The project structure is the way you organize all the files inside a folder in a way that the project best accomplishes the objectives. We are going to start with a .py script (sampleproject.py) that should be with other files in order to complete the information about this script – dependencies, license, how to install it, or how to test it. A common approach for structuring this basic project is as follows:
sampleproject/
│
├── .gitignore
├── sampleproject.py
├── LICENSE
├── README.rst
├── requirements.txt
├── setup.py
└── tests.py
sampleproject.py—if your project is only a single Python source file, then put it into the directory and name it something related to your project.
The README (.rst or .md extension) is used to register the main properties of the project, which should cover, at least, the following:
- What your project does
- How to install it
- Example usage
- How to set up the dev environment
- How to ship a change
- Change log
- License and author info
A template you can use can be downloaded from this GitHub repository: https://github.com/dbader/readme-template. For further information, please see https://dbader.org/blog/write-a-great-readme-for-your-github-project.
The LICENSE.md document contains the applicable license. This is arguably the most important part of your repository, aside from the source code itself. The full license text and copyright claims should exist in this file. It is always a good idea to have one if you are distributing code. Typically, the GNU General Public License (GPL) (http://www.gnu.org/licenses/gpl.html) or the MIT license (https://opensource.org/licenses/MIT) are used in open source projects. You can check out http://choosealicense.com/ if you are not sure which license should be applied to your project.
A requirements.txt pip requirements file (https://pip.pypa.io/en/stable/user_guide/#requirements-files) should be placed at the root of the repository, which is used to specify the dependencies required to contribute to the project. The requirements.txt file can be generated using the following:
$ pip freeze > requirements.txt
To install these requirements, you can use the following command:
$ pip install -r requirements.txt
The setup.py file allows you to create packages you can redistribute. This script is meant to install your package on the end user's system, not to prepare the development environment as pip install -r < requirements.txt does. It is a key file because it defines information of your package (such as versioning, package requirements, and the project description).
The tests.py script contains the tests.
The .gitignore file tells Git what kind of files to ignore, such as IDE clutter or local configuration files. You can find sample .gitignore files for Python projects at https://github.com/github/gitignore.