python

Python Best Practices and Coding Standards

This document outlines comprehensive best practices and coding standards for Python development, aiming to promote clean, efficient, maintainable, and secure code.

1. Code Organization and Structure

1.1. Directory Structure Best Practices

• Flat is better than nested (but not always). Start with a simple structure and refactor as needed.

• Packages vs. Modules: Use packages (directories with __init__.py) for logical grouping of modules.

• src layout: Consider using a src directory to separate application code from project-level files (setup.py, requirements.txt, etc.). This helps avoid import conflicts and clarifies the project's boundaries.

• Typical Project Structure:

  project_name/ ├── src/ │ ├── package_name/ │ │ ├── init.py │ │ ├── module1.py │ │ ├── module2.py │ ├── main.py # Entry point ├── tests/ │ ├── init.py │ ├── test_module1.py │ ├── test_module2.py ├── docs/ │ ├── conf.py │ ├── index.rst ├── .gitignore ├── pyproject.toml or setup.py ├── README.md ├── requirements.txt or requirements-dev.txt

1.2. File Naming Conventions

• Modules: Lowercase, with underscores for readability (e.g., my_module.py).
• Packages: Lowercase (e.g., my_package). Avoid underscores unless necessary.
• Tests: Start with test_ (e.g., test_my_module.py).

1.3. Module Organization Best Practices

• Single Responsibility Principle: Each module should have a well-defined purpose.
• Imports:
  • Order: standard library, third-party, local.
  • Absolute imports are generally preferred (e.g., from my_package.module1 import function1).
  • Use explicit relative imports (from . import sibling_module) when dealing with complex package layouts where absolute imports are overly verbose or impractical.
• Constants: Define module-level constants in uppercase (e.g., MAX_ITERATIONS = 100).
• Dunder names: __all__, __version__, etc. should be after the module docstring but before any imports (except from __future__). Use __all__ to explicitly define the public API.