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.
- 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.
.devcontainer/
: Contains Docker configurations for the development environment, including aDockerfile
anddevcontainer.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:
-
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
orCmd+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. - Open the Command Palette (
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.