README.md

Python Starting Project

A comprehensive learning template for Python applications with modern tools and best practices.

If you know uv ,git, and cursor/VSCODE, and have python 3.11+ installed, just run the 4 commands below:

uv sync
uv venv
pre-commit install
# to run prehooks locally
poe pre

Quick Setup

Prerequisites

• Python 3.11+ installed on your system
• Git installed on your system
• Basic command-line knowledge

Step 1: Install UV Package Manager

UV is a blazing-fast Python package manager written in Rust.

For MacOS/Linux:

1. Install Cursor - AI-powered code editor
2. Install UV - Modern Python package manager

Verify installation with:

uv --version

Step 2: Set Up Your Project

You can either start from our template or clone the repository directly:

Option A: Use GitHub Template

1. Go to the Python Starting Project
2. Click the green "Use this template" button
3. Choose "Create a new repository"
4. Fill in your repository details
5. Clone your new repository:

   git clone https://github.com/your-username/your-repo-name.git
   cd your-repo-name

Option B: Direct Clone

git clone https://github.com/dhkts1/Python-Starting-Project
cd Python-Starting-Project

Step 5: Install Dependencies and Create Virtual Environment

uv sync

Step 6: Set Up Pre-commit Hooks (all the format, linting, testing, etc tools that will run automatically when you commit)

# Install pre-commit hooks
pre-commit install

Step 7: Verify Your Setup

# Run all pre-commit checks
poe pre

Step 8: Run the Sample Application

# Run the main script
python -m src.main

You're all set! Start developing with confidence.

⚠️ WARNING: This template configures most tools at their maximum strictness level. It is designed for new projects where you want to follow strict standards from the beginning.

Purpose

This project serves as both a starting template and a learning tool for Python development best practices:

• Modern Python Tools: Learn to use cutting-edge tools like Ruff, Pyright, and UV
• Code Quality: Experience best practices for linting, testing, and documentation
• Project Structure: Learn how to organize a Python project properly
• CI/CD Integration: See how automated workflows improve code quality

Documentation

For detailed information and guides, check out the project documentation:

• Getting Started: Detailed setup and usage instructions
• Tutorial: Setup Your First Project: Step-by-step tutorial
• Why: The story behind this project
• Architecture: Configuration, logging, and project structure
• Development: Workflow, pre-commit hooks, and best practices
• API Reference: Detailed code documentation

Project Status

This project is actively maintained and monitored for code quality through various metrics:

Code Quality

Testing & Documentation

Code Maintainability

Tools

These badges are updated automatically by our CI/CD pipeline and reflect the current status of the project.