2.2.7. Structuring Python projects¶
We recommend using the following principles to organize Python projects:
Use a separate repository for each project
Store only one package in each repository
Structure each package as outlined below, following the recommendations provided by The Hitchhiker’s Guide To Python:
repository_name/ # source code directory (1) __init__.py # each source code directory must contain an __init__.py file __main__.py # optional, for command line programs _version.py # file with version number data/ # directory for data files needed by the code tests/ # directory for test code fixtures/ # fixtures for tests secret/ # git-ignored fixtures containing usernames, passwords, and tokens requirements.txt # list of packages required to run the tests, but not # required by the project; used by CircleCI (2, 3) docs/ # directory for documentation conf.py # documentation configuration index.rst # main documentation file requirements.txt # packages required to compile the documentation (2, 3) requirements.rtd.txt # list of packages required to compile the documentation; # used by Read the Docs (2) _build/html/ # directory where compiled documentation is saved _static # optional for static files such as .css and .js files # needed for the documentation examples/ # (optional) directory for examples of how to use the code LICENSE # license file MANIFEST.in # list of files that should be distributed with the package README.md # Read me file; displayed by GitHub requirements.txt # list of required packages (2, 3) requirements.optional.txt # list of optional requirements (2, 3) setup.cfg # options for the installation script setup.py # installation script .circleci/ # directory for CircleCI configuration config.yml # CircleCI configuration requirements.txt # list of locations of requirements not in PyPI (2, 3) downstream_dependencies.yml # List of downstream dependencies in YAML format (3) .gitignore # list of file paths and extensions that Git should ignore .readthedocs.yml # Read the Docs configuration
(1) The name of the source code directory should be the same as that of the repository.
(2) For details about requirements.txt files see the section about Changing package dependencies for a CircleCI build.
(3) These dependencies can be determined automatically by karr_lab_build_utils.
Separate code that is useful on its own—distinct from the project, into independent packages and repositories.