Attributes

Attribute table helpers from annnet.core._Annotation.

These methods are mixed into AnnNet. Direct imports from underscore modules follow the internal API policy.

annnet.core._Annotation.AttributesClass

Attribute accessors and upsert helpers.

This mixin owns graph-, vertex-, edge-, slice-, and edge-slice-level metadata. Structural topology is intentionally excluded; only non-structural user attributes are stored in the annotation tables.

Functions

set_graph_attribute

set_graph_attribute(key, value)

Set a graph-level attribute.

Parameters:

Name	Type	Description	Default
`key`	`str`	Attribute name.	required
`value`	`Any`	Attribute value.	required

get_graph_attribute

get_graph_attribute(key, default=None)

Get a graph-level attribute.

Parameters:

Name	Type	Description	Default
`key`	`str`	Attribute name.	required
`default`	`Any`	Value to return if the attribute is missing.	`None`

Returns:

Type	Description
`Any`

set_vertex_attrs

set_vertex_attrs(vertex_id, **attrs)

Upsert pure vertex attributes (non-structural) into the vertex table.

Parameters:

Name	Type	Description	Default
`vertex_id`	`str`	Vertex identifier.	required
`**attrs`		Attribute key/value pairs.	`{}`

Raises:

Type	Description
`ValueError`	If any key is structurally reserved (e.g. `vertex_id`).

set_vertex_attrs_bulk

set_vertex_attrs_bulk(updates)

Upsert vertex attributes in bulk.

Parameters:

Name	Type	Description	Default
`updates`	`dict[str, dict] \| Iterable[tuple[str, dict]]`	Mapping or iterable of `(vertex_id, attrs)` pairs.	required

get_attr_vertex

get_attr_vertex(vertex_id, key, default=None)

Get a single vertex attribute (scalar) or default if missing.

Parameters:

Name	Type	Description	Default
`vertex_id`	`str`	Vertex identifier.	required
`key`	`str`	Attribute name.	required
`default`	`Any`	Value to return if missing.	`None`

Returns:

Type	Description
`Any`

set_edge_attrs

set_edge_attrs(edge_id, **attrs)

Upsert pure edge attributes (non-structural) into the edge DF.

Parameters:

Name	Type	Description	Default
`edge_id`	`str`	Edge identifier.	required
`**attrs`		Attribute key/value pairs.	`{}`

Raises:

Type	Description
`ValueError`	If any key is structurally reserved (e.g. `edge_id`, `source`, `target`, `weight`, `members`, `head`, `tail`, `flexible`).

set_edge_attrs_bulk

set_edge_attrs_bulk(updates)

Upsert edge attributes in bulk.

Parameters:

Name	Type	Description	Default
`updates`	`dict[str, dict] \| Iterable[tuple[str, dict]]`	Mapping or iterable of `(edge_id, attrs)` pairs.	required

get_attr_edge

get_attr_edge(edge_id, key, default=None)

Get a single edge attribute (scalar) or default if missing.

Parameters:

Name	Type	Description	Default
`edge_id`	`str`	Edge identifier.	required
`key`	`str`	Attribute name.	required
`default`	`Any`	Value to return if missing.	`None`

Returns:

Type	Description
`Any`

set_slice_attrs

set_slice_attrs(slice_id, **attrs)

Upsert pure slice attributes.

Parameters:

Name	Type	Description	Default
`slice_id`	`str`	Slice identifier.	required
`**attrs`		Attribute key/value pairs. Structural keys are ignored.	`{}`

get_slice_attr

get_slice_attr(slice_id, key, default=None)

Get a single slice attribute (scalar) or default if missing.

Parameters:

Name	Type	Description	Default
`slice_id`	`str`	Slice identifier.	required
`key`	`str`	Attribute name.	required
`default`	`Any`	Value to return if missing.	`None`

Returns:

Type	Description
`Any`

set_edge_slice_attrs

set_edge_slice_attrs(slice_id, edge_id, **attrs)

Upsert per-slice attributes for a specific edge.

Parameters:

Name	Type	Description	Default
`slice_id`	`str`	Slice identifier.	required
`edge_id`	`str`	Edge identifier.	required
`**attrs`		Attribute key/value pairs. Structural keys are ignored except `weight`.	`{}`

get_edge_slice_attr

get_edge_slice_attr(slice_id, edge_id, key, default=None)

