What is the convention for structuring Python modules?

Python module structuring follows established conventions that make projects maintainable, distributable, and easy to navigate. Here's the standard structure used by most Python projects.

Standard Python Project Structure

Here is a sample project that shows a very good way to structure your projects: https://github.com/kennethreitz/samplemod

The project is about creating the "sample" module. The directory structure looks as follows ?

README.rst
LICENSE
setup.py
requirements.txt
sample/__init__.py
sample/core.py
sample/helpers.py
docs/conf.py
docs/index.rst
tests/test_basic.py
tests/test_advanced.py

File and Directory Explanations

README.rst

This file provides a brief description of the module, how to set it up, how to use it, installation instructions, and basic usage examples. It's the first file users see when visiting your project.

LICENSE

Contains license text and any copyright claims. This file specifies how others can use, modify, and distribute your code.

setup.py

It is Python's answer to a multi-platform installer and makes file. If you're familiar with command-line installations, then make && make install translates to python setup.py build && python setup.py install. It is used to build your project on the user machine and handle package distribution.

requirements.txt

A Pip requirements file should specify the dependencies required to contribute to the project: testing, building, and generating documentation. If your project has no development dependencies, or you prefer development environment setup via setup.py, this file is unnecessary.

docs/ Directory

This directory contains the documentation for your project. Typically uses Sphinx for generating HTML documentation from reStructuredText files.

tests/ Directory

All your tests should reside in this directory. Initially, you'll have a single test file. As they start to grow, you can structure your tests like your module directory with separate test files for different components.

sample/ Directory

This directory contains your actual module code. If your module consists of only a single file, you can place it directly in the root of your repository as sample.py. Your library does not belong in an ambiguous src or python subdirectory. This will contain an __init__.py file if you want this module to reside within a package.

Best Practices

Conclusion

Following this conventional structure makes your Python projects professional, maintainable, and familiar to other developers. The key is keeping your actual module code in a dedicated directory, separating tests and documentation, and including proper metadata files for distribution.