util.abstractGraph module

Graphs whose nodes and relations are persistent objects: an AbstractGraph is a PRDb (see util.persistence.pRef) of AGObject objects, each of which keeps track of the relations (AGRelation: an object with a src and a dst) that come in to it and go out from it. Relations are objects in their own right, so they can relate relations.

Created on Sep 10, 2026

Code author: Rob Kremer <robkremer@me.com>

class util.abstractGraph.AbstractGraph(url: str, mode='w', memoryResident: bool = True, _reading: bool = False)

Bases: PRDb, Generic

A persistent graph: a PRDb of AGObject objects – nodes and the relations between them.

__init__(url: str, mode: str = 'w', memoryResident: bool = True, _reading: bool = False)
Parameters:

  • url (str)

  • mode (str)

  • memoryResident (bool)

  • _reading (bool)

class util.abstractGraph.AGObject(db: TDB, **kwargs)

Bases: PRObject, Generic

An object in an AbstractGraph: it keeps the relations that come in to it and go out from it (AGRelation objects whose dst or src it is), which the relations maintain as they’re connected and disconnected.

__init__(db: TDB, **kwargs)
Parameters:

  • db (AbstractGraph) – The db to which this object will belong.

  • kwargs (Any) – Passed on to super().__init__(). AGObject is normally shared as a common ancestor by two (or more) of a subclass’s bases – eg: sn.model.model.Relation reaches AGObject through both GraphObject and AGRelation. Calling super().__init__(db=db, **kwargs) here (instead of naming PRObject directly, as this used to) lets the whole chain stay cooperative, so PRObject.__init__() – which registers this object with db – runs exactly once no matter how many of the subclass’s bases lead here, and kwargs is how a sibling base’s own constructor arguments (eg: AGRelation’s src/ dst, which AGObject itself has no use for) get carried through to it along that same chain.

_incoming: ValidatedList

Should only be assigned by Relation objects where self is at the dst end.

_outgoing: ValidatedList

Should only be assigned by Relation objects where self is at the src end and not write-locked.

_isConnected()
Returns:

Return type:

_disconnect(**kwargs) → None

Disconnect this object from it’s Model by:

  • unregistering it with the Model

  • unregistering (from other objects) the far ends of the relations, but keeping the close ends intact so that they may be later restored if necessary

  • unregistering all the above relations with the Model

Note

User this method when deleting an object with the potential to undo the deletion. Keep a pointer to the object and undo the deletion by calling its _reconnect() method.

Parameters:

kwargs

_reconnect(**kwargs)

Reconnect this disconnected object to it’s Model by:

  • reregistering it to the Model

  • reregistering (to other objects) the far ends of the relations

  • reregistering all the above relations with the Model

Note

This method should only be used to undo a _disconnect() operation.

Note

A relation r connecting two objects that are both being reconnected together (eg: a multi-selection undo of an erase, where r itself was one of the erased objects) gets reconnected as a side effect of whichever of the two objects is processed first: that object’s own r._reconnect(kept=self) call both registers r and re-appends it onto the other (not-yet-reconnected) object’s _incoming/_outgoing list, so that object sees r again once its own turn comes. Guarding with r._isConnected() below – mirroring the #TODO on _disconnect() about chains of transitive relations – is what keeps that second encounter from trying to reconnect (and re-assert) an already-reconnected r.

Parameters:

kwargs

class util.abstractGraph.AGNode(db: TDB, **kwargs)

Bases: AGObject[TDB, AGRelation], Generic

A node in an AbstractGraph: an AGObject that isn’t a relation.

class util.abstractGraph.AGRelation(db: TDB, src: T | None = None, dst: T | None = None, **kwargs)

Bases: AGObject[TDB, AGRelation], Generic

A relation in an AbstractGraph: an AGObject from a source (src) to a destination (dst), either of which may be any AGObject – including another relation – or None. Setting an end updates the ends’ lists of incoming and outgoing relations.

__init__(db: TDB, src: T | None = None, dst: T | None = None, **kwargs)
Parameters:

  • db (AbstractGraph) – The db to which this object will belong.

  • src (Optional[T]) – The source AGObject of this relation, or None.

  • dst (Optional[T]) – The destination AGObject of this relation, or None.

  • kwargs (Any) – Passed on to super().__init__() – see AGObject.__init__()’s kwargs param for why. AGRelation is normally combined with a sibling class (eg: sn.model.model.GraphObject, via sn.model.model.Relation) through multiple inheritance, so this carries through whatever constructor arguments that sibling needs that AGRelation itself doesn’t consume.

_dst: T | None
_src: T | None
property dst: T | None
Returns:

The destination of this relation, or None. (A subclass may calculate one it doesn’t have itself: eg: sn.model.model.Relation inherits its type’s.)

Return type:

T | None

property src: T | None
Returns:

The source of this relation, or None. (A subclass may calculate one it doesn’t have itself: eg: sn.model.model.Relation inherits its type’s.)

Return type:

T | None

connect(source: T | None = None, destination: T | None = None)

Connects or re-assigns the src and/or dst links by removing any existing links and setting the pointers in both this Relation and the target GraphObjects.

Note

Use this method during Relation construction or when modifying the source and/or destination of the Relation. This method ONLY applies to Relations. (contrast AGObject._disconnect() and AGObject._reconnect())

Parameters:
_reconnect(kept: T | None = None, **kwargs)
Parameters:

  • kept (T | None)

  • kwargs

_disconnect(keep: T | None = None, **kwargs) → None

Disconnects this relation from it’s src and dst by removing the pointers from the src and dst objects. The pointers to these object (in this relation) are kept intact. This relation is also removed from it’s containing Model object (it is removed from the Model’s list, but it’s db pointer remains intact.

This is typically useful for undo operations where, for example, a delete operation on an object can be undone by disconnecting the object, saving it, and if it on deletion and then re-connecting it if the delete is undone.

Parameters:

  • source (bool) – [default: False] Iff True the src side is disconnected.

  • destination (bool) – [default: False] Iff True the dst side is disconnected.

  • keep (T | None)

  • kwargs