1/20/2017 - 3:16 PM

What every Python project should have From:

What every Python project should have


Firstly, the requirements.txt file is crucial for the sanity of those who want to install your project. It is basically a text file which contains the dependencies to be installed via pip, one per line.

It is that simple. And that powerful.

You can also have multiple requirements.txt files that serve different purposes. For example, you can have a requirements.txt that have general dependencies listed that your project need to run, a requirements_dev.txt where you have listed some dependencies that enable some debugging mechanisms and a requirements_docs.txt that has listed some requirements that are used when generating the documentation (such as Sphinx and the desired theme).

A file is crucial for your project if you want to be installable via pip. It is easy to write, very configurable and takes care of a lot of things such as importing, project metadata, updating the sources, installing the dependencies, and much more.

You can check the setuptools documentation for more information on this.

A proper structure

The project structure is crucial. With a well organized structure, it will e easier to organize things, locate certain source files and encourages other people to contribute.

The root project directory should have a structure similar to


Of course, this is not the only way to organize your project, but this certainly is the most used template.


Unit testing is crucial for your project. It allows you to be confident in the stability of your code. I recommend the unittest module for this job as it is built in and is flexible enough to get the job done right.

There are also other libraries that can be used for testing your project, such as or nose.


If you develop a project, I am sure that you don't write it just for yourself. Other people must know how to use your project properly. And even if you write the project only for yourself (although beats the purpose of open source), after a while of not developing it and when you come back to it, you will surely not remember anything that is going on in your code (or API).

So, in order to achieve a reusable code base, you should:

  • design a sane API that is easy to use and remember
  • the same sane API should be flexible enough to allow easy configurations
  • document the most relevant use-cases
  • don't try to fit all cases. It should fit only the most usual 80% of cases.

In order to properly document your code, you should use a tool specialized for that job, such as Sphinx or mkdocs, so that you can generate nice-looking documentation with proper reference links by writing in a popular markup language designed just for that (rst or markdown).


After you familiarize yourself with the topics described above, you will surely be able to produce nice structured projects and libraries that comply to the community standards. And don't forget to ALWAYS use PEP-8!