python-coding

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