= Python Packaging Best Practices =

Slightly opinionated, but nevertheless informed (imho) list of Python Packaging Best Practices, based on copious amounts of experience with many diverse Python projects, as a user and a packager.

This list seeks to be "tool" (solution) agnostic where possible, and describe things in terms of needs and outcomes, with the driving motivations being:

 * PEP20 relevant (obvious, explicit, etc)
 * Reducing friction, saving (everyone) time.
 * Making your software easy to consume
 * Encouraging contributions to your software
 * Transcending the "downstream vs upstream divide"

We'll flesh out the motivations and caveats later.

Note: ```setup.py``` means setup.py or setup.cfg or other equivalent ``one place that has your package metadata``.

== Cheatsheet ==

=== General ===

 * Have a clear LICENSE
  * Pick a well-defined existing LICENSE.
  * Have a LICENSE file in your repository
  * Include LICENSE file to the source distribution (sdist). Use ```MANIFEST.in``` or ```setup.py:data_files```
  * Define LICENSE in ```setup.py:license```

 * Clearly declare exact Python version support. ```setup.py:python_requires```. This should ''at least'' match your CI coverage.

=== Dependencies ===

 * Declare all dependencies in one place, in one way. This includes optional (```setup.py:extras_require```) and test dependencies (```setup.py:tests_require```)
 * Put development dependencies in ```extras_require[dev]```, not `tests_require```. They are not compulsory.
  * Understand the distinctions between development and user testing (eg: the latter doesn't want/need coverage, pylint, pep8 etc).
 * Use `>=` version specs for '''distribution''' dependencies.
  * Understand the distinctions between packaging and deployment (pinned) dependencies.
  * Use these for development testing too. This makes sure issues are picked up in development '''early''', and '''before''' releases/users.
  * Use the '''lowest''' supported version of a dependency that your code '''requires'''.

=== Tests ===

 * Have a '''HOW TO RUN TESTS''' section in your README in the repository root. Noone should need to go looking.
 * Have '''one''' entry point, and ideally one command to run tests.
 * Include tests, test data files, and test ''related'' files in the source distribution. Use ```MANIFEST.in``` and/or ```setup.py:packages```
 * Tests that need some external thing (package, file, environment) SKIP not FAIL if that test requirement is not fulfilled.
 * Run tests using the the source distribution. This gets you coverage of the user test scenario and tests the complete packaging pipeline.