Need help with somepackage?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

382 Stars 73 Forks Mozilla Public License 2.0 45 Commits 1 Opened issues


Show how to structure a Python project.

Services available


Need anything else?

Contributors list

# 43,743
45 commits

.. image:: :target: .. image:: :target: ../master/LICENSE


Show how to structure a Python project.

Inspired by

Great resources



Please browse this blog post for a good summary of recommendatios and templates:

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
    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.


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


  • In
    define what should be visible to the outside.
  • Use


  • Test all non-trivial code. I recommend to use
  • Use Travis CI:

Dependency management

  • Package dependencies for developers should be listed in
  • Alternatively, consider using
  • Package dependencies for users of your code (who will probably install via pip) should be listed in

Code style

  • Follow PEP8:
  • Use
    to automatically check for PEP8.

Type checking

  • Consider using type hints:
  • Consider using
  • Consider verifying type annotations at runtime:

Share your package

  • Choose a license and add a LICENSE file.
  • Share your package on PyPI. For this you can follow


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

Example shown here:

Suggestions? Corrections? Pull requests?

Yes please!

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.