colour.utilities.Port#

class colour.utilities.Port(name: str | None = None, value: Any = None, description: str = '', node: PortNode | None = None)[source]#

Bases: MixinLogging

Define a port object that serves as an input or output port (i.e., a pin) for a colour.utilities.PortNode class and connects to other input or output ports.

Parameters:

name (str | None) – Port name.
value (Any) – Initial value to set the port with.
description (str) – Port description.
node (PortNode | None) – Node to add the port to.

Attributes

name
value
description
node
connections
connections_incoming
connections_outgoing

Methods

__init__()
__str__()
is_input_port()
is_output_port()
connect()
disconnect()
to_graphviz()

Examples

>>> port = Port("a", 1, "Port A Description")
>>> port.name
'a'
>>> port.value
1
>>> port.description
'Port A Description'

__init__(name: str | None = None, value: Any = None, description: str = '', node: PortNode | None = None) → None[source]#

Parameters:

name (str | None)
value (Any)
description (str)
node (PortNode | None)

Return type:

None

property name: str#

Getter and setter for the port name.

Parameters:: value – Value to set the port name with.
Returns:: Port name.
Return type:: str

property value: Any#

Getter and setter for the port value.

Parameters:: value – Value to set the port value with.
Returns:: Port value.
Return type:: object

property description: str#

Getter and setter for the port description.

Parameters:: value – Value to set the port description with.
Returns:: Port description.
Return type:: str or None

property node: PortNode | None#

Getter and setter for the port node.

Parameters:: value (PortNode or None) – Port node to set.
Returns:: Port node.
Return type:: PortNode or None

property connections: OrderedSet[Port]#

Getter for the port connections, in both directions.

Returns:: Port connections.
Return type:: colour.utilities.OrderedSet

Notes

The returned ordered set is a copy, the incoming connections followed by the outgoing ones. Connecting and disconnecting is performed with colour.utilities.Port.connect() and colour.utilities.Port.disconnect().

property connections_incoming: OrderedSet[Port]#

Getter for the connections feeding the port.

Returns:: Port connections.
Return type:: colour.utilities.OrderedSet

Notes

An input port has at most one of them, that being the port producing its value.

property connections_outgoing: OrderedSet[Port]#

Getter for the connections the port feeds.

Returns:: Port connections.
Return type:: colour.utilities.OrderedSet

__str__() → str[source]#

Return a formatted string representation of the port.

Returns:: Formatted string representation.
Return type:: str

Examples

>>> print(Port("a"))
None.a (-> [])
>>> print(Port("a", node=PortNode("Port Node")))
Port Node.a (-> [])

is_input_port() → bool[source]#

Determine whether the port is an input port.

Returns:: Whether the port is an input port.
Return type:: bool

Examples

>>> Port().is_input_port()
False
>>> node = PortNode()
>>> node.add_input_port("a").is_input_port()
True

Notes

The port is compared by identity: a node is free to name an input port and an output port alike, and a lookup by name alone would report such a port as being both.

is_output_port() → bool[source]#

Determine whether the port is an output port.

Returns:: Whether the port is an output port.
Return type:: bool

Examples

>>> Port().is_output_port()
False
>>> node = PortNode()
>>> node.add_output_port("output").is_output_port()
True

Notes

The port is compared by identity, as it is in colour.utilities.Port.is_input_port().

connect(port: Port) → None[source]#

Connect this port to the specified port.

Parameters:: port (Port) – Port to connect to.
Raises:: ValueError – If an attempt is made to connect an input port to multiple output ports.
Return type:: None

Examples

>>> port_a = Port()
>>> port_b = Port()
>>> port_a.connections
OrderedSet([])
>>> port_b.connections
OrderedSet([])
>>> port_a.connect(port_b)
>>> port_a.connections
OrderedSet([<...Port object at 0x...>])
>>> port_b.connections
OrderedSet([<...Port object at 0x...>])

Notes

The connection is directed. An output port feeds an input port, whichever of the two the connection is made from. Two ports sharing a role are a graph passing a value to or from one of its own children, and there the port the connection is made from is the one feeding.
Connected ports carry the same value, so the connection reconciles them at once rather than leaving each holding its own default until something is set.
Connecting a pair already connected is not a second feeder and does not raise.

disconnect(port: Port) → None[source]#

Disconnect from the specified port.

Parameters:: port (Port) – Port to disconnect from.
Return type:: None

Examples

>>> port_a = Port()
>>> port_b = Port()
>>> port_a.connect(port_b)
>>> port_a.connections
OrderedSet([<...Port object at 0x...>])
>>> port_b.connections
OrderedSet([<...Port object at 0x...>])
>>> port_a.disconnect(port_b)
>>> port_a.connections
OrderedSet([])
>>> port_b.connections
OrderedSet([])

to_graphviz() → str[source]#

Generate a string representation for port visualisation with Graphviz.

Returns:: String representation for visualisation of the port with Graphviz.
Return type:: str

Examples

>>> Port("a").to_graphviz()
'<a> a'

colour.utilities.Port#

This Page