Echopy module values and their documentation
Echopy keeps a native module value connected to its owner. A read through the facade sees the current object; an accepted module write or deletion reaches the native namespace. The adjacent declaration records documentation and a type without inventing an offline value. Maintainers need to check both routes: correct names alone cannot reveal a hidden write or a lost attribute docstring.
This guide explains the source contract with invented, owned modules. The names
owned_echopy_values, value-with-dash and _echopy_value below are test inputs,
not claims that a FontLab build exposes those names. Every assignment changes an
owned ModuleType object. For real native import and read-only class identity
examples, start with the Echopy package guide.
An arbitrary native module assignment can change application state; these
examples do not authorize copying invented assignments into FontLab.
Follow a value through the pipeline
| Stage | What it supplies | What it does not establish |
|---|---|---|
| Capture metadata | Names, recorded types, docs and inspection failures | Complete getter/setter behavior or safe arbitrary introspection |
| Raw generation | Source-safe annotated names, adjacent docs and alias metadata | Concrete offline values |
| Maintained JSON overlays | Targeted doc/type enrichment with explicit source attribution | New measured native semantics |
Merged .pyi |
Full declarations and adjacent attribute documentation | A runtime implementation |
Tiny .py facade |
Current native dispatch, or offline declarations | Emulation of FontLab |
| Griffe static visitor | What a documentation consumer reads from source | Native argument conversion or execution |
from module import value follows normal Python binding rules: the local name
refers to the object obtained at that moment. Keep reading module.value when
you need later module replacements. Similarly, module.__dict__ can contain
initial binding snapshots and runtime bookkeeping. Use attribute access, aliases
and dir() to test delegation; do not treat the dictionary as a live native map.
Python documents module subclasses in its
module attribute access reference.
Set up an owned experiment
Use Python 3.11 in a fresh directory that you own, with the Echopy revision being
checked and its docs extra already provisioned (griffe is required). Check
fontlab_echopy.__file__ before proceeding so the source or installed copy is
unambiguous. No FontLab, native Qt or macOS framework is required. The source
runner and installed-prefix runner execute this exact setup anew before each
marked example; they never rewrite the setup or example body.
Save this setup followed by one marked example in a Python file and run that
file. Each example is independent. TemporaryDirectory owns the raw/merged
outputs and overlays; leaving the context removes those scratch files and the
invented module registrations, even if an assertion fails. The helper calls the
real capture/generation/merge/runtime code rather than reproducing its logic.
import ast
from contextlib import contextmanager
import copy
import json
from pathlib import Path
import sys
from tempfile import TemporaryDirectory
from types import ModuleType, SimpleNamespace
from fontlab_echopy.tooling.capture import namespace as capture_namespace
from fontlab_echopy.tooling.generate import generate, source_name
from fontlab_echopy.tooling.merge import merge
OWNED_NATIVE = "owned_echopy_values"
OWNED_FACADE = "owned_echopy_values_facade"
@contextmanager
def owned_pipeline(scope, *, values=None, overlays=(), stage="merged"):
assert OWNED_NATIVE not in sys.modules and OWNED_FACADE not in sys.modules
data = {"modules": {OWNED_NATIVE: {"namespace": copy.deepcopy(scope)}}}
with TemporaryDirectory(prefix="echopy-values-", dir=Path.cwd()) as temporary:
folder = Path(temporary)
raw, output = folder / "raw", folder / "merged"
generate(data, raw)
paths = []
for index, patch in enumerate(overlays):
path = folder / f"overlay-{index}.json"
path.write_text(json.dumps(patch), encoding="utf-8")
paths.append(path)
raw_before = {p.name: p.read_bytes() for p in raw.iterdir() if p.is_file()}
overlay_before = [p.read_bytes() for p in paths]
result = merge(raw, output, paths)
native = ModuleType(OWNED_NATIVE) if values is not None else None
if native is not None:
native.__dict__.update(values)
sys.modules[OWNED_NATIVE] = native
facade = ModuleType(OWNED_FACADE)
source = (raw if stage == "raw" else output) / f"{OWNED_NATIVE}.py"
facade.__file__ = str(source)
sys.modules[OWNED_FACADE] = facade
try:
exec(compile(source.read_text(), str(source), "exec"), facade.__dict__)
yield SimpleNamespace(native=native, facade=facade, raw=raw,
output=output, overlays=paths, result=result)
assert raw_before == {p.name: p.read_bytes() for p in raw.iterdir() if p.is_file()}
assert overlay_before == [p.read_bytes() for p in paths]
finally:
sys.modules.pop(OWNED_FACADE, None)
sys.modules.pop(OWNED_NATIVE, None)
The values=None branch deliberately omits a native module. A dictionary,
including an empty dictionary, explicitly supplies an owned native module.
This distinction prevents an unavailable native namespace from becoming a
successful dummy. The helper verifies raw and overlay byte preservation after
every normally completed example; the capture example also checks its input.
Read the current object and forward a write
The first example keeps an earlier local reference, replaces the value through the facade, then changes the native owner directly. Both module reads follow the owner. The earlier local reference keeps ordinary Python snapshot semantics.
initial, replacement, final = object(), object(), object()
scope = {"attributes": [{"name": "value", "type": "Any"}]}
with owned_pipeline(scope, values={"value": initial}) as case:
facade, native = case.facade, case.native
saved_reference = facade.value
assert facade.value is native.value is initial
facade.value = replacement
assert facade.value is native.value is replacement
native.value = final
assert facade.value is native.value is final
assert saved_reference is initial
Echopy preserves native object identity; it does not clone a value or wrap it in a documentation object. This test proves dispatch on an owned Python module. It says nothing about whether a particular native attribute has a writable setter, accepts a type, or changes a document safely. Native setter errors propagate through either spelling. Any partial native side effects require their own preservation check.
Keep source-safe and native spellings connected
A native name that cannot appear in Python source receives a source identifier.
For this invented name, source_name("value-with-dash") is value_with_dash.
Use getattr/setattr/delattr for the original spelling; the source identifier
supports ordinary attribute syntax. Both routes must reach the same object.
Deletion must remove both visible spellings, and re-creation must reconnect them.
native_name = "value-with-dash"
alias = source_name(native_name)
assert alias == "value_with_dash"
initial, replacement = object(), object()
scope = {"attributes": [{"name": native_name, "type": "Any"}]}
with owned_pipeline(scope, values={native_name: initial}) as case:
facade, native = case.facade, case.native
assert getattr(facade, native_name) is facade.value_with_dash is initial
facade.value_with_dash = replacement
assert getattr(native, native_name) is replacement
assert getattr(facade, native_name) is facade.value_with_dash is replacement
assert {native_name, alias}.issubset(dir(facade))
delattr(facade, native_name)
assert not hasattr(native, native_name)
assert not hasattr(facade, native_name) and not hasattr(facade, alias)
assert native_name not in dir(facade) and alias not in dir(facade)
setattr(facade, alias, initial)
assert getattr(native, native_name) is getattr(facade, native_name) is initial
This is module dispatch. A sanitized class-member declaration does not add a
renamed member to an original native class: returning that class unchanged
preserves its identity. Consult the native spelling with getattr when needed.
The package import aliases echopy and fontlab_echopy are a separate mechanism;
the package guide checks those.
Reserve exact bookkeeping fields
The runtime keeps _echopy_native, _echopy_name and _echopy_aliases local.
Its child-facade import bookkeeping also remains special, so importing a child
facade cannot overwrite a native pseudo-namespace. These rules do not reserve
all _echopy_ spellings. The generator separately refuses helper-name collisions
before writing output; do not broaden its refusal policy to hide valid names.
This matrix exercises accepted invented names at both raw and merged stages.
It writes by both spellings, checks exact runtime state identities, deletes and
checks dir() again. _echopy_builtins is an accepted invented value here; raw
generation selects another private import alias when that name is occupied.
None of these spellings is asserted to exist in the running FontLab.
for stage in ("raw", "merged"):
for native_name in ("_echopy_value", "_echopy-value",
"_echopy_value-with-dash", "_echopy_builtins"):
for route in (native_name, source_name(native_name)):
initial, replacement = object(), object()
scope = {"attributes": [{"name": native_name, "type": "Any"}]}
with owned_pipeline(scope, values={native_name: initial}, stage=stage) as case:
facade, native = case.facade, case.native
state = {key: facade.__dict__[key] for key in
("_echopy_native", "_echopy_name", "_echopy_aliases")}
setattr(facade, route, replacement)
assert getattr(native, native_name) is replacement
assert getattr(facade, native_name) is replacement
assert getattr(facade, source_name(native_name)) is replacement
assert all(facade.__dict__[key] is value for key, value in state.items())
delattr(facade, route)
assert not hasattr(native, native_name)
for spelling in {native_name, source_name(native_name)}:
assert not hasattr(facade, spelling) and spelling not in dir(facade)
Keep annotation-only values absent offline
An annotation is documentation, not a value assignment. The generated source
and merged sidecar record an AnnAssign without a value. Offline loading keeps
the annotation while attribute reads fail. A type or doc overlay must not
materialize a sentinel, None or a fabricated constant.
native_name = "_echopy-value"
alias = source_name(native_name)
scope = {"attributes": [{"name": native_name, "type": "int", "doc": "Owned value."}]}
patch = {f"{OWNED_NATIVE}.{alias}": {"returns": "str", "doc": "Owned supplement."}}
for stage in ("raw", "merged"):
with owned_pipeline(scope, overlays=[patch], stage=stage) as case:
assert case.native is None
assert alias in case.facade.__annotations__
assert not hasattr(case.facade, alias)
assert not hasattr(case.facade, native_name)
stub = ast.parse((case.output / f"{OWNED_NATIVE}.pyi").read_text())
value = next(node for node in stub.body if isinstance(node, ast.AnnAssign))
assert value.value is None and ast.unparse(value.annotation) == "str"
For callable declarations, offline operations raise NativeUnavailable; see
unavailable native operations.
A missing annotation-only value instead has normal absent-attribute behavior.
A dir() entry or a declared type is not proof that an offline value exists.
Capture descriptor documentation without invoking its getter
Here a property object is stored directly on a plain owned module. Reading that
module member returns the descriptor itself; capture can read its documentation
without invoking the property getter. The deliberately failing getter makes the
boundary testable. This is not a claim that every native module getattr is
side-effect free, nor permission to run a fresh capture against a live host.
calls = []
def forbidden_getter(owner):
"""Owned captured descriptor documentation."""
calls.append(owner)
raise AssertionError("The property getter must never run")
owned = ModuleType(OWNED_NATIVE)
owned.value = property(forbidden_getter)
captured = capture_namespace(owned, OWNED_NATIVE)
before = copy.deepcopy(captured)
assert captured["attributes"][0]["doc"] == forbidden_getter.__doc__
with owned_pipeline(captured) as case:
raw_text = (case.raw / f"{OWNED_NATIVE}.py").read_text()
stub_text = (case.output / f"{OWNED_NATIVE}.pyi").read_text()
assert forbidden_getter.__doc__ in raw_text and forbidden_getter.__doc__ in stub_text
assert case.result == {"applied": 0, "unmatched": []}
assert captured == before and calls == []
Capture records errors explicitly. Documentation and a recorded descriptor type do not establish whether a native property is readable, writable or callable. A docstring that includes parentheses is not enough to turn an attribute into a method. Preserve recorded fields and limitations rather than guessing a setter.
Preserve docs for each value collection
The generator accepts module attributes, constants and modules collections.
Those are input collections; capture need not classify every object into all
three. Each collection emits an annotation followed immediately by its captured
docstring. The adjacent string belongs to the annotated value for documentation
consumers; moving it to the module header loses that association.
for collection in ("attributes", "constants", "modules"):
captured_doc = f"Owned {collection} documentation."
scope = {collection: [{"name": "value-with-dash", "type": "Any", "doc": captured_doc}]}
with owned_pipeline(scope) as case:
for path in (case.raw / f"{OWNED_NATIVE}.py", case.output / f"{OWNED_NATIVE}.pyi"):
tree = ast.parse(path.read_text())
index = next(i for i, node in enumerate(tree.body) if isinstance(node, ast.AnnAssign))
annotation, documentation = tree.body[index:index + 2]
assert annotation.target.id == "value_with_dash" and annotation.value is None
assert isinstance(documentation, ast.Expr)
assert documentation.value.value == captured_doc
assert not hasattr(case.facade, "value_with_dash")
Unknown captured types remain Any. That expresses missing type information;
it does not mean every object can safely be passed to a native setter.
The Python annotated assignment AST
records the target, annotation and optional value independently.
Target source identifiers and preserve overlay precedence
Overlay keys use the emitted source identifier: owned_echopy_values.value_with_dash
for native value-with-dash. On annotated attributes, the existing returns
field specifies the annotation override; it does not call a getter or describe a
method return. doc supplies supplemental prose and source gives its origin.
Overlays are combined in list order, field by field. A later field replaces the
earlier value for that field. Omitting a field in a later overlay retains the
earlier setting. The following intentionally includes one unmatched native-name
key to show the diagnostic, then verifies the correctly targeted source key.
The later doc replaces the earlier supplemental doc; the earlier float type
survives. Captured documentation remains first and appears once.
scope = {"attributes": [{"name": "value-with-dash", "type": "int", "doc": "Captured value."}]}
first = {f"{OWNED_NATIVE}.value_with_dash":
{"doc": "First supplement.", "returns": "float", "source": "owned-first"}}
last = {f"{OWNED_NATIVE}.value_with_dash":
{"doc": "Final supplement.", "source": "owned-final"},
f"{OWNED_NATIVE}.value-with-dash": {"doc": "Wrong target."}}
with owned_pipeline(scope, overlays=[first, last]) as case:
assert case.result == {"applied": 1, "unmatched": [f"{OWNED_NATIVE}.value-with-dash"]}
tree = ast.parse((case.output / f"{OWNED_NATIVE}.pyi").read_text())
index = next(i for i, node in enumerate(tree.body) if isinstance(node, ast.AnnAssign))
annotation, documentation = tree.body[index:index + 2]
assert ast.unparse(annotation.annotation) == "float"
assert documentation.value.value == ("Captured value.\n\nSupplemental documentation:\n"
"Final supplement.\n\nSource: owned-final")
assert "First supplement." not in documentation.value.value
An unmatched target must be investigated. It can mean a spelling error, an obsolete capture target or a patch for another producer; a green identity count does not prove the overlay was applied. Keep overlay inputs independent of regenerated raw output. Changing generation/merge code alone does not update already shipped captures, declarations, provenance or generated references.
Check the actual documentation consumer
An AST string check catches emission mistakes. It does not establish which
docstring a documentation consumer associates with the member. This example
uses Griffe's actual static visit API against the emitted .pyi, then compares
the member name, annotation and combined documentation. It does not import or
execute the sidecar. Griffe documents the API in its
agents reference.
from griffe import visit
scope = {"attributes": [{"name": "value-with-dash", "type": "Any", "doc": "Captured detail."}]}
patch = {f"{OWNED_NATIVE}.value_with_dash":
{"returns": "str", "doc": "Maintained detail.", "source": "owned-guide"}}
with owned_pipeline(scope, overlays=[patch]) as case:
stub = case.output / f"{OWNED_NATIVE}.pyi"
documented = visit(OWNED_NATIVE, filepath=stub, code=stub.read_text())
member = documented.members["value_with_dash"]
assert str(member.annotation) == "str"
assert member.docstring.value == ("Captured detail.\n\nSupplemental documentation:\n"
"Maintained detail.\n\nSource: owned-guide")
assert member.value is None
assert not hasattr(case.facade, "value_with_dash")
This establishes the owned source-to-Griffe path. It does not qualify rendered pages, navigation, type links, browser accessibility or a published site.
Keep the native facade small and lazy
Detailed value docs belong in the sidecar. Native loading must not parse that sidecar merely to obtain a value. This example generates an owned facade, removes its sidecar only inside the temporary directory, and re-executes it while its owned native module remains registered. If native binding required the sidecar, this would fail. The descriptor-free live value still has exact identity.
initial = object()
scope = {"attributes": [{"name": "value", "type": "Any", "doc": "Owned sidecar detail."}]}
with owned_pipeline(scope, values={"value": initial}) as case:
source = case.output / f"{OWNED_NATIVE}.py"
stub = source.with_suffix(".pyi")
facade_text = source.read_text()
assert "Owned sidecar detail." not in facade_text
assert "_populate(globals()," in facade_text
stub.unlink()
exec(compile(facade_text, str(source), "exec"), case.facade.__dict__)
assert case.facade.value is case.native.value is initial
Deleting a shipped sidecar would break offline analysis and packaging. The
example removes a disposable owned output solely to check native-path laziness;
retain every packaged .pyi and its licence/provenance in real distributions.
Interpret the evidence at its actual scope
A retained full identity audit covered 17 namespace scopes: 16 available and one
absent optional module. It matched 242,649 symbol identities and five root
namespace identities across declarations, alias maps and facade routes. Those
static matches do not classify every constructor or descriptor. The retained
census still has 1,600 variadic constructors, 13,035 variadic methods and 68,103
merged class attribute annotations typed Any. Exact historical raw capture
input was unavailable to that audit; a different local capture is not a valid
replacement. The retained upstream Qt enrichment report also has 35 failed
documents and 266 unmatched native classes. These are limitations of those
retained inputs, not newly measured current-host counts or results of this guide.
Captured docs, inferred annotations and reference signatures are evidence with provenance. They cannot prove native semantic completeness. A successful owned example is source-contract evidence; a fresh ordinary wheel/sdist run is installed-artifact evidence. Consumer qualification, native FontLab workflows, canonical promotion, generated-reference/source-lock refresh and publication remain independent acceptance levels. Read rebuild and contribute for the documented build process; obey the workspace's current approval and resource holds before attempting a capture, native run or generated build.