Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nokia/moler/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Moler is IO-agnostic. The same observer code runs on top of TCP, SSH, serial, in-memory, or any other transport. ConnectionFactory manages the registry of available transports and creates connection instances on demand. There are two entry points:
  • get_connection() — module-level convenience function. Handles named connections from configuration and variant resolution.
  • ConnectionFactory — the underlying class-based registry. Use directly to register custom transports or query available variants.
moler.connection_factory
  ├── get_connection()            # module-level function
  └── ConnectionFactory           # registry class

​
Module-level function

​
get_connection

from moler.connection_factory import get_connection

get_connection(
    name=None,
    io_type=None,
    variant=None,
    **constructor_kwargs,
) -> connection
Return a fully-configured connection instance. Provide either name or io_type, not both.
​
name
str
default:"None"
Name of a connection defined in Moler’s configuration. The factory looks up the io_type and constructor arguments from the configuration, then constructs the connection. The name value is also passed to the connection constructor (if it accepts it) so the connection’s logger is named accordingly.
​
io_type
str
default:"None"
Transport type. Built-in values include 'tcp', 'udp', 'ssh', 'terminal', 'sshshell', 'memory'. Custom types can be registered via ConnectionFactory.register_construction().
​
variant
str
default:"None"
Implementation variant such as 'threaded', 'asyncio', or 'twisted'. If None, the variant is resolved from the configuration’s default_variant mapping for the given io_type.
​
constructor_kwargs
Any
Additional keyword arguments forwarded directly to the connection constructor. For example, host and port for TCP connections.
Returns a connection object ready to be opened. Raises:
  • AssertionError — if neither name nor io_type is provided, or if both are provided.
  • KeyError — if the named connection is not in the configuration, or if variant is not registered.
  • AttributeError — if io_type='terminal' is requested on Windows.

​
ConnectionFactory class

ConnectionFactory implements the registry. All methods are class methods.

​
register_construction

ConnectionFactory.register_construction(
    io_type,
    variant,
    constructor,
) -> None
Register a callable that builds a connection of the given io_type/variant pair. Call this once at import time when providing a custom transport.
​
io_type
str
required
Transport type identifier, e.g. 'tcp', 'myserial'.
​
variant
str
required
Implementation variant identifier, e.g. 'threaded', 'asyncio'.
​
constructor
callable
required
Any callable — typically a class or a factory function — that accepts **constructor_kwargs and returns a connection instance. Must be callable; raises ValueError otherwise.

​
get_connection

ConnectionFactory.get_connection(
    io_type,
    variant,
    **constructor_kwargs,
) -> connection
Create and return a connection using the registered constructor for (io_type, variant). This is the low-level method; prefer the module-level get_connection() for normal use.
​
io_type
str
required
Transport type.
​
variant
str
required
Implementation variant.
​
constructor_kwargs
Any
Arguments forwarded to the registered constructor.
Raises KeyError if no constructor is registered for the (io_type, variant) pair.

​
available_variants

ConnectionFactory.available_variants(io_type) -> list[str]
Return the list of registered variant names for a given io_type.
​
io_type
str
required
Transport type to query.
Returns a list of variant strings, e.g. ['threaded', 'asyncio']. Returns an empty list if io_type has no registrations.

​
Usage examples

from moler.connection_factory import get_connection

conn = get_connection(
    io_type='tcp',
    variant='threaded',
    host='192.168.1.100',
    port=23,
)
conn.open()
try:
    # Subscribe a ConnectionObserver to conn.moler_connection
    # and run commands/events here
    pass
finally:
    conn.close()
Built-in connection types and their threaded variants are registered automatically on import of moler.connection_factory. You only need to call register_construction() when adding a completely new transport.
Since Moler 2.0.0 the default registered connection type uses MolerConnectionForSingleThreadRunner. If you rely on the older ThreadedMolerConnection behaviour, register it explicitly before creating connections.

Build docs developers (and LLMs) love

Get started for freeTalk to us