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.