address Module

Address Class

class oscpython.address.Address(value: Optional[Any] = None, index: int = -1, pattern: str = '/', parts: Tuple[oscpython.address.AddressPart] = <factory>)

Bases: oscpython.arguments.StringArgument

An OSC address pattern

pattern: str = '/'

The OSC address string

parts: Tuple[oscpython.address.AddressPart]

A tuple of AddressPart instances derived from the pattern, delimited by forward slash ("/")

static parts_to_pattern(parts: Sequence[oscpython.address.AddressPart]) → str

Convert the given parts to an OSC address string

static pattern_to_parts(pattern: str) → Tuple[oscpython.address.AddressPart]

Convert the given OSC address string to a tuple of parts

get_pack_value() → Optional[Tuple[bytes]]

Get the value(s) to be packed using struct.pack()

Returns None if no value is associated with the argument, otherwise a tuple (even if there is only one item)

property is_concrete

True if the address is “concrete” (contains no pattern matching characters)

classmethod from_parts(parts: Sequence[oscpython.address.AddressPart]) → oscpython.address.Address

Create an instance from the given sequence of parts

copy() → oscpython.address.Address

Create a copy of the instance

join(other) → oscpython.address.Address

Join the address with either a str or Address instance, separating the pattern with "/"

match(other: Union[oscpython.address.Address, str]) → bool

Match this address with another using pattern-matching rules

Parameters

other – Either a str or Address instance

Returns

True if the given address matches

Return type

bool

AddressPart Class

class oscpython.address.AddressPart(part: str, is_root: bool, re_pattern: Optional[re.Pattern] = None, has_wildcard: Optional[bool] = None)

Bases: object

One “part” of an Address (delimited by forward slash)

property part

The address part as a string

property is_root

True if this is the first part of the Address

property re_pattern

The address part as a compiled re.Pattern to be used for OSC address pattern matching

property has_wildcard

True if the re_pattern contains any wildcard characters

match(other: oscpython.address.AddressPart) → bool

Match this instance with another AddressPart using OSC pattern matching

static compile_re(pattern: str) → Tuple[re.Pattern, bool]

Create a regular expression used for OSC address pattern matching

The pattern is only valid within the parts separated by forward slash ("/")

Returns

• pattern (re.Pattern) – The compiled pattern

• has_wildcard (bool) – True if the pattern contains any pattern-matching characters

AddressSpace Class

class oscpython.address.AddressSpace(*args, **kwargs)

Bases: pydispatch.dispatch.Dispatcher

An OSC address space, container for root (top-level) AddressNode instances

root_nodes

Mapping of root nodes using the name as keys

Type

Dict[str, oscpython.address.AddressNode]

Events

on_message(address: Address, message: Message, timetag: TimeTag)

Fired when a message is received by a server.

Parameters

• address (oscpython.address.Address) – The OSC address matching the message

• message (oscpython.messages.Message) – The OSC message

• timetag (oscpython.common.TimeTag) – The timestamp of when the message was received

add_root(name: str, cls: Optional[type] = None) → oscpython.address.AddressNode

Create an AddressNode and add it to root_nodes

Parameters

• name (str) – The node name

• cls (optional) – A subclass of AddressNode to use when creating the root node. If not provided, defaults to AddressNode

add_root_instance(node: oscpython.address.AddressNode)

Add an existing AddressNode instance to root_nodes

Parameters

node – The instance to add

create_from_address(address: Union[str, oscpython.address.Address], cls: Optional[type] = None) → oscpython.address.AddressNode

Create node or nodes from the given OSC address and return the final node on the tree

Parameters

• address – The OSC address

• cls – If provided, a subclass of AddressNode to use when creating node instances

Raises

KeyError – If the address is a root address (containing only one address part) and a node exists in root_nodes that does not match the given cls

find(address: Union[str, oscpython.address.Address]) → Optional[oscpython.address.AddressNode]

Search for a node matching the given address

Parameters

address – The address to search for

match(address: Union[str, oscpython.address.Address]) → Iterator[oscpython.address.AddressNode]

Iterate through any nodes or child nodes matching the given address

See AddressNode.match()

Parameters

address – The address to match

walk() → Iterator[oscpython.address.AddressNode]

Iterate over all root_nodes and their children

Calls walk() on each instances in root_nodes

get(key: str, default: Optional[Any] = None) → Optional[oscpython.address.AddressNode]

