This guideline is very much a work-in-progress.
Contributions to timm for code, documentation, tests are more than welcome!
There haven't been any formal guidelines to date so please bear with me, and feel free to add to this guide.
Code linting and auto-format (black) are not currently in place but open to consideration. In the meantime, the style to follow is (mostly) aligned with Google's guide: https://google.github.io/styleguide/pyguide.html.
A few specific differences from Google style (or black)
- Line length is 120 char. Going over is okay in some cases (e.g. I prefer not to break URL across lines).
- Hanging indents are always preferred, please avoid aligning arguments with closing brackets or braces.
Example, from Google guide, but this is a NO here:
# Aligned with opening delimiter.
foo = long_function_name(var_one, var_two,
var_three, var_four)
meal = (spam,
beans)
# Aligned with opening delimiter in a dictionary.
foo = {
'long_dictionary_key': value1 +
value2,
...
}This is YES:
# 4-space hanging indent; nothing on first line,
# closing parenthesis on a new line.
foo = long_function_name(
var_one, var_two, var_three,
var_four
)
meal = (
spam,
beans,
)
# 4-space hanging indent in a dictionary.
foo = {
'long_dictionary_key':
long_dictionary_value,
...
}While preferred timm style is mostly compatible with Black / Ruff. Since I've been following PEP 8 style since before Black was a thing, there's one area I can't agree on, function arg indents. From a Black example this:
def very_important_function(
template: str,
*variables,
file: os.PathLike,
engine: str,
header: bool = True,
debug: bool = False,
):
with open(file, "w") as f:
...Should according to PEP 8 (https://peps.python.org/pep-0008/#indentation) have an extra level of indent on the args:
def very_important_function(
template: str,
*variables,
file: os.PathLike,
engine: str,
header: bool = True,
debug: bool = False,
):
with open(file, "w") as f:
...I do like sadface though. So please don't run Black on existing files and convert all of the arg indents. Thanks!
When there is discrepancy in a given source file (there are many origins for various bits of code and not all have been updated to what I consider current goal), please follow the style in a given file.
Please avoid formatting code that is unrelated to your PR.
PR with pure formatting / style fixes will be accepted but only in isolation from functional changes, best to ask before starting such a change.
As with code style, docstrings style based on the Google guide: guide: https://google.github.io/styleguide/pyguide.html
The goal for the code is to eventually move to have all major functions and __init__ methods use PEP484 type annotations.
When type annotations are used for a function, as per the Google pyguide, they should NOT be duplicated in the docstrings, please leave annotations as the one source of truth re typing.
There are a LOT of gaps in current documentation relative to the functionality in timm, please, document away!
Create a Python virtual environment using Python 3.10. Inside the environment, install torchandtorchvision` using the instructions matching your system as listed on the PyTorch website.
Then install the remaining dependencies:
python -m pip install -r requirements.txt
python -m pip install -r requirements-dev.txt # for testing
python -m pip install -e .
Run the tests using:
pytest tests/
Since the whole test suite takes a lot of time to run locally (a few hours), you may want to select a subset of tests relating to the changes you made by using the -k option of pytest. Moreover, running tests in parallel (in this example 4 processes) with the -n option may help:
pytest -k "substring-to-match" -n 4 tests/
Please refer to this document.
If you have any questions about contribution, where / how to contribute, please ask in the Discussions (there is a Contributing topic).