Skip to content

A modern Python project template with essential tooling for development, testing, and documentation.

License

Notifications You must be signed in to change notification settings

ross-tsenov/python-project-template

Repository files navigation

README for Python Project Template

This Python Project Template is designed to streamline the development process, focusing on best practices, code quality, and documentation. It employs a variety of tooling and a structured folder layout to ensure maintainability and ease of use. Below is an overview of its key components, tooling, folder structure, and useful commands to get you started.

Tooling

  • Poetry: Used for dependency management and packaging, making it simple to manage project libraries and their versions.
  • Pydantic Settings: Loads and validates settings from .env files, ensuring configurations are both accessible and correctly typed.
  • Ruff: A fast and comprehensive linter that checks for syntax errors and enforces style consistency.
  • Mypy: A static type checker for Python, enhancing code quality and detect errors before runtime.
  • Pytest: The go-to framework for writing and running tests, ensuring your code behaves as expected.
  • Pre-commit: Runs a series of checks (linting, formatting, type checking) before each commit to maintain code quality.
  • MkDocs: Generates project documentation from Markdown files, making it easy to create and maintain up-to-date documentation.
  • Simple Logger: A basic logging implementation that can be easily customized and integrated throughout the project.
  • Devcontainer: Supports development inside a Docker container in VSCode or GitHub Codespaces, providing a consistent and isolated development environment.
  • GitHub Actions: Automates linting, type checking, and testing workflows, ensuring that code meets quality standards before merging.

Folder Structure

  • .devcontainer/: Contains Docker configurations for the development environment, including a Dockerfile and devcontainer.json for container settings.
  • .github/workflows/: Stores CI configurations for automated linting, typing, and testing. It's extendable for additional workflows.
  • docs/: Holds MkDocs structured documentation, serving as the home for project documentation.
    • docs/assets/: Stores images and other assets for the documentation.
  • scripts/: Typically includes utility bash scripts.
  • src/: The primary directory for project source code.
    • src/settings.py: Manages application settings loaded and validated from .env.
    • src/logger.py: Provides a global logger accessible throughout the project.
  • tests/: Contains test cases and fixtures for the project.
    • tests/conftest.py: Defines reusable pytest fixtures.
    • tests/core.py: Tests core functionalities like settings and logging.
  • .env.sample: An example .env file outlining required environment variables.
  • .gitignore: Specifies intentionally untracked files to ignore.
  • .pre-commit-config.yaml: Configures checks to run before commits.
  • main.py: The entry point for running the application.
  • mkdocs.yml: Configuration for MkDocs.
  • pyproject.toml: Specifies project settings, dependencies, and build information.

Sure, here are the useful commands with code blocks for better readability:

Useful Commands

  • Poetry Commands

    Install dependencies:

    poetry install [--with dev] [--with docs]
  • Pre-commit Commands

    Install pre-commit hooks:

    pre-commit install

    Run all pre-commit hooks:

    pre-commit run --all-files
  • Mypy Commands

    Run type checking:

    mypy src/ tests/
  • Pytest Commands

    Run tests:

    pytest tests
  • MkDocs Commands

    Serve documentation locally:

    mkdocs serve

    Build static site:

    mkdocs build
  • Devcontainer Command

    To use the devcontainer, if you are using VSCode, follow these steps:

    • Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on macOS).
    • Type and select "Remote-Containers: Open Folder in Container".

    Alternatively, if you are using GitHub Codespaces, it will automatically use the .devcontainer configuration when you create a new codespace.

This project template is equipped with a robust set of tools and a clear structure to help you start your Python project on the right foot. Adjust and extend it as needed to fit your project requirements.