Python Best Practices

Project Structure

  • Use src-layout with src/your_package_name/
  • Place tests in tests/ directory parallel to src/
  • Keep configuration in config/ or as environment variables
  • Store requirements in requirements.txt or 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 88 characters (Black default)
  • Use absolute imports over relative imports

Type Hints

  • Use type hints for all function parameters and returns
  • Import types from typing module
  • Use Optional[Type] instead of Type | None
  • Use TypeVar for generic types
  • Define custom types in types.py
  • Use Protocol for duck typing

Flask Structure

  • Use Flask factory pattern
  • Organize routes using Blueprints
  • Use Flask-SQLAlchemy for database
  • Implement proper error handlers
  • Use Flask-Login for authentication
  • Structure views with proper separation of concerns

Database

  • Use SQLAlchemy ORM
  • Implement database migrations with Alembic
  • Use proper connection pooling
  • Define models in separate modules
  • Implement proper relationships
  • Use proper indexing strategies

Authentication

  • Use Flask-Login for session management
  • Implement Google OAuth using Flask-OAuth
  • Hash passwords with bcrypt
  • Use proper session security
  • Implement CSRF protection
  • Use proper role-based access control

API Design

  • Use Flask-RESTful for REST APIs
  • Implement proper request validation
  • Use proper HTTP status codes
  • Handle errors consistently
  • Use proper response formats
  • Implement proper rate limiting

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

  • Use HTTPS in production
  • Implement proper CORS
  • Sanitize all user inputs
  • Use proper session configuration
  • Implement proper logging
  • Follow OWASP guidelines

Performance

  • Use proper caching with Flask-Caching
  • Implement database query optimization
  • Use proper connection pooling
  • Implement proper pagination
  • Use background tasks for heavy operations
  • Monitor application performance

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 Google-style docstrings
  • Document all public APIs
  • Keep README.md updated
  • Use proper inline comments
  • Generate API documentation
  • Document environment setup

Development Workflow

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

Dependencies

  • Pin dependency versions
  • Use requirements.txt for production
  • Separate dev dependencies
  • Use proper package versions
  • Regularly update dependencies
  • Check for security vulnerabilities