Contributing Guidelines

Relevant source files

• .github/workflows/test.yml
• .pre-commit-config.yaml
• poetry.lock
• pyproject.toml
• requirements.txt

This document covers the code quality standards, development tools, and contribution workflow for the auth0-python SDK. It describes the pre-commit hooks, code style requirements, testing expectations, and procedures for submitting contributions.

For information about the CI/CD pipeline and automated security scanning, see CI/CD Pipeline and Security Scanning. For details on the build system and dependency management, see Build System and Dependencies.

---

Code Style Requirements

The auth0-python SDK enforces strict code style standards using automated tooling. All code must pass multiple quality checks before being accepted.

Code Formatting and Linting Tools

The project uses four primary code quality tools, all configured as pre-commit hooks:

Tool	Version	Purpose	Configuration
black	23.3.0	Code formatting (opinionated)	Default settings
flake8	5.0.4	PEP 8 linting and style checking	Default settings
isort	5.11.5	Import statement sorting	--profile black for compatibility
pyupgrade	3.3.2	Python syntax modernization	--keep-runtime-typing for type hints

Sources: .pre-commit-config.yaml9-29

Additional Quality Checks

Pre-commit hooks also enforce basic file hygiene:

• check-yaml: Validates YAML syntax in configuration files
• end-of-file-fixer: Ensures files end with a newline
• trailing-whitespace: Removes trailing whitespace from all lines

Sources: .pre-commit-config.yaml2-7

---

Pre-Commit Hook System

Hook Configuration

Pre-commit Hook Execution Flow: Shows the sequential execution of hooks on every commit attempt. All hooks must pass for the commit to succeed.

Sources: .pre-commit-config.yaml1-38

Installing Pre-Commit Hooks

To set up the pre-commit hooks in your local environment:

Once installed, the hooks automatically run on git commit. If any hook fails, the commit is blocked and you must fix the issues before retrying.

Poetry Dependency Hooks

The poetry hooks ensure dependency files remain synchronized:

1. poetry-check: Validates pyproject.toml syntax and consistency
2. poetry-lock: Updates poetry.lock when pyproject.toml changes
3. poetry-export: Regenerates requirements.txt from poetry.lock

The poetry-export hook uses these arguments:

This generates a pip-compatible requirements file including development dependencies.

Sources: .pre-commit-config.yaml31-37

---

Testing Requirements

Running Tests Locally

The SDK uses pytest as its test framework with coverage reporting via pytest-cov. Tests must be run through Poetry's virtual environment:

The coverage report shows:

• Line-by-line coverage (--cov-report=term-missing)
• Skips fully covered files (skip-covered)
• Generates XML report for CI/CD (--cov-report=xml)

Sources: .github/workflows/test.yml68

Test Environment Setup

Test Dependency Architecture: The test suite requires both synchronous and asynchronous testing tools. responses mocks synchronous HTTP via requests, while aioresponses mocks asynchronous HTTP via aiohttp.

Sources: pyproject.toml36-44 requirements.txt2-34

CI Test Matrix

The CI pipeline tests against multiple Python versions using a matrix strategy:

CI Test Matrix Configuration: All Python versions (3.9-3.12) run tests in parallel within isolated bubblewrap sandboxes. Only Python 3.10 uploads coverage to Codecov.

Sources: .github/workflows/test.yml39-85

Sandboxed Test Execution

The CI environment uses bubblewrap to run tests in a secure, isolated sandbox:

This ensures tests cannot:

• Modify the host filesystem (except the workspace)
• Access network resources outside the test
• Interfere with other processes
• Persist state between test runs

Sources: .github/workflows/test.yml26-37

Coverage Requirements

While there is no enforced minimum coverage percentage, contributors should:

1. Add tests for new features: All new functionality must include corresponding tests
2. Maintain existing coverage: Changes should not decrease overall coverage
3. Test both sync and async paths: For HTTP infrastructure changes, test both RestClient and AsyncRestClient
4. Use appropriate mocks: Use responses for sync HTTP mocking, aioresponses for async

Coverage reports highlight untested lines with --cov-report=term-missing:skip-covered, making it easy to identify gaps.

Sources: .github/workflows/test.yml68

---

Development Environment Setup

Prerequisites

• Python: Version 3.8 or higher (3.9-3.12 recommended for testing compatibility)
• Poetry: Package and dependency manager
• Git: Version control
• bubblewrap (optional): For running tests in sandboxed environments locally

Sources: pyproject.toml29 .github/workflows/test.yml41