Get a per-slice attribute for an edge.

Parameters:

Name	Type	Description	Default
`slice_id`	`str`	Slice identifier.	required
`edge_id`	`str`	Edge identifier.	required
`key`	`str`	Attribute name.	required
`default`	`Any`	Value to return if missing.	`None`

Returns:

Type	Description
`Any`

set_slice_edge_weight

set_slice_edge_weight(slice_id, edge_id, weight)

Set a legacy per-slice weight override for an edge.

Parameters:

Name	Type	Description	Default
`slice_id`	`str`	Slice identifier.	required
`edge_id`	`str`	Edge identifier.	required
`weight`	`float`	Weight override.	required

Raises:

Type	Description
`KeyError`	If the slice or edge does not exist.

get_effective_edge_weight

get_effective_edge_weight(edge_id, slice=None)

Resolve the effective weight for an edge, optionally within a slice.

Parameters:

Name	Type	Description	Default
`edge_id`	`str`	Edge identifier.	required
`slice`	`str`	Slice to read the override from. When omitted, the graph's currently active slice is used. Pass an explicit slice ID to override the active-slice resolution.	`None`

Returns:

Type	Description
`float`	Effective weight.

audit_attributes

audit_attributes()

Audit attribute tables for extra/missing rows and invalid edge-slice pairs.

Returns:

Type	Description
`dict`	Summary with keys: - `extra_vertex_rows` - `extra_edge_rows` - `missing_vertex_rows` - `missing_edge_rows` - `invalid_edge_slice_rows`

get_edge_attrs

get_edge_attrs(edge)

Return the full attribute dict for a single edge.

Parameters:

Name	Type	Description	Default
`edge`	`int \| str`	Edge index or edge ID.	required

Returns:

Type	Description
`dict`	Attribute dictionary for that edge. Empty if not found.

get_vertex_attrs

get_vertex_attrs(vertex)

Return the full attribute dict for a single vertex.

Parameters:

Name	Type	Description	Default
`vertex`	`str`	Vertex ID.	required

Returns:

Type	Description
`dict`	Attribute dictionary for that vertex. Empty if not found.

get_attr_edges

get_attr_edges(indexes=None)

Retrieve edge attributes as a dictionary.

Parameters:

Name	Type	Description	Default
`indexes`	`Iterable[int] \| None`	Edge indices to retrieve. If None, returns all edges.	`None`

Returns:

Type	Description
`dict[str, dict]`	Mapping of `edge_id` to attribute dictionaries.

get_attr_vertices

get_attr_vertices(vertices=None)

Retrieve vertex (vertex) attributes as a dictionary.

Parameters:

Name	Type	Description	Default
`vertices`	`Iterable[str] \| None`	Vertex IDs to retrieve. If None, returns all vertices.	`None`

Returns:

Type	Description
`dict[str, dict]`	Mapping of `vertex_id` to attribute dictionaries.

get_attr_from_edges

get_attr_from_edges(key, default=None)

Extract a specific attribute column for all edges.

Parameters:

Name	Type	Description	Default
`key`	`str`	Attribute column name to extract.	required
`default`	`Any`	Value to use if the column or value is missing.	`None`

Returns:

Type	Description
`dict[str, Any]`	Mapping of `edge_id` to attribute values.

get_edges_by_attr

get_edges_by_attr(key, value)

Retrieve all edges where a given attribute equals a specific value.

Parameters:

Name	Type	Description	Default
`key`	`str`	Attribute column name to filter on.	required
`value`	`Any`	Value to match.	required

Returns:

Type	Description
`list[str]`	Edge IDs where the attribute equals `value`.

get_graph_attributes

get_graph_attributes()

Return a shallow copy of the graph-level attributes dictionary.

Returns:

Type	Description
`dict`	Shallow copy of global graph metadata.

Notes

Returned value is a shallow copy to prevent external mutation.

set_edge_slice_attrs_bulk

set_edge_slice_attrs_bulk(slice_id, items)

Upsert edge-slice attributes for a single slice in bulk.

Parameters:

Name	Type	Description	Default
`slice_id`	`str`	Slice identifier.	required
`items`	`Iterable[tuple[str, dict]] \| dict[str, dict]`	Iterable or mapping of `(edge_id, attrs)` pairs.	required

annnet.core._Annotation.AttributesAccessor

Namespace for graph, vertex, edge, and slice annotations.