# `Pyro4.util` — Utilities and serializers

Miscellaneous utilities, and serializers.

class `Pyro4.util.``CloudpickleSerializer`

  A (de)serializer that wraps the Cloudpickle serialization protocol. It can optionally compress the serialized data, and is thread safe.

class `Pyro4.util.``DillSerializer`

  A (de)serializer that wraps the Dill serialization protocol. It can optionally compress the serialized data, and is thread safe.

class `Pyro4.util.``JsonSerializer`

  (de)serializer that wraps the json serialization protocol.

class `Pyro4.util.``MarshalSerializer`

  (de)serializer that wraps the marshal serialization protocol.

  classmethod `class_to_dict`(obj)

    Convert a non-serializable object to a dict. Partly borrowed from serpent. Not used for the pickle serializer.

class `Pyro4.util.``MsgpackSerializer`

  (de)serializer that wraps the msgpack serialization protocol.

class `Pyro4.util.``PickleSerializer`

  A (de)serializer that wraps the Pickle serialization protocol. It can optionally compress the serialized data, and is thread safe.

class `Pyro4.util.``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. Not used for the pickle serializer.

  `deserializeCall`(data, compressed=False)

    Deserializes the given call data back to (object, method, vargs, kwargs) tuple. Set compressed to True to decompress the data first.

  `deserializeData`(data, compressed=False)

    Deserializes the given data (bytes). Set compressed to True to decompress the data first.

  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. Not used for the pickle serializer.

  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.

    This mechanism is not used for the pickle serializer.

  `serializeCall`(obj, method, vargs, kwargs, compress=False)

    Serialize the given method call parameters, try to compress if told so. Returns a tuple of the serialized data and a bool indicating if it is compressed or not.

  `serializeData`(data, compress=False)

    Serialize the given data object, try to compress if told so. Returns a tuple of the serialized data (bytes) and a bool indicating if it is compressed or not.

  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.

    This mechanism is not used for the pickle serializer.

class `Pyro4.util.``SerpentSerializer`

  (de)serializer that wraps the serpent serialization protocol.

  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. Not used for the pickle serializer.

`Pyro4.util.``excepthook`(ex_type, ex_value, ex_tb)

  An exception hook you can use for `sys.excepthook`, to automatically print remote Pyro tracebacks

`Pyro4.util.``fixIronPythonExceptionForPickle`(exceptionObject, addAttributes)

  Function to hack around a bug in IronPython where it doesn’t pickle exception attributes. We piggyback them into the exception’s args. Bug report is at https://github.com/IronLanguages/main/issues/943 Bug is still present in Ironpython 2.7.7

`Pyro4.util.``formatTraceback`(ex_type=None, ex_value=None, ex_tb=None, detailed=False)

  Formats an exception traceback. If you ask for detailed formatting, the result will contain info on the variables in each stack frame. You don’t have to provide the exception info objects, if you omit them, this function will obtain them itself using `sys.exc_info()`.

`Pyro4.util.``getAttribute`(obj, attr)

  Resolves an attribute name to an object. Raises an AttributeError if any attribute in the chain starts with a ‘`_`’. Doesn’t resolve a dotted name, because that is a security vulnerability. It treats it as a single attribute name (and the lookup will likely fail).

`Pyro4.util.``getPyroTraceback`(ex_type=None, ex_value=None, ex_tb=None)

  Returns a list of strings that form the traceback information of a Pyro exception. Any remote Pyro exception information is included. Traceback information is automatically obtained via `sys.exc_info()` if you do not supply the objects yourself.

`Pyro4.util.``get_exposed_members`(obj, only_exposed=True, as_lists=False, use_cache=True)

  Return public and exposed members of the given object’s class. You can also provide a class directly. Private members are ignored no matter what (names starting with underscore). If only_exposed is True, only members tagged with the @expose decorator are returned. If it is False, all public members are returned. The return value consists of the exposed methods, exposed attributes, and methods tagged as @oneway. (All this is used as meta data that Pyro sends to the proxy if it asks for it) as_lists is meant for python 2 compatibility.

`Pyro4.util.``get_exposed_property_value`(obj, propname, only_exposed=True)

  Return the value of an @exposed @property. If the requested property is not a @property or not exposed, an AttributeError is raised instead.

`Pyro4.util.``is_private_attribute`(attr_name)

  returns if the attribute name is to be considered private or not.

`Pyro4.util.``reset_exposed_members`(obj, only_exposed=True, as_lists=False)

  Delete any cached exposed members forcing recalculation on next request

`Pyro4.util.``set_exposed_property_value`(obj, propname, value, only_exposed=True)

  Sets the value of an @exposed @property. If the requested property is not a @property or not exposed, an AttributeError is raised instead.

# `Pyro4.socketutil` — Socket related utilities

Low level socket utilities.

class `Pyro4.socketutil.``SocketConnection`(sock, objectId=None, keep_open=False)

  A wrapper class for plain sockets, containing various methods such as `send()` and `recv()`

`Pyro4.socketutil.``bindOnUnusedPort`(sock, host='localhost')

  Bind the socket to a free port and return the port number. This code is based on the code in the stdlib’s test.test_support module.

`Pyro4.socketutil.``createBroadcastSocket`(bind=None, reuseaddr=False, timeout=<object object>, ipv6=False)

  Create a udp broadcast socket. Set ipv6=True to create an IPv6 socket rather than IPv4. Set ipv6=None to use the PREFER_IP_VERSION config setting.

`Pyro4.socketutil.``createSocket`(bind=None, connect=None, reuseaddr=False, keepalive=True, timeout=<object object>, noinherit=False, ipv6=False, nodelay=True, sslContext=None)

  Create a socket. Default socket options are keepalive and IPv4 family, and nodelay (nagle disabled). If ‘bind’ or ‘connect’ is a string, it is assumed a Unix domain socket is requested. Otherwise, a normal tcp/ip socket is used. Set ipv6=True to create an IPv6 socket rather than IPv4. Set ipv6=None to use the PREFER_IP_VERSION config setting.

`Pyro4.socketutil.``findProbablyUnusedPort`(family=<AddressFamily.AF_INET: 2>, socktype=<SocketKind.SOCK_STREAM: 1>)

  Returns an unused port that should be suitable for binding (likely, but not guaranteed). This code is copied from the stdlib’s test.test_support module.

`Pyro4.socketutil.``getInterfaceAddress`(ip_address)

  tries to find the ip address of the interface that connects to the given host’s address

`Pyro4.socketutil.``getIpAddress`(hostname, workaround127=False, ipVersion=None)

  Returns the IP address for the given host. If you enable the workaround, it will use a little hack if the ip address is found to be the loopback address. The hack tries to discover an externally visible ip address instead (this only works for ipv4 addresses). Set ipVersion=6 to return ipv6 addresses, 4 to return ipv4, 0 to let OS choose the best one or None to use config.PREFER_IP_VERSION.

`Pyro4.socketutil.``getIpVersion`(hostnameOrAddress)

  Determine what the IP version is of the given hostname or ip address (4 or 6). First, it resolves the hostname or address to get an IP address. Then, if the resolved IP contains a ‘:’ it is considered to be an ipv6 address, and if it contains a ‘.’, it is ipv4.

`Pyro4.socketutil.``getSSLcontext`(servercert='', serverkey='', clientcert='', clientkey='', cacerts='', keypassword='')

  creates an SSL context and caches it, so you have to set the parameters correctly before doing anything

`Pyro4.socketutil.``interruptSocket`(address)

  bit of a hack to trigger a blocking server to get out of the loop, useful at clean shutdowns

`Pyro4.socketutil.``receiveData`(sock, size)

  Retrieve a given number of bytes from a socket. It is expected the socket is able to supply that number of bytes. If it isn’t, an exception is raised (you will not get a zero length result or a result that is smaller than what you asked for). The partial data that has been received however is stored in the ‘partialData’ attribute of the exception object.

`Pyro4.socketutil.``sendData`(sock, data)

  Send some data over a socket. Some systems have problems with `sendall()` when the socket is in non-blocking mode. For instance, Mac OS X seems to be happy to throw EAGAIN errors too often. This function falls back to using a regular send loop if needed.

`Pyro4.socketutil.``setKeepalive`(sock)

  sets the SO_KEEPALIVE option on the socket, if possible.

`Pyro4.socketutil.``setNoDelay`(sock)

  sets the TCP_NODELAY option on the socket (to disable Nagle’s algorithm), if possible.

`Pyro4.socketutil.``setNoInherit`(sock)

  Mark the given socket fd as non-inheritable to child processes

`Pyro4.socketutil.``setReuseAddr`(sock)

  sets the SO_REUSEADDR option on the socket, if possible.