Get the root node matching the given name.

If not found, return the default value

Parameters

• key – The name

• default – The value to return if not found

keys() → KeysView[str]

Alias for root_nodes.keys

values() → ValuesView[oscpython.address.AddressNode]

Alias for root_nodes.values

items() → ItemsView[str, oscpython.address.AddressNode]

Alias for root_nodes.items

AddressNode Class

class oscpython.address.AddressNode(name: str, parent: Optional[oscpython.address.AddressNode] = None)

Bases: object

A node within an OSC address space

children

Mapping of child nodes using the name as keys

Type

Dict[str, oscpython.address.AddressNode]

Parameters

• name – The node name

• parent – The node parent

property name

The node name

property address

The full OSC address for the node

property address_part

The AddressPart for the node within its address

property parent

The parent node, or None if this is the root

property part_index

Index of the node address_part

property root

The root node of the tree

property address_space

The AddressSpace the node belongs to

property is_root

True if the node is at the root of the tree (has no parent)

property event_handler

An Event instance used for callbacks

property has_callbacks

True if any callbacks have been set on the node

add_callback(cb: Callable, aio_loop: Optional[asyncio.BaseEventLoop] = None)

Add a method, function or coroutine function to the event_handler

Parameters

• cb – The callback function

• aio_loop – If the callback is a coroutine function, the event loop associated with it

The callback should accept the signature:

def cb(node: oscpython.address.AddressNode,
       message: oscpython.messages.Message,
       timetag: oscpython.common.TimeTag) -> None:
    pass

Callback Arguments

node: AddressNode

The node instance that originated the event

message: messages.Message

The received message

timetag: common.TimeTag

Timestamp of when the message was received. See transport.BaseServer.handle_packet() for details

remove_callback(cb: Callable)

Remove a callback previously attached by add_callback()

dispatch(message: oscpython.messages.Message, timetag: oscpython.common.TimeTag)

Called when a message is received that matches this node address

Triggers any callbacks registered in the event_handler and emits the 'on_message' event on the address_space

Parameters

• message – The received message

• timetag – Timestamp of when the message was received.

find(address: Union[str, oscpython.address.Address]) → Optional[oscpython.address.AddressNode]

Search for a node matching the given relative address

Parameters

address – The address to search for

match(address: Union[str, oscpython.address.Address]) → Iterator[oscpython.address.AddressNode]

Iterate through any nodes or child nodes matching the given address

This uses the Address.match() method to follow OSC pattern matching rules

Parameters

address – The address to match

Note

The address argument must be absolute

walk() → Iterator[oscpython.address.AddressNode]

Iterate through this node and all of its descendants

create_message(*args, **kwargs) → oscpython.messages.Message

Create a Message using this node’s address

Positional and keyword arguments (*args and **kwargs) will be passed directly to messages.Message.create()

create_bundled_message(*args, **kwargs) → oscpython.messages.Bundle

Create a Bundle containing a Message using this node’s address

Keyword arguments (**kwargs) will be passed to the Bundle’s __init__ method and positional arguments (*args) will be passed to messages.Message.create()

add_child(name: str, cls: Optional[type] = None) → oscpython.address.AddressNode

Add a child node to this point in the tree

Parameters

• name (str) – The node name

• cls (optional) – A subclass of AddressNode to use when creating the child node. If not provided, the class is inherited

add_child_instance(child: oscpython.address.AddressNode)

Add an existing AddressNode instance to children

Parameters

child – The instance to add

create_children_from_address(address: Union[str, oscpython.address.Address]) → oscpython.address.AddressNode

Create node or nodes from the given (relative) OSC address and return the final node of the tree

Parameters

address – The OSC address (relative to this node)

classmethod create_from_address(address: Union[str, oscpython.address.Address]) → Tuple[oscpython.address.AddressNode, oscpython.address.AddressNode]

Create node or nodes from the given OSC address

Parameters

address – The OSC address

Returns

• node (AddressNode) – The first (root) node created

• last_child (AddressNode) – The last child created (the end of the address string)

get(key, default=None) → Optional[oscpython.address.AddressNode]

Get the child node matching the given name.

If not found, return the default value

keys() → KeysView[str]

Alias for children.keys()

values() → ValuesView[oscpython.address.AddressNode]

Alias for children.values()

items() → ItemsView[str, oscpython.address.AddressNode]

Alias for children.items()