Python Project Standards / Datum Brain
This repository contains the company-wide standard configuration files and project structure for Python projects at DatumBrain. These standards ensure consistency, maintainability, and quality across all Python projects.
๐ Overview
This template provides a standardized setup for Python projects including:
- Code quality tools (Ruff, Black, MyPy)
- Testing framework (Pytest with coverage)
- Project structure (src layout)
- Configuration files (pyproject.toml, .gitignore, .editorconfig)
๐ Quick Start
Using this Template
-
Clone this repository as a template for your new project:
git clone https://github.com/datumbrain/python-template your-project-name
cd your-project-name
-
Update project-specific details:
- Rename
src/your_package_name to your actual package name
- Update package name references in
pyproject.toml
- Update author information and project metadata
-
Install Poetry (if not already installed):
curl -sSL https://install.python-poetry.org | python3 -
-
Install dependencies:
-
Activate the virtual environment:
๐ Project Structure
.
โโโ src/ # Source code directory
โ โโโ your_package_name/ # Your main package
โ โโโ __init__.py # Package initialization
โโโ tests/ # Test directory
โ โโโ __init__.py # Test package initialization
โ โโโ conftest.py # Pytest configuration and fixtures
โโโ .editorconfig # Editor configuration for consistency
โโโ .gitignore # Git ignore patterns
โโโ pyproject.toml # Project configuration and dependencies
โโโ README.md # Project documentation
Directory Explanations
src/: Contains all production code. Using src layout prevents accidentally importing from the repository root.
tests/: Contains all test files. Tests should mirror the structure of the src directory.
.editorconfig: Ensures consistent coding styles between different editors and IDEs.
pyproject.toml: Central configuration file for the project, including dependencies, build system, and tool configurations.
๐ ๏ธ Configuration Files
pyproject.toml
The pyproject.toml file is the central configuration hub containing:
- Project metadata: Name, version, description, authors
- Dependencies: Using Poetry for dependency management
- Tool configurations:
- Ruff: Fast Python linter and formatter
- MyPy: Static type checking
- Pytest: Testing framework configuration
- Coverage: Code coverage settings
- Black: Code formatting (optional, alongside Ruff)
.gitignore
Comprehensive gitignore file covering:
- Python artifacts (
__pycache__, *.pyc, etc.)
- Virtual environments (
venv, .venv, etc.)
- IDE files (
.idea, .vscode)
- Test and coverage reports
- OS-specific files (
.DS_Store, Thumbs.db)
.editorconfig
Standardizes:
- Character encoding (UTF-8)
- Line endings (LF for Unix-style)
- Indentation (4 spaces for Python)
- Trailing whitespace handling
- File-specific settings for YAML, JSON, Markdown, etc.
๐งฐ Development Tools
Code Quality
Ruff (Linting and Formatting)
# Run linter
poetry run ruff check .
# Fix auto-fixable issues
poetry run ruff check --fix .
# Format code
poetry run ruff format .
MyPy (Type Checking)
Black (Alternative Formatter)
poetry run black src tests
Testing
Run Tests
# Run all tests
poetry run pytest
# Run with coverage
poetry run pytest --cov
# Run specific test file
poetry run pytest tests/test_module.py
# Run tests in parallel
poetry run pytest -n auto
Test Markers
# Run only unit tests
poetry run pytest -m unit
# Skip slow tests
poetry run pytest -m "not slow"
# Run integration tests
poetry run pytest -m integration
Pre-commit Hooks
Set up pre-commit hooks to automatically run checks before commits:
# Install pre-commit
poetry add --group dev pre-commit
# Create .pre-commit-config.yaml
cat > .pre-commit-config.yaml << EOF
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.1.0
hooks:
- id: ruff
args: [--fix]
- id: ruff-format
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.5.0
hooks:
- id: mypy
additional_dependencies: [types-all]
EOF
# Install the git hook scripts
poetry run pre-commit install
# Run against all files (first time)
poetry run pre-commit run --all-files
๐ Coding Standards
Style Guide
- Line Length: 88 characters (Black/Ruff default)
- Indentation: 4 spaces
- Quotes: Double quotes for strings
- Imports: Sorted and grouped (via Ruff/isort)
- Docstrings: Google style convention
Type Hints
All new code should include type hints:
def calculate_total(items: list[float], tax_rate: float = 0.1) -> float:
"""Calculate total with tax.
Args:
items: List of item prices.
tax_rate: Tax rate to apply.
Returns:
Total amount including tax.
"""
subtotal = sum(items)
return subtotal * (1 + tax_rate)
Testing Standards
- Minimum 80% code coverage
- Tests organized in
tests/ mirroring src/ structure
- Use pytest fixtures for reusable test data
- Descriptive test names:
test_<function>_<scenario>_<expected_outcome>
๐ Workflow
Development Workflow
-
Create a feature branch:
git checkout -b feature/your-feature-name
-
Make your changes in src/
-
Write/update tests in tests/
-
Run quality checks:
poetry run ruff check .
poetry run ruff format .
poetry run mypy src
poetry run pytest --cov
-
Commit your changes:
git add .
git commit -m "feat: add your feature description"
-
Push and create a pull request
Commit Message Convention
Follow conventional commits:
feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting)
refactor: Code refactoring
test: Test changes
chore: Build process or auxiliary tool changes
๐ฆ Building and Publishing
Building the Package
This creates distribution files in the dist/ directory.
Publishing to PyPI
# Configure PyPI token
poetry config pypi-token.pypi your-token
# Publish
poetry publish
Publishing to Private Repository
# Configure private repository
poetry config repositories.private https://your-repo-url
poetry config http-basic.private username password
# Publish
poetry publish -r private
๐ Common Tasks
Adding Dependencies
# Add production dependency
poetry add package-name
# Add development dependency
poetry add --group dev package-name
# Add specific version
poetry add package-name@^2.0.0
Updating Dependencies
# Update all dependencies
poetry update
# Update specific package
poetry update package-name
Virtual Environment
# Activate virtual environment
poetry shell
# Run command in virtual environment
poetry run python script.py
# Show environment info
poetry env info
๐ Resources
๐ค Contributing
When contributing to projects using this template:
- Follow the established project structure
- Ensure all tests pass
- Maintain or improve code coverage
- Follow the coding standards
- Update documentation as needed
๐ License
This template is available for all DatumBrain projects. For specific project licenses, check the individual repository.
Maintained by: Engineering Team / Datum Brain
Last updated: 2025-08-28 16:30:05