Initial Setup

Sources: .github/workflows/test.yml54-64

Dependency Management

The project uses Poetry with locked dependencies for reproducible builds:

Dependency Lock and Resolution: poetry.lock contains exact versions and cryptographic hashes for all dependencies, ensuring reproducible installs. The pre-commit hook automatically regenerates requirements.txt when dependencies change.

Sources: pyproject.toml28-44 .pre-commit-config.yaml36-37

Key dependency notes:

• cryptography >=43.0.1: Explicitly declared because pyjwt has a weak dependency on it
• urllib3 >=2.2.3: Explicitly declared because requests has a weak dependency on it
• All version constraints use >= to allow patch/minor updates while ensuring minimum versions

Sources: pyproject.toml31-34

---

Contribution Workflow

Before Committing

Complete Contribution Workflow: Code must pass local pre-commit hooks before being committed, then pass CI tests across all Python versions before being merged.

Sources: .pre-commit-config.yaml1-38 .github/workflows/test.yml1-85

Step-by-Step Process

1. Create a feature branch

2. Make your changes

   • Follow existing code patterns in the relevant modules
   • Add docstrings for new classes and methods
   • Update type hints appropriately

3. Write tests

   • Add test cases in the appropriate test file
   • Ensure both success and error paths are tested
   • For async code, use pytest-asyncio decorators

4. Run tests locally

5. Commit your changes

   • Pre-commit hooks will automatically run
   • If hooks fail, fix the issues and retry the commit
   • Some hooks (like black and isort) auto-fix issues; just git add the changes and retry

6. Push to your fork

7. Open a pull request

   • Provide a clear description of changes
   • Reference any related issues
   • Wait for CI to pass (all Python versions)
   • Address any review feedback

Code Organization Patterns

When contributing new code, follow these organizational patterns:

Authentication API Components (in auth0/authentication/):

• Inherit from AuthenticationBase class
• Use self.client (RestClient instance) for HTTP requests
• Example: [Database, Passwordless, Social classes]

Management API Endpoints (in auth0/management/):

• Accept RestClient instance in __init__
• Define methods matching API operations
• Example: [Users, Organizations, Clients classes]

Async Support:

• Place async versions in auth0/asyncify.py
• Use _async suffix for async method names
• Ensure both sync and async paths are tested

Sources: Based on architectural patterns described in Core Architecture

Common Pre-Commit Issues and Fixes

Hook	Common Issue	Fix
black	Code formatting doesn't match	Hook auto-fixes; just git add and retry
flake8	Line too long (>88 chars)	Break into multiple lines or use implicit string concatenation
isort	Import order incorrect	Hook auto-fixes; just git add and retry
pyupgrade	Outdated syntax (e.g., % formatting)	Hook auto-fixes to modern syntax; review and accept
poetry-lock	poetry.lock out of sync	Hook auto-updates; just git add poetry.lock and retry
trailing-whitespace	Extra spaces at line endings	Hook auto-fixes; just git add and retry

Sources: .pre-commit-config.yaml1-38

When Hooks Can't Auto-Fix

Some flake8 errors require manual intervention:

• F401 (unused import): Remove the unused import
• E501 (line too long): Refactor into multiple lines
• F841 (local variable assigned but never used): Remove or use the variable
• E402 (module level import not at top): Move imports to top of file

Run poetry run flake8 . to see detailed error messages with line numbers.

---

Testing Guidelines

Test File Organization

Tests are located in the auth0/test/ directory, organized by component:

• test_authentication.py: Authentication API tests
• test_management/: Management API endpoint tests
• test_async*.py: Async-specific tests
• test_rest.py: HTTP client tests

Writing Good Tests

1. Use descriptive test names

2. Mock HTTP responses appropriately

3. Test error cases

   • Test invalid input handling
   • Test HTTP error responses (4xx, 5xx)
   • Test rate limiting behavior

4. Use pytest fixtures for common setup

Coverage Best Practices

• Aim for high coverage of new code (ideally >90%)
• Don't sacrifice test quality for coverage numbers
• Focus on testing behavior, not implementation details
• Include both positive and negative test cases

Sources: General testing best practices aligned with CI configuration in .github/workflows/test.yml68

---

Additional Resources

• Project Repository: https://github.com/auth0/auth0-python
• Issue Tracker: https://github.com/auth0/auth0-python/issues
• CI/CD Details: See CI/CD Pipeline
• Security Scanning: See Security Scanning
• Build System: See Build System and Dependencies