This document outlines the coding standards for Python projects to ensure code consistency, readability, and maintainability across the team.
PEP 8 Compliance: Always follow PEP 8 style guide, including:
Consistency: Be consistent in code formatting, variable names, and function names.
Comments: Write clear comments to explain the "why" behind complex code, especially when it's not obvious.
Variables: Use lowercase letters with underscores separating words (snake_case).
my_variableClass Member Variables: Use snake_case for class attributes.
self.file_path, self.data_import_codecoding_style.md section 1.3 for the specific _Capitalizedlowercase convention.Functions/Methods: Use lowercase letters with underscores (snake_case), including CRUD operations.
run_workflow(), read(), create(), update()Classes: Use CapitalizedWords convention (PascalCase).
ObjDocumentConstants: Use all uppercase letters with underscores.
MAX_SIZE = 100File Organization: Split files logically into modules and packages. Keep each module focused on a single responsibility.
Order of Functions:
No long functions: Each function should do one thing and be as small as possible while maintaining clarity.
Import Style: Always import standard libraries first, followed by third-party libraries, and then your own modules.
import os
import sys
from external_package import SomeClass
from my_module import MyFunction
Avoid wildcard imports: Do not use from module import *. Always import explicitly to maintain clarity.
Catch Specific Exceptions: Always catch specific exceptions instead of generic ones.
try:
# some code
except FileNotFoundError as e:
# handle error
Logging in Exceptions: Log exceptions with useful information for debugging.
Test Naming: Use descriptive names for test functions.
test_calculate_total_price_valid_case()Unit Tests: Write unit tests for all core logic.
Test Coverage: Aim for at least 90% code coverage, but focus on testing the most critical parts of the code.
Mocking: Use mocking for external services or dependencies in tests to avoid unnecessary API calls or DB interactions.
Schema Setup Helpers: The root conftest.py provides two shared utilities for test schema setup:
db_is_test — Session-scoped fixture that returns True when the database name ends with .test (uses ObjData.sql_get_database()). Use this to guard destructive operations.ensure_tables(*entries) — Helper function that non-destructively creates tables via CREATE TABLE IF NOT EXISTS. Accepts Obj classes or (ObjClass, "yaml_name") tuples.Non-destructive setup (safe on any database):
@pytest.fixture(scope="session", autouse=True)
def ensure_schema():
from conftest import ensure_tables
ensure_tables(ObjFoo, ObjBar)
ensure_tables((DocumentFile, "ObjDocumentFile"))
yield
Destructive setup (DROP TABLE, DELETE FROM) must use db_is_test:
@pytest.fixture(scope="session", autouse=True)
def ensure_schema(db_is_test):
if not db_is_test:
yield
return
from conftest import ensure_tables
ensure_tables(ObjSafe) # non-destructive tables
obj = ObjDangerous()
obj.sql_execute("DROP TABLE IF EXISTS ...")
obj.create_tables_from_yaml()
yield
Branching Strategy: Use feature branches and pull requests for every new feature or bug fix.
Linting: Before changes are committed, run Ruff check on your files
ruff check factory.core/ObjDocument.pyruff check .Excluded errors can be found in the pyproject.toml
Commit Messages: Write clear and concise commit messages. Follow the convention:
Format: [type]: short description
Types: feat, fix, docs, refactor, test, chore
feat (Feature) → Introduces a new feature or functionality to the codebase.
Example: feat: add user authentication system
fix (Bug Fix) → Fixes a bug or an issue in the code.
Example: fix: resolve login issue when using special characters
docs (Documentation) → Changes related to documentation, like README updates or inline comments.
Example: docs: update API usage examples in README
refactor (Refactoring) → Code changes that improve structure without changing functionality.
Example: refactor: simplify database query logic
test (Testing) → Adds or updates tests, like unit tests or integration tests.
Example: test: add missing tests for user service
chore (Maintenance) → Routine tasks like dependency updates, build scripts, or configuration changes.
Example: chore: update dependencies to latest versions
Peer Reviews: Always have at least one peer review your pull request before merging.
No Merge Without Review: Do not merge code without approval from a teammate.
Constructive Feedback: Provide constructive feedback, and accept feedback graciously.
Project-Specific: Use self.debug() for all logging and debugging output. Do not use print() or standard logging libraries directly.
Logging Levels (for reference): Standard Python logging uses these levels:
DEBUG: Detailed information, typically useful only for diagnosing problems.INFO: General information about the application's flow.WARNING: Indicates something unexpected, but not a problem.ERROR: Indicates a more serious issue that prevents the program from running correctly.