audit_inline_choices Namespace Reference

Functions
	_resolve_modules ()
	Expand the module roots into (path, dotted name) pairs.
str	literal_key (str module, list values)
	Stable identity for one inline choice set.
dict	find_inline_choices ()
	Every inline set of string choices in the CLI package.
list	string_members (collection)
	The string members of a literal collection, or None if it is not all strings.
int	main ()
	Fail when an inline choice set is neither named nor classified.

Variables
	REPO_ROOT = Path(__file__).resolve().parents[2]
str	WAIVERS = REPO_ROOT / "tests" / "tooling" / "inline_choice_waivers.json"
tuple	MODULE_ROOTS
	MODULES = tuple(item[0] for item in _resolve_modules())
	MODULE_DOTTED = dict(_resolve_modules())
tuple	VALID_CLASSIFICATIONS
int	MIN_REASON_CHARS = 40
int	MINIMUM_CHOICE_SIZE = 2

Detailed Description

Reject public closed choices written as inline literals.

The family census discovers `normalize_*` functions and named module-level constants.
That is a complete search of what it can see - and an inline `if value not in {"a","b"}`
is invisible to it. The census could therefore call itself exhaustive while public
choices sat in literals nobody enumerated.

This closes the loop from the other side: every inline set of string choices in the CLI
package must either become a named constant, which the census then discovers and
classifies, or be listed here with the same typed classification and a reason. A
literal that is neither is a violation.

Function Documentation

_resolve_modules()

audit_inline_choices._resolve_modules ( )

protected

Expand the module roots into (path, dotted name) pairs.

Returns

List of scanned module pairs.

Definition at line 31 of file audit_inline_choices.py.

def _resolve_modules():
    """!
    @brief Expand the module roots into `(path, dotted name)` pairs.
    @return List of scanned module pairs.
    """
    resolved = []
    for root in MODULE_ROOTS:
        path = REPO_ROOT / root
        if path.is_dir():
            dotted = root.replace("/", ".")
            for child in sorted(path.glob("*.py")):
                if child.name != "__init__.py":
                    resolved.append((str(child.relative_to(REPO_ROOT)), dotted))
        else:
            resolved.append((root, root.replace("/", ".")[: -len(".py")]))
    return resolved
 
 

literal_key()

str audit_inline_choices.literal_key	(	str	module,
		list	values
	)

Stable identity for one inline choice set.

Keyed by module and sorted values rather than by line number, so the waiver survives edits above it and two sites sharing a set collapse to one entry - which is itself a signal that the set wants a name.

Parameters

[in]	module	Dotted module name.
[in]	values	The string members.

Returns

Waiver key.

Definition at line 63 of file audit_inline_choices.py.

def literal_key(module: str, values: list) -> str:
    """!
    @brief Stable identity for one inline choice set.
 
    @details Keyed by module and sorted values rather than by line number, so the
             waiver survives edits above it and two sites sharing a set collapse to one
             entry - which is itself a signal that the set wants a name.
    @param[in] module Dotted module name.
    @param[in] values The string members.
    @return Waiver key.
    """
    return f"{module}::{{{','.join(sorted(values))}}}"
 
 

Here is the caller graph for this function:

find_inline_choices()

dict audit_inline_choices.find_inline_choices

(

)

Every inline set of string choices in the CLI package.

Two shapes are recognised: a membership test against a literal collection, and an argparse choices= literal. Both are how a closed public set gets written without a name.

Returns

Mapping of waiver key to the list of sites that produced it.

Definition at line 77 of file audit_inline_choices.py.

def find_inline_choices() -> dict:
    """!
    @brief Every inline set of string choices in the CLI package.
 
    @details Two shapes are recognised: a membership test against a literal collection,
             and an argparse `choices=` literal. Both are how a closed public set gets
             written without a name.
    @return Mapping of waiver key to the list of sites that produced it.
    """
    found: dict = {}
    for module in MODULES:
        path = REPO_ROOT / module
        if not path.is_file():
            continue
        dotted = MODULE_DOTTED.get(module, module.replace("/", ".")[: -len(".py")])
        tree = ast.parse(path.read_text(encoding="utf-8"))
        for node in ast.walk(tree):
            values = None
            shape = None
            if isinstance(node, ast.Compare) and node.ops and \
                    isinstance(node.ops[0], (ast.In, ast.NotIn)):
                collection = node.comparators[0]
                if isinstance(collection, (ast.Set, ast.List, ast.Tuple)):
                    values, shape = string_members(collection), "membership test"
            elif isinstance(node, ast.Call):
                for keyword in node.keywords:
                    if keyword.arg == "choices" and \
                            isinstance(keyword.value, (ast.Set, ast.List, ast.Tuple)):
                        values, shape = string_members(keyword.value), "argparse choices"
            if values and len(values) >= MINIMUM_CHOICE_SIZE:
                key = literal_key(dotted, values)
                found.setdefault(key, []).append(f"{module}:{node.lineno} ({shape})")
    return found
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

