| # Template repository for LLM projects. | |
| ## Introduction | |
| This repository serves as a template for modern Python projects, leveraging the latest features of Python 3.12 and industry-standard tools for development, testing, and packaging. | |
| ## Key Features | |
| - Python 3.12+ compatibility | |
| - Modern dependency management with `uv` | |
| - Code formatting with `black` and `isort` | |
| - Static type checking with `mypy` | |
| - Testing with `pytest` | |
| - Build system using `hatchling` | |
| ## Prerequisites | |
| - Python 3.12 or higher | |
| - `uv` package installer | |
| ## Installation | |
| The only tool you need to install is `uv`. You can install it using `pip`: | |
| ```bash | |
| pip install uv | |
| ``` | |
| `uv` is a modern Python package installer and resolver that offers several benefits over traditional pip. Benefits of using uv: | |
| - Significantly faster installation and resolution of dependencies | |
| - Built-in support for virtual environments | |
| - Improved dependency resolution algorithm | |
| - Written in Rust, offering better performance and memory safety | |
| After `uv` is installed, prefix everything with `uv` or `uvx`: | |
| - `uv pip install` for installing packages. | |
| - `uvx` for running tools, like `uvx black` | |
| ## Development Workflow | |
| 1. Create and activate a virtual environment using `uv`: | |
| ``` | |
| uv venv | |
| source .venv/bin/activate | |
| ``` | |
| 2. Install the project and its dependencies: | |
| ``` | |
| make | |
| ``` | |
| ### Code Formatting | |
| We use `black` and `isort` to maintain consistent code formatting: | |
| ``` | |
| uvx isort src tests | |
| uvx black src tests | |
| ``` | |
| ### Linting and Type Checking | |
| Run static type checking with `mypy`: | |
| ``` | |
| uv run mypy src | |
| ``` | |
| ### Running Tests | |
| Execute the test suite using `pytest`: | |
| ``` | |
| uv run pytest | |
| ``` | |
| ### Building the Project | |
| To build the project, use `hatchling`: | |
| ``` | |
| uvx hatchling build | |
| ``` | |
| ## Configuration | |
| Project configuration is managed through `pyproject.toml`. This includes settings for `black`, `isort`, `mypy`, and `pytest`. | |
| ## Makefile Commands | |
| For convenience, common tasks are automated in the `Makefile`: | |
| - `make install`: Install the project and its dependencies | |
| - `make format`: Run code formatters | |
| - `make lint`: Run linters and type checkers | |
| - `make test`: Run the test suite | |
| - `make build`: Build the project | |
| Run `make help` to see all available commands. | |