python-general-best-practices

Python Best Practices

Project Structure

• Place tests in tests/ directory parallel
• Keep configuration in config/ or as environment variables
• Store requirements in pyproject.toml
• Place static files in static/ directory
• Use templates/ for Jinja2 templates

Code Style

• Follow Black code formatting
• Use isort for import sorting
• Follow PEP 8 naming conventions:
  • snake_case for functions and variables
  • PascalCase for classes
  • UPPER_CASE for constants
• Maximum line length of 100 characters
• Use absolute imports over relative imports
• Use proper response formats

Type Hints

• Use type hints for all function parameters and returns
• Use modern Python 3.10+ union syntax: str | None instead of Optional[str]
• Use built-in generics: list[str], dict[str, int], tuple[int, ...], set[int]
• Import types from typing module for types not available as builtins (e.g., TypedDict, TypeVar, Literal, Callable, Protocol, Any)
• Use TypeVar for generic types
• Define custom types in types.py
• Use Protocol for duck typing

Testing

• Use pytest for testing
• Write tests for all routes
• Use pytest-cov for coverage
• Implement proper fixtures
• Use proper mocking with pytest-mock
• Test all error scenarios

Security

• Sanitize all user inputs
• Use proper session configuration
• Implement proper logging
• Follow OWASP guidelines

Error Handling

• Create custom exception classes
• Use proper try-except blocks
• Implement proper logging
• Return proper error responses
• Handle edge cases properly
• Use proper error messages

Documentation

• Use reStructuredText-style docstrings
• Document all public APIs
• Keep README.md updated
• Use proper inline comments
• Generate API documentation
• Document environment setup

Development Workflow

• Leverage uv for package management
• Use virtual environments (venv)
• Implement pre-commit hooks
• Use proper Git workflow
• Follow semantic versioning
• Use proper CI/CD practices
• Implement proper logging