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