Python Template Project

A basic Python template project demonstrating a simple module with arithmetic operations, set up with uv for dependency management, pytest for testing, mypy for type checking, and ruff for linting.

Getting Started

This section outlines how to set up and use this repository, including necessary configurations for development.

Prerequisites

Ensure you have uv installed. If not, you can install it via pip:

pip install uv

Installation

1. Clone the repository:

   git clone https://github.com/jumtra/python-template.git
   cd python-template

2. Create and activate a virtual environment:

   uv venv
   source .venv/bin/activate

3. Install dependencies:

   uv sync

   This command installs all production and development dependencies as defined in pyproject.toml.

Usage

Running the Module

You can import and use the add, subtract, multiply, and divide functions from my_module:

from my_module.main import add, subtract, multiply, divide

result_add = add(5, 3)
print(f"5 + 3 = {result_add}") # Output: 5 + 3 = 8

result_subtract = subtract(10, 4)
print(f"10 - 4 = {result_subtract}") # Output: 10 - 4 = 6

result_multiply = multiply(7, 2)
print(f"7 * 2 = {result_multiply}") # Output: 7 * 2 = 14

result_divide = divide(20, 5)
print(f"20 / 5 = {result_divide}") # Output: 20 / 5 = 4.0

Running the Example Script

To run the example script located at src/my_module/main.py directly:

uv run python src/my_module/main.py

Development

Testing

This project uses pytest for unit testing. Tests are located in the tests/ directory and follow standard pytest conventions.

To run the tests, use pytest:

uv run pytest

This will also generate a coverage report.

Linting, Formatting, and Type Checking

To ensure code quality and consistency, and to adhere to the project's coding standards, run the following commands:

• Linting (Ruff Check):

  uv run ruff check .

• Formatting (Ruff Format):

  uv run ruff format .

• Type Checking (Mypy):

  uv run mypy . --config-file mypy.toml

  It's recommended to run these checks before committing your changes.

Documentation

For more detailed information, please see the main documentation page or the module-specific documentation.

Workflows

This project uses GitHub Actions for CI/CD and other automations. The following workflows are configured:

GitHub Actions Configuration

To ensure the GitHub Actions workflows, especially those integrating with the Gemini API, function correctly, follow these steps:

1. Add Gemini API Key to Repository Secrets:

   • Go to your GitHub repository settings.
   • Navigate to Secrets and variables > Actions.
   • Click on New repository secret.
   • Name the secret GEMINI_API_KEY and paste your Gemini API key as the value.

2. Configure Workflow Permissions:

   • Go to your GitHub repository settings.
   • Navigate to Actions > General.
   • Scroll down to Workflow permissions.
   • Select Read and write permissions and Allow GitHub Actions to create and approve pull requests.
   • Click Save.

• ci.yml: Runs tests, linting, and type checking on every push and pull request.
• pr-review.yml: Provides AI-powered reviews for pull requests.
• gemini-assistant.yml: Integrates a Gemini assistant for repository management.
• issue-triage-automated.yml / issue-triage-scheduled.yml: Automatically labels and triages new issues.
• document-creator.yml: Automatically generates and updates documentation, and creates pull requests for the changes.
• issue-creator.yml: Analyzes Python code for quality issues and automatically creates GitHub issues.