Standard Python package layout

Installation

To install the package, run the following command in the root directory of the package.

pip install .

To install the package in editable mode, run the following command in the root directory of the package.

pip install -e .

The package can then be used in the following way:

from PackageName import add #add is an example function

Structure

   project_name
   ├── docs
   │   └── Documentation.md
   │   
   ├── examples
   │   └── example.py
   ├── src
   │   └── package_name
   │       └── __init__.py
   ├── tests
   │   ├── __init__.py
   │   └── test_example.py
   ├── .gitignore
   ├── LICENSE.txt
   ├── README.md
   ├── requirements.txt
   └── setup.py

DOCS

This folder contains the documentation of the project. It can be in any format like markdown, pdf, etc. However, markdown is preferred as it is easy to read and write.

Examples

This folder contains the examples of the project. It can be in any format like python script, jupyter notebook, etc. Examples can either use relative imports to make use of the package or can be standalone scripts that bank on the package being installed. Relative imports have been proven to be less flexible and more error prone. We recommend using standalone scripts that import the installed package. Installing the package in editable mode is a good way to make changes to the package and see the changes reflected in the examples. To do this run pip install -e . in the root directory of the package.

src

This folder contains the source code of the package. The Main folder within src should have the same name as the package (see setup.py package name). The package should have an __init__.py file. This file can be empty or can contain the version of the package. The version of the package should be in the format of a string. The package should contain the modules and subpackages that are required for the package. The package should be structured in a way that it is easy to understand and use. The setup.py file has indicated that the package root can be found in the src folder. This is done by setting the package_dir parameter in the setup function to {'': 'src'}. This is a good practice as it allows the package to be installed in a way that is consistent with the package layout.

tests

The tests can be run in two ways. The first way is to run the tests using the unittest module. The second way is to run the tests using the pytest module

unittest

Calling the unittests is quite simple. The following command can be run in the root directory of the package.

python -m unittest -v discover 

This however runs all code from the root directory requiring the imports within the tests to be relative to the root directory. Importing a package from the root directory within the unittest code would therefore look like this:

from src.PackageName.module_name import add #add is an example function

pytest

To run the tests using pytest, the following command can be run in the root directory of the package.

pytest

This however will not always work as the tests are not in the root directory. To run the tests using pytest, the following command can be run in the root directory of the package.

PYTHONPATH=src 
pytest tests/ -v

This puts the src directory in the python path and runs the tests in the tests directory. This allows the tests to import the package in the same way as the package is imported in the examples. Importing a package from the root directory within the pytest code would therefore look like this:

from PackageName.module_name import add #add is an example function

.gitignore

This file contains the files and directories that should be ignored by git. This file is important as it prevents the addition of unnecessary files to the repository. This file should contain the following:

__pycache__

LICENCE

This file contains the licence of the project (i.e MIT).

requirements

This file contains the requirements of the project. This file can be generated using the following command:

pip freeze > requirements.txt

the file looks like this:

numpy==1.19.5
pandas==1.1.5

The file can be installed using the following command:

pip install -r requirements.txt

setup.py

This file contains the metadata of the package. This file should be modified in the case of:

- Changing the version of the package
- Changing the name of the package
- Changing the author of the package
- Changing the author email of the package
- Changing the description of the package
- Changing the long description of the package
- Changing the URL of the package
- Changing the license of the package
- Changing the classifiers of the package
- Changing the keywords of the package
- Changing the packages of the package