selfdoc v0.37.1 /selfdoc.ownership
Updated
On this page

Classifies a generated page's frontmatter description as machine-owned placeholder text that selfdoc may overwrite, or handwritten text gen must preserve.

#selfdoc.ownership

#selfdoc.ownership

Description ownership predicate: machine-owned vs handwritten.

Classifies a generated page's frontmatter description as either machine-owned (a placeholder selfdoc emitted and may freely overwrite) or handwritten (authored by a human/agent and must never be overwritten).

The single guiding principle: descriptions are handwritten; machine text is only ever a placeholder. The critical property is the INVERSE -- handwritten text must NEVER be classified machine-owned. The reverse (legacy machine residue occasionally classified handwritten when no seed_hash was ever recorded) is acceptable: the next selfdoc gen reseeds it, and releases always run gen before check.

Ownership is decided per page kind:

  • module pages: the current or historical instantiated template for that

module, OR the recorded seed_hash.

  • gen-index: the current/legacy index templates, OR the recorded seed_hash.
  • CLI pages: :func:is_default_cli_description (a live recompute from the

schema, covering the truncated-prefix family), OR the recorded seed_hash.

seed_hash is the SHA-256 of the machine-emitted description TEXT, recorded per page by selfdoc gen in the staleness store.

This module lives in the selfdoc (app) layer, not selfdoc_core, because CLI ownership needs :mod:selfdoc.strictcli_support.

#normalize_description

python
def normalize_description(value)

Strip surrounding whitespace and one layer of matching quotes.

#description_seed_hash

python
def description_seed_hash(value)

SHA-256 of a (normalized) machine-emitted description string.

#is_machine_owned_module_description

python
def is_machine_owned_module_description(value, module_name, seed_hash=None)

True if value is machine-owned for a module page named module_name.

#is_machine_owned_index_description

python
def is_machine_owned_index_description(value, seed_hash=None)

True if value is a machine-owned gen-index description.

#is_machine_owned_cli_description

python
def is_machine_owned_cli_description(value, *, kind, name, app_name, help_text, seed_hash=None)

True if value is a machine-owned CLI page description.

#_lookup_cli

python
def _lookup_cli(cli_structure, name)

Return (kind, help_text, app_name) for a CLI page name, or (None,...).

#is_machine_owned

python
def is_machine_owned(rel_path, frontmatter, *, seed_hash=None, cli_structure=None)

Classify a page's description as machine-owned (True) or handwritten.

rel_path selects the page kind by filename; frontmatter supplies the description (and title for module pages). seed_hash is the per-page seed hash from the staleness store (None when unrecorded). cli_structure is the parsed strictcli schema (needed to look up a CLI command's help text); pass None for non-strictcli projects.

Handwritten text is never classified machine-owned. Only generated pages can be machine-owned -- a non-generated (hand-authored) page always returns False, so it receives full staleness protection.

Search