Editing Development/Python (section)

== Naming ==

=== Casing (PEP 8) ===

{| class="wikitable"
! Element !! Case !! Example
|-
| Functions, methods, variables || <code>snake_case</code> || <code>parse_legislation_article()</code>
|-
| Classes || <code>PascalCase</code> || <code>LegislationArticle</code>
|-
| Constants || <code>UPPER_SNAKE</code> || <code>ALLOWED_TABLE_NAMES</code>
|-
| Enum members || <code>UPPER_SNAKE</code> || <code>Confidence.SOURCE_CHECKED</code>
|-
| Enum string values || <code>lowercase</code> || <code>"source_checked"</code>
|-
| Module filenames || <code>snake_case</code> || <code>connection_pool.py</code>
|}

=== No abbreviations ===

The code is written and maintained by AI. The AI does not tire of typing. Full words always.

{| class="wikitable"
! Wrong !! Right
|-
| <code>ref</code> || <code>reference</code>
|-
| <code>leg</code> || <code>legislation</code>
|-
| <code>dec</code> || <code>decision</code>
|-
| <code>doc</code> || <code>document</code>
|-
| <code>fts</code> || <code>full_text_search</code>
|-
| <code>tbl</code> || <code>table</code>
|-
| <code>q</code> || <code>query</code>
|-
| <code>lim</code> || <code>limit</code>
|-
| <code>flt</code> || <code>filter</code>
|-
| <code>el</code> || <code>element</code>
|-
| <code>ctx</code> || <code>context</code>
|-
| <code>conn</code> || <code>connection</code>
|-
| <code>cfg</code> || <code>configuration</code>
|-
| <code>num</code> || <code>number</code>
|-
| <code>idx</code> || <code>index</code>
|-
| <code>val</code> || <code>value</code>
|}

=== Qualified names ===

Single-word names are ambiguous. Always qualify with the domain.

{| class="wikitable"
! Wrong !! Right !! Why
|-
| <code>query</code> || <code>search_query</code> || Could be SQL, HTTP, FTS...
|-
| <code>text</code> || <code>article_text</code> || Could be anything
|-
| <code>content</code> || <code>html_content</code> || What kind?
|-
| <code>result</code> || <code>search_result</code> || Result of what?
|-
| <code>data</code> || <code>decision_data</code> || Meaningless alone
|-
| <code>items</code> || <code>matched_articles</code> || What items?
|-
| <code>response</code> || <code>search_response</code> || From where?
|-
| <code>path</code> || <code>file_path</code> or <code>concept_path</code> || Filesystem? URI?
|}

=== Booleans read as phrases ===

A boolean variable or parameter must read as a true/false statement.

<syntaxhighlight lang="python">
# Wrong
active = True
force = False
recursive = True

# Right
is_in_force = True
should_force_refresh = False
is_recursive = True
has_been_verified = False
should_include_repealed = True
</syntaxhighlight>

=== Classes: named for what they ARE ===

<syntaxhighlight lang="python">
class LegislationArticle: ...
class CaseLawDecision: ...
class ResolvedReference: ...
class AnnotationEnvelope: ...
class ConceptDefinition: ...
class SearchFilters: ...
class SearchResults: ...
class CompiledPackage: ...
</syntaxhighlight>

=== Methods: verb + explicit object ===

<syntaxhighlight lang="python">
def parse_legislation_article(xml_path: Path) -> LegislationArticle: ...
def resolve_legal_reference(raw_text: str) -> list[ResolvedReference]: ...
def search_full_text(query: str, filters: SearchFilters) -> SearchResults: ...
def compile_domain_package(domain: str) -> CompiledPackage: ...
def sanitize_html_content(raw_html: str) -> str: ...
def extract_text_content(element: Element, xpath: str) -> str | None: ...
def validate_date_range(date_from: str | None, date_to: str | None) -> None: ...
</syntaxhighlight>

=== Protocols: named for the capability ===

<syntaxhighlight lang="python">
class LegislationParser(Protocol): ...
class ReferenceResolver(Protocol): ...
class SearchEngine(Protocol): ...
class VersionSelector(Protocol): ...
class DecisionDownloader(Protocol): ...
</syntaxhighlight>

=== Enums ===

<syntaxhighlight lang="python">
class ConceptType(Enum):
    QUALIFIABLE = "qualifiable"
    OPEN_STANDARD = "open_standard"
    GUIDING_PRINCIPLE = "guiding_principle"
    PROCEDURAL = "procedural"
    SCALE = "scale"

class Confidence(Enum):
    STUB = "stub"
    MEMORY_ONLY = "memory_only"
    SOURCE_CHECKED = "source_checked"
    CROSS_VALIDATED = "cross_validated"

class Outcome(Enum):
    QUALIFIED = "qualified"
    NOT_QUALIFIED = "not_qualified"
    VALIDATED = "validated"
    INVALIDATED = "invalidated"
    PROCEDURAL = "procedural"
    MOOT = "moot"
</syntaxhighlight>