Project structure

Python script

Python is a great language for building small helper tools for various different kinds of tasks. Such small tools can be often expressed as a single file Python script.

Here is an example structure for a Python script (aka executable Python module).

In [ ]:
# the content of my_script.py

# imports
import logging

# constants
LOGGER = logging.getLogger()


def magical_function():
    LOGGER.warning('We are about to do some magical stuff')


def main():
    # The actual logic of the script
    magical_function()


if __name__ == '__main__':
    main()

Python package

An example structure for a python project:

my_project/
    README.md
    requirements.txt
    setup.py

    src/
        my_project/
            __init__.py
            my_module.py
            other_module.py

            my_pkg1/
                __init__.py
                my_third_module.py

    tests/
        conftest.py
        test_module.py
        test_other_module.py

        my_pkg1/
            test_my_third_module.py
  • requirements.txt lists the Python packages from which my_project depends on.
    • these can be installed by running pip install -r requirements
  • setup.py is a file in which you include relevant information about your project and the file is also used for packaging your project. Here's a minimal example of a setup.py:
'''Minimal setup.py file'''

from setuptools import setup, find_packages

setup(
    name='my_project',
    version='0.1',
    packages=find_packages(where="src"),
    package_dir={"": "src"})
  • Once you have the setup.py file in place, you can install your project in editable mode by running pip install -e . in the root directory of your project. In editable mode the installed version is updated when you make changes to the source code files.