Pyro5.api — Main API package

Single module that centralizes the main symbols from the Pyro5 API. It imports most of the other packages that it needs and provides shortcuts to the most frequently used objects and functions from those packages. This means you can mostly just import Pyro5.api in your code to have access to most of the Pyro5 objects and functions.

class Pyro5.api.BatchProxy(proxy)

Proxy that lets you batch multiple method calls into one. It is constructed with a reference to the normal proxy that will carry out the batched calls. Call methods on this object that you want to batch, and finally call the batch proxy itself. That call will return a generator for the results of every method call in the batch (in sequence).

class Pyro5.api.Daemon(host=None, port=0, unixsocket=None, nathost=None, natport=None, interface=<class 'Pyro5.server.DaemonObject'>, connected_socket=None)

Pyro daemon. Contains server side logic and dispatches incoming remote method calls to the appropriate objects.

annotations()

Override to return a dict with custom user annotations to be sent with each response message.

clientDisconnect(conn)

Override this to handle a client disconnect. Conn is the SocketConnection object that was disconnected.

close()

Close down the server and release resources

combine(daemon)

Combines the event loop of the other daemon in the current daemon’s loop. You can then simply run the current daemon’s requestLoop to serve both daemons. This works fine on the multiplex server type, but doesn’t work with the threaded server type.

events(eventsockets)

for use in an external event loop: handle any requests that are pending for this daemon

handleRequest(conn)

Handle incoming Pyro request. Catches any exception that may occur and wraps it in a reply to the calling side, as to not make this server side loop terminate due to exceptions caused by remote invocations.

housekeeping()

Override this to add custom periodic housekeeping (cleanup) logic. This will be called every few seconds by the running daemon’s request loop.

locationStr

The location (str of the form host:portnumber) on which the Daemon is listening

proxyFor(objectOrId, nat=True)

Get a fully initialized Pyro Proxy for the given object (or object id) for this daemon. If nat is False, the configured NAT address (if any) is ignored. The object or id must be registered in this daemon, or you’ll get an exception. (you can’t get a proxy for an unknown object)

register(obj_or_class, objectId=None, force=False, weak=False)

Register a Pyro object under the given id. Note that this object is now only known inside this daemon, it is not automatically available in a name server. This method returns a URI for the registered object. Pyro checks if an object is already registered, unless you set force=True. You can register a class or an object (instance) directly. For a class, Pyro will create instances of it to handle the remote calls according to the instance_mode (set via @expose on the class). The default there is one object per session (=proxy connection). If you register an object directly, Pyro will use that single object for all remote calls. With weak=True, only weak reference to the object will be stored, and the object will get unregistered from the daemon automatically when garbage-collected.

requestLoop(loopCondition=<function Daemon.<lambda>>) None

Goes in a loop to service incoming requests, until someone breaks this or calls shutdown from another thread.

resetMetadataCache(objectOrId, nat=True)

Reset cache of metadata when a Daemon has available methods/attributes dynamically updated. Clients will have to get a new proxy to see changes

property selector

the multiplexing selector used, if using the multiplex server type

static serveSimple(objects, host=None, port=0, daemon=None, ns=True, verbose=True) None

Backwards compatibility method to fire up a daemon and start serving requests. New code should just use the global serve function instead.

shutdown()

Cleanly terminate a daemon that is running in the requestloop.

property sock

the server socket used by the daemon

property sockets

list of all sockets used by the daemon (server socket and all active client sockets)

unregister(objectOrId)

Remove a class or object from the known objects inside this daemon. You can unregister the class/object directly, or with its id.

uriFor(objectOrId, nat=True)

Get a URI for the given object (or object id) from this daemon. Only a daemon can hand out proper uris because the access location is contained in them. Note that unregistered objects cannot be given an uri, but unregistered object names can (it’s just a string we’re creating in that case). If nat is set to False, the configured NAT address (if any) is ignored and it will return an URI for the internal address.

validateHandshake(conn, data)

Override this to create a connection validator for new client connections. It should return a response data object normally if the connection is okay, or should raise an exception if the connection should be denied.

