Connections

The Connections class can be used to manage any type of constraint within, and between items.

class gaphas.connections.Connections(solver: Solver | None = None)

Manage connections and constraints.

add_handler(handler)

Add a callback handler.

Handlers are triggered when a constraint has been solved.

remove_handler(handler)

Remove a previously assigned handler.

property solver: Solver

The solver used by this connections instance.

solve() → None

Solve all constraints.

add_constraint(item: Item, constraint: Constraint) → Constraint

Add a “simple” constraint for an item.

remove_constraint(item: Item, constraint: Constraint) → None

Remove an item specific constraint.

connect_item(item: Item, handle: Handle, connected: Item, port: Port | None, constraint: Constraint | None = None, callback: Callable[[Item, Handle, Item, Port], None] | None = None) → None

Create a connection between two items. The connection is registered and the constraint is added to the constraint solver.

The pair (item, handle) should be unique and not yet connected.

The callback is invoked when the connection is broken.

Parameters:

• item (Item) – Connecting item (i.e. a line).

• handle (Handle) – Handle of connecting item.

• connected (Item) – Connected item (i.e. a box).

• port (Port) – Port of connected item.

• constraint (Constraint) – Constraint to keep the connection in place.

• callback (() -> None) – Function to be called on disconnection.

ConnectionError is raised in case handle is already registered on a connection.

disconnect_item(item: Item, handle: Handle | None = None) → None

Disconnect the connections of an item.

If handle is not None, only the connection for that handle is disconnected.

remove_connections_to_item(item: Item) → None

Remove all connections (handles connected to and constraints) for a specific item (to and from the item).

This is some brute force cleanup (e.g. if constraints are referenced by items, those references are not cleaned up).

reconnect_item(item: Item, handle: Handle, port: Port | None = None, constraint: Constraint | None = None) → None

Update an existing connection.

This is used to provide a new constraint to the connection. item and handle are the keys to the to-be-updated connection.

get_connection(handle: Handle) → Connection | None

Get connection information for specified handle.

>>> c = Connections()
>>> from gaphas.item import Line
>>> line = Line()
>>> from gaphas import item
>>> i = item.Line()
>>> ii = item.Line()
>>> c.connect_item(i, i.handles()[0], ii, ii.ports()[0])
>>> c.get_connection(i.handles()[0])     
Connection(item=<gaphas.item.Line object at 0x...)
>>> c.get_connection(i.handles()[1])     
>>> c.get_connection(ii.handles()[0])    

get_connections(item: Item | None = None, handle: Handle | None = None, connected: Item | None = None, port: Port | None = None) → Iterator[Connection]

Return an iterator of connection information.

The list contains (item, handle). As a result an item may be in the list more than once (depending on the number of handles that are connected). If item is connected to itself it will also appear in the list.

>>> c = Connections()
>>> from gaphas import item
>>> i = item.Line()
>>> ii = item.Line()
>>> iii = item.Line()
>>> c.connect_item(i, i.handles()[0], ii, ii.ports()[0], None)

>>> list(c.get_connections(item=i)) 
[Connection(item=<gaphas.item.Line object at 0x...]
>>> list(c.get_connections(connected=i))
[]
>>> list(c.get_connections(connected=ii)) 
[Connection(item=<gaphas.item.Line object at 0x...]

>>> c.connect_item(ii, ii.handles()[0], iii, iii.ports()[0], None)
>>> list(c.get_connections(item=ii)) 
[Connection(item=<gaphas.item.Line object at 0x...]
>>> list(c.get_connections(connected=iii)) 
[Connection(item=<gaphas.item.Line object at 0x...]