/somepackage

Show how to structure a Python project.

Primary LanguagePythonMozilla Public License 2.0MPL-2.0

https://travis-ci.org/bast/somepackage.svg?branch=master

Somepackage

Show how to structure a Python project.

Inspired by https://github.com/kennethreitz/samplemod.

Great resources

Recommendations

Please browse this blog post for a good summary of recommendatios and templates: https://medium.com/@jonas.r.kemper/understanding-best-practice-python-tooling-by-comparing-popular-project-templates-6eba49229106

Python 2 or 3?

  • Develop your code under Python 3, test it for both Python 2 and Python 3 but consider Python 3 to be the default today.

Split your code into packages, modules, and functions

  • All code should be inside some function (except perhaps if __name__ == '__main__':).
  • Split long functions into smaller functions.
  • If you need to scroll through a function over several screens, it is probably too long.
  • Functions should do one thing and one thing only.
  • Hide internals with underscores.
  • Organize related functions into modules.
  • If modules grow too large, split them.
  • Import from other modules under somepackage/ using from .somemodule import something.
  • Do file I/O on the "outside" of your code, not deep inside.

Classes vs. functions

  • Do not overuse classes.
  • Prefer immutable data structures.
  • Prefer pure functions.

Naming

  • Give the subdirectory the same name as your package.
  • Before you name your package, check that the name is not taken on https://pypi.org (you may want to upload your package to PyPI one day).

Interfaces

  • In somepackage/__init__.py define what should be visible to the outside.
  • Use https://semver.org.

Testing

Dependency management

  • Package dependencies for developers should be listed in requirements.txt.
  • Alternatively, consider using http://pipenv.readthedocs.io.
  • Package dependencies for users of your code (who will probably install via pip) should be listed in setup.py.

Code style

Type checking

Share your package

Documentation

I used to recommend reStructuredText for READMEs in contrast to Markdown but PyPI no longer requires reStructuredText. You can use Markdown as noted on https://pypi.org/help/ under "How can I upload a project description in a different format?".

Example shown here: https://packaging.python.org/tutorials/packaging-projects/#creating-setup-py

Suggestions? Corrections? Pull requests?

Yes please!