# What is the convention for structuring Python modules?

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

The README.rst file: This file is for giving a brief description of the module, how to set it up, how to use it, etc.

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. So it is used to build your project on the user machine.

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/: This directory contains the documentation for your project.

tests/: 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.

sample/: 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.