Project Structure¶

This document provides an overview of key Python project structure elements and their implications for end users.

Essentials¶

This template uses the following high-level project structure:

📁 python/
├── 📄 pyproject.toml
├── 📄 ...
├── 📁 src/
│   └── 📁 ${namespace}/
│       └── 📁 ${component}/
│           └── 📄 ...
└── 📁 tests/
    └── 📄 ...

pyproject.toml¶

The pyproject.toml file is the standard configuration format for modern Python projects.

It centralizes configuration for:

• Project metadata (e.g., authors and contact information)
• Dependencies
• Build system integration
• Third-party tools

Build systems managed through this file include poetry, hatch, pdm, and our choice, uv.

Other commonly configured tools include:

• Formatters (e.g., Black, Ruff)
• Linters (e.g., Pylint, Ruff)
• Type checkers (e.g., MyPy, Pyright)
• Test frameworks (e.g., pytest)

Namespace¶

"Namespace packaging" allows for the distribution of independent but related packages under a shared namespace.

For example, using jambazid as the namespace:

from jambazid.cache import redis_cache
from jambazid.openapi import oas3_redactor
from jambazid.siem.opentelemetry import instrument_opentelemetry

These features can be developed in separate repositories but distributed under a unified namespace reflecting the author or organization.

Installation mappings typically follow this pattern:

This enables users to install only the specific components they need from a broader ecosystem.

Prominent examples of namespace packages include:

• OpenTelemetry
• Azure
• Google

Build System¶

The complete file structure includes additional files and directories that are not essential for the basic functionality of the package. These files and directories are used by the build system for development, testing, and documentation purposes.

📁 python/
├── 📄 README.md
├── 📄 ...
├── 📄 pyproject.toml
├── 📄 ...
├── 📄 .python-version
├── 📄 ...
├── 📄 uv.lock
├── 📄 ...
├── 📄 zensical.toml
├── 📄 ...
├── 📄 .gitignore
├── 📄 ...
├── 📁 src/
│   └── 📁 ${namespace}/
│       └── 📁 ${component}/
│           ├── 📄 __init__.py
│           ├── 📄 module.py
│           ├── 📄 ...
│           ├── 📁 sub_package/
│           │   ├── 📄 __init__.py
│           │   ├── 📄 sub_module.py
│           │   └── 📄 ...
│           └── 📁 data/
│               └── 📄 ...
└── 📁 tests/
    ├── 📁 data/
    │   └── 📄 ...
    ├── 📄 conftest.py
    ├── 📄 ...
    └── 📁 test_${component}/
        ├── 📄 test_module.py
        └── 📄 ...

Tests¶

Tests are implemented using the pytest framework.

This template uses the standard convention of placing tests outside the application source code. Consequently, test files are excluded from the built distribution:

📁 python/
├── 📄 ...
├── 📁 src/
└── 📁 tests/