string_members()

list audit_inline_choices.string_members

(

collection

)

The string members of a literal collection, or None if it is not all strings.

Parameters

[in]

collection

An ast Set, List, or Tuple node.

Returns

List of string values, or None.

Definition at line 112 of file audit_inline_choices.py.

def string_members(collection) -> list:
    """!
    @brief The string members of a literal collection, or None if it is not all strings.
    @param[in] collection An ast Set, List, or Tuple node.
    @return List of string values, or None.
    """
    members = [element.value for element in collection.elts
               if isinstance(element, ast.Constant) and isinstance(element.value, str)]
    return members if len(members) == len(collection.elts) and members else None
 
 

Here is the caller graph for this function:

main()

int audit_inline_choices.main

(

)

Fail when an inline choice set is neither named nor classified.

Returns

Process status code.

Definition at line 123 of file audit_inline_choices.py.

def main() -> int:
    """!
    @brief Fail when an inline choice set is neither named nor classified.
    @return Process status code.
    """
    document = json.loads(WAIVERS.read_text(encoding="utf-8"))
    waivers = document["inline_choices"]
    found = find_inline_choices()
 
    problems: list = []
    for key in sorted(found):
        entry = waivers.get(key)
        if entry is None:
            problems.append(
                f"{key}\n      at {', '.join(found[key])}\n"
                f"      Give this set a name so the family census can see it, or "
                f"classify it in inline_choice_waivers.json."
            )
            continue
        classification = entry.get("classification")
        if classification not in VALID_CLASSIFICATIONS:
            problems.append(f"{key}: classification {classification!r} is not one of "
                            f"{list(VALID_CLASSIFICATIONS)}")
        elif len(str(entry.get("reason", "")).strip()) < MIN_REASON_CHARS:
            problems.append(f"{key}: classified {classification} without a stated reason")
    for stale in sorted(set(waivers) - set(found)):
        problems.append(f"{stale}: waived, but no such inline literal exists any more")
 
    if problems:
        print("Inline choice-set violations:", file=sys.stderr)
        for problem in problems:
            print(f"  {problem}", file=sys.stderr)
        return 1
 
    from collections import Counter
    spread = Counter(waivers[key]["classification"] for key in found)
    summary = ", ".join(f"{count} {name}" for name, count in sorted(spread.items()))
    print(f"Inline choice audit passed: {len(found)} inline set(s), every one classified "
          f"({summary}).")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

REPO_ROOT

audit_inline_choices.REPO_ROOT = Path(__file__).resolve().parents[2]

Definition at line 23 of file audit_inline_choices.py.

WAIVERS

str audit_inline_choices.WAIVERS = REPO_ROOT / "tests" / "tooling" / "inline_choice_waivers.json"

Definition at line 24 of file audit_inline_choices.py.

MODULE_ROOTS

tuple audit_inline_choices.MODULE_ROOTS

Initial value:

=  ("picurv_cli/core.py", "picurv_cli/cli.py", "picurv_cli/storage",
                "picurv_cli/main.py")

Definition at line 27 of file audit_inline_choices.py.

MODULES

audit_inline_choices.MODULES = tuple(item[0] for item in _resolve_modules())

Definition at line 49 of file audit_inline_choices.py.

MODULE_DOTTED

audit_inline_choices.MODULE_DOTTED = dict(_resolve_modules())

Definition at line 50 of file audit_inline_choices.py.

VALID_CLASSIFICATIONS

tuple audit_inline_choices.VALID_CLASSIFICATIONS

Initial value:

=  (
    "parameter_of_entry", "spelling_alias", "structural",
    "cli_inventory_sufficient", "not_public",
)

Definition at line 54 of file audit_inline_choices.py.

MIN_REASON_CHARS

int audit_inline_choices.MIN_REASON_CHARS = 40

Definition at line 58 of file audit_inline_choices.py.

MINIMUM_CHOICE_SIZE

int audit_inline_choices.MINIMUM_CHOICE_SIZE = 2

Definition at line 60 of file audit_inline_choices.py.