class Pyro5.api.DaemonObject(daemon)

The part of the daemon that is exposed as a Pyro object.

get_metadata(objectId)

Get metadata for the given object (exposed methods, oneways, attributes).

info()

return some descriptive information about the daemon

ping()

a simple do-nothing method for testing purposes

registered()

returns a list of all object names registered in this daemon

class Pyro5.api.Proxy(uri, connected_socket=None)

Pyro proxy for a remote object. Intercepts method calls and dispatches them to the remote object.

_pyroBind()

Bind this proxy to the exact object from the uri. That means that the proxy’s uri will be updated with a direct PYRO uri, if it isn’t one yet. If the proxy is already bound, it will not bind again.

_pyroRelease()

release the connection to the pyro daemon

_pyroReconnect(tries=100000000)

(Re)connect the proxy to the daemon containing the pyro object which the proxy is for. In contrast to the _pyroBind method, this one first releases the connection (if the proxy is still connected) and retries making a new connection until it succeeds or the given amount of tries ran out.

_pyroValidateHandshake(response)

Process and validate the initial connection handshake response data received from the daemon. Simply return without error if everything is ok. Raise an exception if something is wrong and the connection should not be made.

_pyroTimeout

The timeout in seconds for calls on this proxy. Defaults to None. If the timeout expires before the remote method call returns, Pyro will raise a Pyro5.errors.TimeoutError

_pyroMaxRetries

Number of retries to perform on communication calls by this proxy, allows you to override the default setting.

_pyroSerializer

Name of the serializer to use by this proxy, allows you to override the default setting.

_pyroHandshake

The data object that should be sent in the initial connection handshake message. Can be any serializable object.

_pyroLocalSocket

The socket that is used locally to connect to the remote daemon. The format depends on the address family used for the connection, but usually for IPV4 connections it is the familiar (hostname, port) tuple. Consult the Python documentation on socket families for more details

class Pyro5.api.SerializedBlob(info, data, is_blob=False)

Used to wrap some data to make Pyro pass this object transparently (it keeps the serialized payload as-is) Only when you need to access the actual client data you can deserialize on demand. This makes efficient, transparent gateways or dispatchers and such possible: they don’t have to de/reserialize the message and are independent from the serialized class definitions. You have to pass this as the only parameter to a remote method call for Pyro to understand it. Init arguments: info = some (small) descriptive data about the blob. Can be a simple id or name or guid. Must be marshallable. data = the actual client data payload that you want to transfer in the blob. Can be anything that you would otherwise have used as regular remote call arguments.

deserialized()

Retrieves the client data stored in this blob. Deserializes the data automatically if required.

class Pyro5.api.SerializerBase

Base class for (de)serializer implementations (which must be thread safe)

classmethod class_to_dict(obj)

Convert a non-serializable object to a dict. Partly borrowed from serpent.

classmethod dict_to_class(data)

Recreate an object out of a dict containing the class name and the attributes. Only a fixed set of classes are recognized.

classmethod register_class_to_dict(clazz, converter, serpent_too=True)

Registers a custom function that returns a dict representation of objects of the given class. The function is called with a single parameter; the object to be converted to a dict.

classmethod register_dict_to_class(classname, converter)

Registers a custom converter function that creates objects from a dict with the given classname tag in it. The function is called with two parameters: the classname and the dictionary to convert to an instance of the class.

classmethod unregister_class_to_dict(clazz)

Removes the to-dict conversion function registered for the given class. Objects of the class will be serialized by the default mechanism again.

classmethod unregister_dict_to_class(classname)

Removes the converter registered for the given classname. Dicts with that classname tag will be deserialized by the default mechanism again.

class Pyro5.api.URI(uri)

Pyro object URI (universal resource identifier). The uri format is like this: PYRO:objectid@location where location is one of:

  • hostname:port (tcp/ip socket on given port)

  • ./u:sockname (Unix domain socket on localhost)

There is also a ‘Magic format’ for simple name resolution using Name server:

