Editing Development/Python (section)

== Architecture patterns ==

=== Dependency injection ===

Dependencies are passed explicitly. No global singletons, no module-level mutable state.

<syntaxhighlight lang="python">
# Wrong
class SearchEngine:
    def __init__(self):
        self._pool = _get_global_pool()
        self._load_cache()

# Right
class FullTextSearchEngine:
    def __init__(self, connection_pool: ConnectionPool):
        self.connection_pool = connection_pool
</syntaxhighlight>

=== No side effects in <code>__init__</code> ===

Constructors store parameters. They do not open connections, load caches, or perform I/O.

<syntaxhighlight lang="python">
# Wrong
class FrenchReferenceResolver:
    def __init__(self, connection_pool: ConnectionPool):
        self.connection_pool = connection_pool
        self._code_cache = self._load_code_cache()  # I/O in __init__

# Right
class FrenchReferenceResolver:
    def __init__(self, connection_pool: ConnectionPool):
        self.connection_pool = connection_pool
        self._code_cache: dict[str, str] | None = None

    def _ensure_code_cache(self) -> dict[str, str]:
        if self._code_cache is None:
            self._code_cache = self._load_code_cache()
        return self._code_cache
</syntaxhighlight>

=== Composition over inheritance ===

Core libraries define <code>Protocol</code> interfaces. Country packages and plugins provide implementations. Applications compose them.

<syntaxhighlight lang="python">
# duralex -- defines the interface
class ReferenceResolver(Protocol):
    def resolve_legal_reference(self, raw_text: str) -> list[ResolvedReference]: ...

class CompositeReferenceResolver:
    """Chains multiple resolvers. First match wins."""
    def __init__(self, resolvers: list[ReferenceResolver]):
        self.resolvers = resolvers

    def resolve_legal_reference(self, raw_text: str) -> list[ResolvedReference]:
        for resolver in self.resolvers:
            if results := resolver.resolve_legal_reference(raw_text):
                return results
        return []

# duralex-fr -- implements for France
class FrenchLegalReferenceResolver:
    """French legal references: articles, lois, pourvois, ECLI."""
    ...

# Application -- composes at startup
resolver = CompositeReferenceResolver([
    FrenchLegalReferenceResolver(connection_pool=pool),
    SireneCompanyResolver(),
])
</syntaxhighlight>

=== One module = one concept ===

A Python file should contain one coherent concept. If you need a table of contents to navigate the file, split it.

{| class="wikitable"
! Wrong !! Right
|-
| <code>db.py</code> (1400 lines: pool + CRUD + FTS + ingest + dedup + browse) || <code>connection_pool.py</code>, <code>full_text_search.py</code>, <code>ingest_state.py</code>, <code>browse_structure.py</code>
|-
| <code>validation.py</code> (filters + jurisdiction + pagination + dates + courts) || <code>search_filters.py</code>, <code>court_classification.py</code>
|}

Target: '''under 300 lines per file'''. Hard limit: '''500 lines'''.