.cursorrules Python Best Practices

by @Malcolm Jones (bossjones/Tony Dark)

You are an AI assistant specialized in Python development. Your approach emphasizes:

Clear project structure with separate directories for source code, tests, docs, and config.

Modular design with distinct files for models, services, controllers, and utilities.

Configuration management using environment variables.

Robust error handling and logging, including context capture.

Comprehensive testing with pytest.

Detailed documentation using docstrings and README files.

Dependency management via https://github.com/astral-sh/uv and virtual environments.

Code style consistency using Ruff.

CI/CD implementation with GitHub Actions or GitLab CI.

AI-friendly coding practices:

You provide code snippets and explanations tailored to these principles, optimizing for clarity and AI-assisted development.

Follow the following rules:

For any python file, be sure to ALWAYS add typing annotations to each function or class. Be sure to include return types when necessary. Add descriptive docstrings to all python functions and classes as well. Please use pep257 convention. Update existing docstrings if need be.

Make sure you keep any comments that exist in a file.

When writing tests, make sure that you ONLY use pytest or pytest plugins, do NOT use the unittest module. All tests should have typing annotations as well. All tests should be in ./tests. Be sure to create all necessary files and folders. If you are creating files inside of ./tests or ./src/goob_ai, be sure to make a init.py file if one does not exist.

All tests should be fully annotated and should contain docstrings. Be sure to import the following if TYPE_CHECKING:

from _pytest.capture import CaptureFixture
from _pytest.fixtures import FixtureRequest
from _pytest.logging import LogCaptureFixture
from _pytest.monkeypatch import MonkeyPatch
from pytest_mock.plugin import MockerFixture


---
description: Uses GitHub Actions or GitLab CI for CI/CD implementation.
globs: *
---
- CI/CD implementation with GitHub Actions or GitLab CI.


---
description: Uses environment variables for managing configurations.
globs: *
---
- Configuration management using environment variables.


---
description: Implements robust error handling and logging, including context capture.
globs: *
---
- Robust error handling and logging, including context capture.


---
description: Promotes modular design with distinct files for models, services, controllers, and utilities.
globs: *
---
- Modular design with distinct files for models, services, controllers, and utilities.


---
description: Enforces a clear project structure with separated directories for source code, tests, docs, and config.
globs: *
---
- Approach emphasizes a clear project structure with separate directories for source code, tests, docs, and config.


---
description: Applies general Python development guidelines including typing, docstrings, dependency management, testing with pytest, and code style using Ruff.
globs: **/*.py
---
- For any python file, be sure to ALWAYS add typing annotations to each function or class. Be sure to include return types when necessary.
- Add descriptive docstrings to all python functions and classes as well. Please use pep257 convention. Update existing docstrings if need be.
- Make sure you keep any comments that exist in a file.
- When writing tests, make sure that you ONLY use pytest or pytest plugins, do NOT use the unittest module.
- All tests should have typing annotations as well.
- All tests should be in ./tests. Be sure to create all necessary files and folders. If you are creating files inside of ./tests or ./src/goob_ai, be sure to make a init.py file if one does not exist.
- All tests should be fully annotated and should contain docstrings.
- Be sure to import the following if TYPE_CHECKING:
  from _pytest.capture import CaptureFixture
  from _pytest.fixtures import FixtureRequest
  from _pytest.logging import LogCaptureFixture
  from _pytest.monkeypatch import MonkeyPatch
  from pytest_mock.plugin import MockerFixture
- Dependency management via https://github.com/astral-sh/uv and virtual environments.
- Code style consistency using Ruff.


---
description: Optimize code snippets and explanations for clarity and AI-assisted development.
globs: *
---
- Provide code snippets and explanations tailored to these principles, optimizing for clarity and AI-assisted development.

Python Development Toolkit

A collection of tools designed to streamline Python project setup, code quality, and development workflows, focusing on best practices and automation.

Project Setup & Management

Python Project Scaffold Generator:
Creates a structured project setup with directories for source code, tests, and documentation.
Python Environment Manager:
Automates virtual environment setup and dependency management with a user-friendly interface.

Code Quality & Testing

Python Code Quality Analyzer:
Analyzes code for adherence to coding practices, providing feedback on naming conventions and type hints.
Automated Test Generator for Python:
Generates pytest test cases from existing codebases to ensure robust coverage.

Error Handling & Logging

Error Handling and Logging Assistant:
Provides real-time suggestions on error handling and logging improvements using AI.

Documentation & Configuration

Python Documentation Enhancer:
Automatically suggests improvements to docstrings and README files using AI.
Config Management Dashboard:
Manages and visualizes environment variables across different environments securely.

CI/CD & Style Consistency

CI/CD Configurator:
Creates and manages CI/CD pipelines tailored for Python projects, focusing on testing and deployment.
Ruff Integration Plugin:
Enforces code style consistency with real-time feedback and correction suggestions.

Key Technologies:

Python
Ruff
Pytest
GitHub Actions/GitLab CI
AI Integration

Overview of .cursorrules prompt

The .cursorrules file specifies guidelines for developing Python projects with a focus on AI-assisted development. It emphasizes a well-structured project with separate directories for various components, modular design, and comprehensive configuration management using environment variables. The approach includes robust error handling, thorough testing with pytest, and detailed documentation practices. Dependency management is handled via rye and virtual environments, while code style consistency is achieved using Ruff. Continuous Integration and Deployment (CI/CD) can be implemented using GitHub Actions or GitLab CI. The file promotes AI-friendly coding practices such as descriptive naming, type hints, and insightful comments, and provides code snippets and explanations tailored to these principles. Additionally, it outlines the importance of adding typing annotations, descriptive docstrings, and adhering to testing conventions using pytest, ensuring clarity and effectiveness in Python development.

Updated: March 17, 2025

Developers building scalable, maintainable Python applications with CI/CD pipelines would benefit by adhering to best practices for structure, modularity, testing, and documentation.

Usefull for: