graflo.architecture.evolution.preview_focus

One merge preview, narrowed to what a single equivalence or attribute is about.

A :class:~graflo.architecture.evolution.preview.MergePreview describes the whole merge; on a real schema that is too much to read at once. A focus target names one part of it, and :func:focus returns the preview of that part alone, every edge closed over the nodes it keeps:

• a cluster id (vertex-cluster-0): the merged class, its members, their attributes, the resources its identity reads and the findings on any of them;
• a merged attribute (merged:Machine.match_key): every edge into it, with the rows and classes those edges leave from;
• rest: the findings no other target holds, with the classes they name.

Selection is by node id, never by declared_by: that field is a cluster id for some edge kinds, a merged name, a side or a key space for others.

Attributes

AttributeScope = Literal['nontrivial', 'all'] module-attribute

REST = 'rest' module-attribute

__all__ = ['REST', 'AttributeScope', 'finding_positions', 'focus', 'focus_targets', 'resolve_target'] module-attribute

Classes

Functions:

finding_positions(preview, target)

Positions in preview.findings of the findings target holds.

Source code in graflo/architecture/evolution/preview_focus.py

def finding_positions(preview: MergePreview, target: str | int) -> list[int]:
    """Positions in ``preview.findings`` of the findings *target* holds."""
    selection = _select(preview, target)
    if selection is None:
        raise KeyError(f"no focus target {target!r}")
    return list(selection.findings)

focus(preview, target)

The part of preview that target is about.

Parameters:

Name	Type	Description	Default
preview	MergePreview	The whole preview.	required
target	str | int	A cluster id, a merged attribute node id, rest, or a position in the op's vertex_equivalences.	required

Returns:

Type	Description
MergePreview	A preview holding only the target's nodes, the edges between them,
MergePreview	their findings in the original order, and the cluster they belong to.

Raises:

Type	Description
KeyError	target is none of these; the message lists the valid ones.

Source code in graflo/architecture/evolution/preview_focus.py

def focus(preview: MergePreview, target: str | int) -> MergePreview:
    """The part of *preview* that *target* is about.

    Args:
        preview: The whole preview.
        target: A cluster id, a merged attribute node id, ``rest``, or a
            position in the op's ``vertex_equivalences``.

    Returns:
        A preview holding only the target's nodes, the edges between them,
        their findings in the original order, and the cluster they belong to.

    Raises:
        KeyError: *target* is none of these; the message lists the valid ones.
    """
    selection = _select(preview, target)
    if selection is None:
        valid = focus_targets(preview, attributes="all")
        raise KeyError(f"no focus target {target!r}; valid targets: {valid}")
    into = selection.cluster.into if selection.cluster else None
    return preview.model_copy(
        update={
            "nodes": [n for n in preview.nodes if n.id in selection.nodes],
            "edges": list(selection.edges),
            "clusters": [selection.cluster] if selection.cluster else [],
            "findings": [preview.findings[i] for i in selection.findings],
            "routing": [r for r in preview.routing if into and r.vertex == into],
        }
    )

focus_targets(preview, attributes='nontrivial')

Every target of preview, in the order a reader should take them.

Each vertex cluster is followed by its merged attributes, then come the relation clusters, then rest when some finding is held by no other target. Every finding lands in at least one target.

Parameters:

Name	Type	Description	Default
preview	MergePreview	The whole preview.	required
attributes	AttributeScope	Which merged attributes become targets of their own.	'nontrivial'

Source code in graflo/architecture/evolution/preview_focus.py

def focus_targets(
    preview: MergePreview, attributes: AttributeScope = "nontrivial"
) -> list[str]:
    """Every target of *preview*, in the order a reader should take them.

    Each vertex cluster is followed by its merged attributes, then come the
    relation clusters, then ``rest`` when some finding is held by no other
    target. Every finding lands in at least one target.

    Args:
        preview: The whole preview.
        attributes: Which merged attributes become targets of their own.
    """
    out: list[str] = []
    for cluster in _ordered_clusters(preview):
        out.append(cluster.id)
        if cluster.kind == "vertex":
            out.extend(
                node_id
                for node_id in _merged_attributes(preview, cluster)
                if attributes == "all" or _nontrivial(preview, cluster, node_id)
            )
    if _rest_findings(preview):
        out.append(REST)
    return out

resolve_target(preview, target)

The target id target names, or None.

An integer, or a string of digits, is a position in the op's vertex_equivalences: it names the cluster that declaration folded into.

Source code in graflo/architecture/evolution/preview_focus.py

def resolve_target(preview: MergePreview, target: str | int) -> str | None:
    """The target id *target* names, or ``None``.

    An integer, or a string of digits, is a position in the op's
    ``vertex_equivalences``: it names the cluster that declaration folded into.
    """
    if isinstance(target, int) or target.isdigit():
        position = int(target)
        return next(
            (
                c.id
                for c in preview.clusters
                if c.kind == "vertex" and position in c.declarations
            ),
            None,
        )
    return target