PYRONAME:objectname[@location] (optional name server location, can also omit location port)

And one that looks up things in the name server by metadata:

PYROMETA:meta1,meta2,...[@location] (optional name server location, can also omit location port)

You can write the protocol in lowercase if you like (pyro:...) but it will automatically be converted to uppercase internally.

static isUnixsockLocation(location)

determine if a location string is for a Unix domain socket

property location

property containing the location string, for instance "servername.you.com:5555"

Pyro5.api.behavior(instance_mode: str = 'session', instance_creator: Callable | None = None) Callable

Decorator to specify the server behavior of your Pyro class.

Pyro5.api.callback(method: Callable) Callable

decorator to mark a method to be a ‘callback’. This will make Pyro raise any errors also on the callback side, and not only on the side that does the callback call.

Pyro5.api.expose(method_or_class: _T) _T

Decorator to mark a method or class to be exposed for remote calls. You can apply it to a method or a class as a whole. If you need to change the default instance mode or instance creator, also use a @behavior decorator.

Pyro5.api.locate_ns(host: str | IPv4Address | IPv6Address = '', port: int | None = None, broadcast: bool = True) client.Proxy

Get a proxy for a name server somewhere in the network.

Pyro5.api.oneway(method: Callable) Callable

decorator to mark a method to be oneway (client won’t wait for a response)

Pyro5.api.register_class_to_dict(clazz, converter, serpent_too=True)

Registers a custom function that returns a dict representation of objects of the given class. The function is called with a single parameter; the object to be converted to a dict.

Pyro5.api.register_dict_to_class(classname, converter)

Registers a custom converter function that creates objects from a dict with the given classname tag in it. The function is called with two parameters: the classname and the dictionary to convert to an instance of the class.

Pyro5.api.resolve(uri: str | URI, delay_time: float = 0.0) URI

Resolve a ‘magic’ uri (PYRONAME, PYROMETA) into the direct PYRO uri. It finds a name server, and use that to resolve a PYRONAME uri into the direct PYRO uri pointing to the named object. If uri is already a PYRO uri, it is returned unmodified. You can consider this a shortcut function so that you don’t have to locate and use a name server proxy yourself. Note: if you need to resolve more than a few names, consider using the name server directly instead of repeatedly calling this function, to avoid the name server lookup overhead from each call. You can set delay_time to the maximum number of seconds you are prepared to wait until a name registration becomes available in the nameserver.

Pyro5.api.serve(objects: Dict[Any, str], host: str | IPv4Address | IPv6Address | None = None, port: int = 0, daemon: Daemon | None = None, use_ns: bool = True, verbose: bool = True) None

Basic method to fire up a daemon (or supply one yourself). objects is a dict containing objects to register as keys, and their names (or None) as values. If ns is true they will be registered in the naming server as well, otherwise they just stay local. If you need to publish on a unix domain socket, or require finer control of the daemon’s behavior, you can’t use this shortcut method. Create a Daemon yourself and use its appropriate methods. See the documentation on ‘publishing objects’ (in chapter: Servers) for more details.

Pyro5.api.start_ns(host=None, port=None, enableBroadcast=True, bchost=None, bcport=None, unixsocket=None, nathost=None, natport=None, storage=None)

utility fuction to quickly get a Name server daemon to be used in your own event loops. Returns (nameserverUri, nameserverDaemon, broadcastServer).

Pyro5.api.start_ns_loop(host=None, port=None, enableBroadcast=True, bchost=None, bcport=None, unixsocket=None, nathost=None, natport=None, storage=None)

utility function that starts a new Name server and enters its requestloop.

Pyro5.api.type_meta(class_or_object, prefix='class:')

extracts type metadata from the given class or object, can be used as Name server metadata.

Pyro5.api.unregister_class_to_dict(clazz)

Removes the to-dict conversion function registered for the given class. Objects of the class will be serialized by the default mechanism again.

Pyro5.api.unregister_dict_to_class(classname)

Removes the converter registered for the given classname. Dicts with that classname tag will be deserialized by the default mechanism again.