Pyro4.core — core Pyro logic

Core logic (uri, daemon, proxy stuff).

class Pyro4.core.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.

asString()

the string representation of this object

static isUnixsockLocation(location)

determine if a location string is for a Unix domain socket

location

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

class Pyro4.core.Proxy(uri)

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.

_pyroBatch()

returns a helper class that lets you create batched method calls on the proxy

_pyroAsync(async=True)

turns the proxy into async mode so you can do asynchronous method calls, or sets it back to normal sync mode if you set async=False.

_pyroAnnotations()

Override to return a dict with custom user annotations to be sent with each request message. Code using Pyro 4.56 or newer can skip this and instead set the annotations directly on the context object.

_pyroResponseAnnotations(annotations, msgtype)

Process any response annotations (dictionary set by the daemon). Usually this contains the internal Pyro annotations such as hmac and correlation id, and if you override the annotations method in the daemon, can contain your own annotations as well. Code using Pyro 4.56 or newer can skip this and instead read the response_annotations directly from the context object.

_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 Pyro4.errors.TimeoutError

_pyroHmacKey

the HMAC key (bytes) that this proxy uses

_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.

class Pyro4.core.Daemon(host=None, port=0, unixsocket=None, nathost=None, natport=None, interface=<class ‘Pyro4.core.DaemonObject’>)

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 = None

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

natLocationStr = None

The NAT-location (str of the form nathost:natportnumber) on which the Daemon is exposed for use with NAT-routing

objectsById = None

Dictionary from Pyro object id to the actual Pyro object registered by this id

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)

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.

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

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

selector

the multiplexing selector used, if using the multiplex server type

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

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 you can’t use this shortcut method. See the documentation on ‘publishing objects’ (in chapter: Servers) for more details.

shutdown()

Cleanly terminate a daemon that is running in the requestloop.

sock

the server socket used by the daemon

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 Pyro4.core.DaemonObject(daemon)

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

get_metadata(objectId, as_lists=False)

Get metadata for the given object (exposed methods, oneways, attributes). If you get an error in your proxy saying that ‘DaemonObject’ has no attribute ‘get_metadata’, you’re probably connecting to an older Pyro version (4.26 or earlier). Either upgrade the Pyro version or set METADATA config item to False in your client code.

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

Pyro4.core.callback(method)

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.

Pyro4.core.batch(proxy)

convenience method to get a batch proxy adapter

Pyro4.core.async(proxy, async=True)

convenience method to set proxy to async or sync mode.

Pyro4.core.expose(method_or_class)

Decorator to mark a method or class to be exposed for remote calls (relevant when REQUIRE_EXPOSE=True) 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.

Pyro4.core.behavior(instance_mode=’session’, instance_creator=None)

Decorator to specify the server behavior of your Pyro class.

Pyro4.core.oneway(method)

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

Pyro4.core.current_context = <Pyro4.core._CallContext object>

the context object for the current call. (thread-local)

class Pyro4.core._StreamResultIterator(streamId, proxy)

Pyro returns this as a result of a remote call which returns an iterator or generator. It is a normal iterable and produces elements on demand from the remote iterator. You can simply use it in for loops, list comprehensions etc.

class Pyro4.core.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.