Code Quality Tools

Relevant source files

• .github/workflows/test.yml
• .gitignore
• README.md
• poetry.lock
• pyproject.toml
• requirements.txt

This page documents the static analysis tools used to maintain code quality in the auth0-python SDK, including type checking with mypy and linting with ruff. For information about testing infrastructure, see Testing Infrastructure. For CI/CD integration of these tools, see CI/CD Pipeline.

Overview

The SDK employs two primary code quality tools configured in pyproject.toml1-102:

Tool	Version	Primary Purpose
mypy	1.13.0	Static type checking with Pydantic plugin support
ruff	0.11.5	Fast linting and formatting (replaces black, flake8, isort, pyupgrade)

Both tools are installed as development dependencies and configured to accommodate the dual architecture of the SDK: the modern type-safe Management API v5 and the legacy Authentication API.

Sources: pyproject.toml51-59 pyproject.toml70-101

Tool Configuration Architecture

Sources: pyproject.toml70-101

Type Checking with mypy

Configuration

The mypy configuration is minimal but strategic, targeting only the code designed for type safety:

Sources: pyproject.toml70-73

Pydantic Plugin Integration

The Management API v5 uses Pydantic models extensively for request/response validation. The pydantic.mypy plugin enhances type checking by:

• Validating Pydantic model field types
• Checking __init__ signatures against model definitions
• Enforcing strict type checking on Pydantic validators
• Providing IDE integration for Pydantic-specific patterns

This plugin is essential because the Management API codebase relies on Pydantic v1.9.2+ and pydantic-core 2.18.2+.

Sources: pyproject.toml71 pyproject.toml41-42

Authentication API Exclusion

The Authentication API is explicitly excluded from type checking:

This exclusion exists because:

1. Legacy Code: The Authentication API predates the v5 rewrite and maintains backward compatibility patterns
2. Different Design Philosophy: Uses dynamic typing and runtime flexibility for OAuth 2.0 flow variations
3. Mixed HTTP Clients: Supports both aiohttp and requests with different type signatures
4. Technical Debt: Retrofitting full type annotations would risk breaking changes

The Management API (src/auth0/management/) is fully type-checked, leveraging the Fern-generated OpenAPI types.

Sources: pyproject.toml72-73

Linting with ruff

Overview and Rule Selection

ruff is configured to enforce consistent code style while accommodating necessary exceptions:

The tool consolidates functionality from multiple legacy tools (black, flake8, isort, pyupgrade) into a single fast Rust-based linter.

Sources: pyproject.toml75-83

Rule Categories

Sources: pyproject.toml79-83

Ignored Rules

The configuration explicitly ignores certain rules to balance strictness with practical development needs:

Rule	Category	Reason for Ignoring
E402	Module import not at top	Allows conditional imports based on runtime checks
E501	Line too long	Handled by line-length setting; some long strings unavoidable
E711	Comparison to None	Legacy code uses == None patterns
E712	Equality with True	Explicit boolean comparisons in some validation code
E721	Type comparison style	Mixed use of type() and isinstance()
E722	Bare except	Some legacy error handling uses bare except
E731	Lambda assignment	Used in certain callback registration patterns
F821	Undefined name	Forward references in type hints
F841	Unused variable	Some fixture variables required by test framework

Sources: pyproject.toml84-94

Import Sorting Configuration

The isort functionality within ruff enforces import order:

This ensures consistent import organization:

1. Future imports (from __future__ import ...)
2. Standard library imports (import json, import os)
3. Third-party imports (import httpx, import pydantic)
4. First-party imports (from auth0.management import ...)

Sources: pyproject.toml96-97

Development Dependency Management

Tool Installation

Both tools are specified as development dependencies with pinned versions:

Exact version pinning ensures:

• Reproducible Development: All developers use identical tool versions
• Consistent CI/CD: Same behavior in local and CI environments
• Controlled Updates: Explicit decision required to upgrade tools

Sources: pyproject.toml51-59

Dependency Installation Flow

Sources: pyproject.toml38-65 .github/workflows/test.yml54-64

Local Development Workflow

Running Type Checks

Developers run mypy locally to check type errors in the Management API:

The tool automatically:

1. Reads configuration from [tool.mypy] in pyproject.toml70-73
2. Excludes src/auth0/authentication/ directory
3. Applies Pydantic plugin to Management API types
4. Reports type errors with file/line locations

Sources: pyproject.toml70-73

Running Lint Checks

Developers run ruff to check and fix code style issues:

The tool automatically:

1. Reads configuration from [tool.ruff] in pyproject.toml75-97
2. Applies selected rules (E, F, I) to all Python files
3. Respects ignored rules for pragmatic development
4. Sorts imports according to isort configuration

Sources: pyproject.toml75-97

CI/CD Integration Status

Current State

The CI/CD pipeline (.github/workflows/test.yml1-85) currently does not enforce code quality tools as required checks. The workflow file contains commented-out lint checks:

This code represents the legacy tool stack that ruff now replaces.

Sources: .github/workflows/test.yml70-79

Tool Migration

The repository has migrated from multiple tools to ruff:

Old Tool	Purpose	Replacement
black 23.3.0	Code formatting	ruff format
flake8 5.0.4	Linting	ruff check (E, F rules)
isort 5.11.5	Import sorting	ruff check (I rules)
pyupgrade 3.3.2	Syntax modernization	Not directly replaced

The migration to ruff provides:

• 10-100x faster execution than Python-based tools
• Single tool instead of four separate tools
• Unified configuration in pyproject.toml75-97
• Better caching for incremental checks

Sources: .github/workflows/test.yml70-79 pyproject.toml59

Tool-Code Mapping

Sources: pyproject.toml70-97

Configuration Reference

Complete mypy Configuration

Located at pyproject.toml70-73:

• Plugin: pydantic.mypy for Pydantic v1/v2 compatibility
• Exclusion: src/auth0/authentication/ directory completely skipped
• No explicit strict settings: Relies on default strictness level

Complete ruff Configuration

Located at pyproject.toml75-97:

• Line Length: 120 characters
• Selected Rules: E (pycodestyle), F (pyflakes), I (isort)
• Ignored Rules: 9 specific rules (E402, E501, E711, E712, E721, E722, E731, F821, F841)
• Import Order: Standard four-section ordering (future, stdlib, third-party, first-party)

Best Practices

When to Run Tools

Stage	Tool	Command	Purpose
Pre-commit	ruff	ruff check . --fix	Fix auto-fixable style issues
Pre-commit	ruff	ruff format .	Format code consistently
Pre-push	mypy	mypy	Verify Management API types
Pre-push	ruff	ruff check .	Final lint verification

Handling Type Errors

When mypy reports errors in Management API code:

1. Check actual error: Many errors indicate real bugs (incorrect types, missing attributes)
2. Add type annotations: Missing annotations cause inference failures
3. Use type guards: For runtime type checks, use isinstance() or type guards
4. Add # type: ignore: Only as last resort for known false positives

Handling Lint Errors

When ruff reports errors:

1. Auto-fix first: Run ruff check . --fix to automatically resolve fixable issues
2. Manual fixes: Address remaining issues (logic errors, undefined names)
3. Disable specific line: Use # noqa: E711 for unavoidable violations
4. Update configuration: Consider adding to ignore list if pattern is acceptable

Sources: pyproject.toml75-97