getting-started.md

Python Starting Project

!!! note "New Documentation Structure"

This content is being migrated to a more learning-focused structure. See:

- [Beginner's Guide](learning-path/beginners-guide.md)
- [Setup Tutorial](tutorials/setup-your-first-project.md)

The original content will remain available until the migration is complete.

A comprehensive Python project template with built-in logging, configuration management, and development tools. This template provides a solid foundation for building Python applications with best practices for configuration, logging, code quality, and project structure.

Features

• Structured project layout with src-based architecture
• Logging configuration with console and file output
• Settings management using pydantic-settings
• Environment variable support with .env file override capability
• Lazy loading for improved import performance
• Comprehensive testing with pytest
• Code quality tools:
  • Ruff for linting and formatting
  • Pyright for static type checking
  • Bandit for security checks
  • Vulture for dead code detection
  • Interrogate for docstring coverage
  • Darglint for docstring validation
• GitHub Actions for CI/CD with pre-commit checks
• Comprehensive badge system with dynamic quality indicators
• Documentation with MkDocs for beautiful, searchable documentation

Prerequisites

• Python 3.11 or higher
• uv for dependency management (recommended)
• An IDE: either Visual Studio Code or Cursor (recommended for AI-assisted development)

Installation

Important: Do not skip these steps!

# Clone the repository
git clone https://github.com/yourusername/python-starting-project.git
cd python-starting-project

# Install dependencies
uv sync

# Install pre-commit hooks:
uv venv
pre-commit install

# Run pre-commit hooks to verify everything works:
poe pre

Project Structure

The project follows a modular architecture with clear separation of concerns:

python-starting-project/
├── src/                  # Main source code
│   ├── utils/            # Utility modules
│   │   ├── settings.py   # Application settings
│   │   └── logging.py    # Logging configuration
│   ├── __init__.py       # Package initialization with lazy loading
│   └── main.py           # Application entry point
├── tests/                # Test directory
│   ├── unit/             # Unit tests
│   └── conftest.py       # Pytest configuration
├── docs/                 # Documentation files
│   ├── api/              # API reference documentation
│   ├── architecture/     # Architecture documentation
│   └── development/      # Development guides
├── .github/              # GitHub configuration
│   └── workflows/        # GitHub Actions workflows
│       └── ci.yml        # CI workflow with dynamic badges
├── .vscode/              # Editor configuration
├── mkdocs.yml            # MkDocs configuration
├── pyproject.toml        # Project configuration
├── .pre-commit-config.yaml # Pre-commit hooks configuration
└── .env.example          # Example environment configuration

Simplified Workflow

This project is designed to have a minimal learning curve. You only need to know 4 commands for the entire development cycle:

1. uv sync

This command installs or updates all project dependencies:

uv sync

When to use it:

• When you first clone the repository
• When dependencies are updated in pyproject.toml
• When switching to a branch with different dependencies

2. uv venv

Same as source .venv/bin/activate, it enters to the context of the virtual environment. and allows you to use the tools installed in the virtual environment.

uv venv

3. pre-commit install

This command sets up the pre-commit hooks that automatically check your code quality before each commit:

pre-commit install

When to use it:

• Only once after cloning the repository
• If you need to reinstall the pre-commit hooks

3. git add

This command stages your changes for commit:

# Add specific files
git add filename.py

# Add all changes
git add .

When to use it:

• After making changes you want to commit

4. git commit

This command commits your staged changes:

git commit -m "Add new feature"

When to use it:

• After staging your changes with git add
• The pre-commit hooks will automatically run before the commit is created
• If any hooks fail, the commit will be aborted until you fix the issues

Complete Workflow Example

# Initial setup (only once)
uv sync
uv venv
pre-commit install

# Development cycle (repeat as needed)
# 1. Make changes to your code
# 2. Stage changes
git add .
# 3. Commit changes (pre-commit hooks run automatically)
git commit -m "Add new feature"
# 4. to run all github hooks without committing use
poe pre

That's it! With just these 4 commands, you can handle the entire development workflow while maintaining high code quality standards.

!!! warning "For pip Users"

If you're coming from a traditional pip workflow, here's how commands compare:

| pip Command                       | UV Equivalent    | Description          |
| --------------------------------- | ---------------- | -------------------- |
| `pip install -r requirements.txt` | `uv sync`        | Install dependencies |
| `pip install package`             | `uv add package` | Install a package    |

**Important:** This project uses `pyproject.toml` instead of `requirements.txt`. Think of it as requirements.txt on steroids:

- It defines project metadata, dependencies, dev dependencies, and build configuration in one file
- It's standardized (PEP 621) and works with any modern Python tooling
- It supports precise version specifications and dependency groups
- It's used by the build system, linters, formatters, and other tools

While you could still use pip with this project, you'd miss out on the benefits of modern Python tooling like faster installations, better dependency resolution, and integrated development workflows.

IDE Integration

The project is configured to work with both VSCode and Cursor:

VSCode Integration

For the best development experience with VSCode:

1. Open the project in VSCode
2. Install recommended extensions when prompted
3. Use the integrated terminal for running commands
4. Use the built-in debugger for debugging

Cursor Integration

Cursor provides all VSCode features plus AI-assisted development:

1. Open the project in Cursor
2. Cursor will automatically use the project's settings and extensions
3. Enable AI features in Cursor settings, MCP, YOLO MODE, etc.
4. Install ALL the extensions of the project
5. Use AI features to help with code completion, refactoring, and documentation. especially the agent. mnj
6. Use AI features to help with code completion, refactoring, and documentation

Next Steps

• Explore the Architecture documentation
• Learn about Pre-commit Hooks
• Check out the API Reference