Code Style and Linters

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• pyproject.toml
• README.md
• tests/test_utils.py
• tests/test_security.py

FastLimit maintains high code quality standards through a combination of automated linting tools, strict type checking, and standardized formatting. These practices ensure that the library remains production-ready, performant, and maintainable for both core contributors and community members.

The project follows the PEP 8 style guide with specific modifications, such as an extended line length, to accommodate modern development environments. Enforcement is automated via pre-commit hooks and CI/CD pipelines to prevent non-compliant code from entering the main codebase.

Sources: CONTRIBUTING.md:280-282, pyproject.toml:50, README.md:1-5

Automated Toolchain

The project utilizes several industry-standard tools for maintaining code health. These tools are configured within pyproject.toml and are required for all contributions.

Linting and Formatting Tools

Tool	Purpose	Configuration Highlights
Black	Code Formatting	100 character line limit, Target Python 3.9
Ruff	Linting & Sorting	E (pycodestyle), F (pyflakes), I (isort), B (bugbear)
Mypy	Type Checking	Strict mode enabled, Disallow untyped defs
Pre-commit	Git Hooks	Runs automated checks before every commit

Sources: pyproject.toml:44-53, pyproject.toml:70-89, CONTRIBUTING.md:290-300

Developer Workflow for Linting

The following flow diagram illustrates the expected development cycle for ensuring code style compliance before submitting changes.

This workflow ensures that developers catch style issues locally before they reach the CI pipeline.
Sources: CONTRIBUTING.md:185-195, CONTRIBUTING.md:210-220

Python Style Guidelines

Formatting Standards

FastLimit adheres to the following formatting conventions:

• Line Length: Extended to 100 characters instead of the standard 79.
• Quotes: Double quotes " are preferred for strings.
• Imports: Must be grouped into standard library, third-party, and local imports, handled automatically by the Ruff I (isort) rules.

Sources: CONTRIBUTING.md:280-288, pyproject.toml:70-80

Naming Conventions

The project uses standard Python naming patterns to ensure consistency across the main package and the test suite.

Entity	Convention	Example
Classes	PascalCase	RateLimiter, CheckResult
Functions	snake_case	check_rate_limit(), generate_key()
Constants	UPPER_SNAKE_CASE	MAX_RETRIES
Private Members	Leading Underscore	_internal_method(), _redact_redis_url()

Sources: CONTRIBUTING.md:304-315, tests/test_security.py:84-86, tests/test_utils.py:108-110

Documentation and Type Hinting

Type Annotations

Static typing is mandatory for all public functions and methods. This is enforced by mypy with the strict = true setting.

# Required Type Hinting Style
async def check(
    self,
    key: str,
    rate: str,
    algorithm: Optional[str] = None,
    cost: int = 1,
) -> bool:
    pass

Sources: pyproject.toml:82-85, CONTRIBUTING.md:320-330

Docstring Standards

FastLimit uses Google-style docstrings. Every public component must include a docstring detailing arguments, return types, exceptions raised, and usage examples.

Detailed documentation is required for core logic such as key generation and utility functions.
Sources: CONTRIBUTING.md:340-355, tests/test_utils.py:1-10

Security and Best Practices

Code style guidelines also extend to security and robust implementation practices within the codebase:

1. Sensitive Data: Functions that handle connection strings, such as _redact_redis_url, must be used to ensure passwords are not leaked in logs.
2. Key Collisions: Key generation logic in utils.py must use URL encoding for identifiers to prevent collisions (e.g., distinguishing between user:123 and user_123).
3. Error Handling: Specific exceptions (e.g., RateLimitExceeded, BackendError) must be used instead of bare except: blocks.

Sources: tests/test_security.py:15-25, tests/test_security.py:80-90, CONTRIBUTING.md:385-395

Summary

The Code Style and Linters system in FastLimit is designed to maintain a high-quality, professional codebase. By leveraging Black, Ruff, and Mypy alongside pre-commit hooks, the project ensures that all contributions are technically sound, well-documented, and consistent with Python best practices. This rigor supports the library's goals of high performance and reliability in production environments.