PyCOM 0.6.0 documentation

Extending PyCOM

This section documents API bits required to extend PyCOM.

PyCOM Semi-public API

pycom.logger()

Default logger for ZeroJSON

pycom.ioloop()

Returns 0MQ IOLoop instance for current event loop.

Roughly equivalent to:

zmq.eventloop.IOLoop.instance()
pycom.create_task(callback, timeout)

Create repeating task.

Interface Declaration

class pycom.interfaces.Interface(wrapped, name, stateful=False, authentication=None)[source]

Internal object, representing interface.

Should not be created directly, only using pycom.interface(). Available through __interface__ attribute of objects with interface (and their classes).

Inherits pycom.BaseComponent, allows directly calling methods.

instance

Stored owner class instance.

methods

Dictionary of methods for this class, keys being method names, value being objects of type pycom.interfaces.Method.

stateful

Boolean value, whether this interface is stateful or not.

authentication

Authentication policy - see pycom.interface().

invoke_with_request(request, timeout=None)[source]

Invoke method using given request object.

timeout is ignored here.

Returns zerojson.Response object.

register_method(method_info)[source]

Register method with descriptor method_info of type pycom.interfaces.Method.

Raises RuntimeError if method with this name is already registered.

class pycom.interfaces.Method(wrapped, name, results=(), attachments=(None, None))[source]

Class for holding wrapped method.

Should not be created directly, only using pycom.method(). Available through __method__ attribute of any remote-invokable method.

wrapped

Link to original method.

name

Method name.

prehooks
posthooks

Lists of hooks that should be executed for pre- and post- processing incoming and outgoing data. Hook is a callable with the following signature:

hook(iface, method, data)
iface

pycom.interfaces.Interface object.

method

pycom.interfaces.Method object.

data

Data to be processed (zerojson.Request for prehooks, zerojson.Response for posthooks).

Example from tests:

import pycom

def setup_my_hook(meth):
    def my_hook(iface, method, data):
        pass  # ...
    meth.__method__.prehooks.append(my_hook)
    return meth

@pycom.interface("...")
class InterfaceWithMethods(pycom.Service):

    @setup_my_hook
    @pycom.method
    def method1(self, request):
        pass  # ...

Do NOT try to use things like functools.wraps and standard decorators on PyCOM methods, they behave in a different way.

required_arguments
optional_arguments

List of strings - required and optional arguments declaration. If present, input will be checked, pycom.BadRequest raised when necessary. Required arguments are passed as positional, optional - as keyword.

results

List of strings - results declaration. If present, output will be checked, resulting tuple will be unpacked, and JSON object will be sent back.

attachments

A tuple of 2 strings: names for incoming and outgoing attachment parameters. Mostly used in introspection and pycom.ProxyComponent. Defaults to (None, None).

call(iface, request)[source]

Call this method with given pycom.zerojson.Request.

iface should be pycom.interfaces.Interface object.

Returns zerojson.Response object.

post_configure(owner_iface)[source]

Called once owner_iface is fully configured.

Other

pycom.nsclient.detect_ns(host)[source]

Detect nameserver on a given host.

ZeroJSON Implementation

Higher-level API

class zerojson.Server(addresses)

Basic server instance.

Subclass and override handle_call to get a working server.

commands

Dictionary ‘command name’ -> ‘command implementation’.

session_factory

Factory for zerojson.Session objects.

handle_call(request)

Handle a single call.

prepare_call(request)

Prepare request to be passed to handle_call.

Returns prepared zerojson.Request.

process(request)

Process the request.

Do not override this method, override handle_call instead.

setup(ioloop=None)

Setup server on a given event loop.

class zerojson.Client(socket, iface)

Client component working over 0MQ network.

Takes 0MQ socket or address as socket and interface name as iface. Optionally takes client context.

close(**kwargs)

Closes accociated socket.

kwargs are passed to underlying 0MQ method.

invoke(method_name, args=None, timeout=None, attachment=None)

Invoke given method with args (see pycom.BaseComponent.invoke() for details).

invoke_with_request(request, timeout=None)

Invoke method using given request object.

Returns zerojson.Response object.

Commands Implementation

class zerojson.common.BaseCommand(server=None)[source]

Base implementation for any command.

Typical request-response processing chain looks like:

<client>
 request_to_wire (request_to_dict => dict_to_wire) ==>
<server>
 ==> request_from_wire (dict_from_wire => request_from_dict) ==>
 ==> process_request [request processing goes here] ==>
 ==> response_to_wire (response_to_dict => dict_to_wire) ==>
<client>
 ==> response_from_wire (dict_from_wire => response_from_dict)
process_request(json_body, *other_parts)[source]

Call to process request.

Override real_process_request to change behaviour.

real_process_request(request, *other_parts)[source]

Call to process request.

request_from_dict(data)[source]

Get request from Python dict.

request_from_wire(message)[source]

Unpack request from wire format.

request_to_dict(*args, **kw)[source]

Dump request to Python dict.

request_to_wire(request, **kw)[source]

Pack request to wire format.

response_from_dict(data)[source]

Get request from Python dict.

response_from_wire(message)[source]

Unpack request from wire format.

response_to_dict(response)[source]

Dump response to Python dict.

Base version just returns empty dict.

response_to_wire(response, **kw)[source]

Pack result to wire format.

zerojson.common.dict_to_wire(data, with_version=True)[source]

Pack Python dictionary data into wire format.

zerojson.common.dict_from_wire(data)[source]

Unpack Python dictionary from wire format data.

Raise BadRequest on errors.

class zerojson.call.CallCommand(server=None)[source]

CALL command implementation.

Constants

pycom.constants

Module with common constants for PyCOM:

# Versions

__version_info__ = (0, 6, 0, "")
__version__ = "%d.%d.%d%s" % __version_info__

# Standard stuff

GENERIC_METHOD_INTROSPECT = "introspect"

# Nameserver constants

NS_INTERFACE = "org.pycom.nameserver"
NS_METHOD_STAT = "stat"
NS_METHOD_LOCATE = "locate"
NS_METHOD_REGISTER = "register"
NS_METHOD_LIST_SERVICES = "list_services"
NS_SERVICE_TIMEOUT = 60000

# Authenticator constants

AUTH_INTERFACE = "org.pycom.authenticator"
AUTH_METHOD_AUTHENTICATE = "authenticate"
AUTH_METHOD_VALIDATE = "validate"
AUTH_EXTENSION = "org.pycom.auth"

# Other constants

NS_NAME_LOCAL = "local"
zerojson.constants

Module with common constants for ZeroJSON protocol:

# Versions

__version_info__ = (0, 5, 0, "")
__version__ = "%d.%d.%d%s" % __version_info__

# Error codes

ERROR_UNKNOWN = 1
ERROR_METHOD_NOT_FOUND = 2
ERROR_SERVICE_NOT_FOUND = 3
ERROR_BAD_REQUEST = 4
ERROR_ACCESS_DENIED = 5
ERROR_SESSION_EXPIRED = 6

# Protocol constants

PROTO_VERSION = "1.0"
PROTO_CMD_CALL = b"CALL"
PROTO_CMD_FINISH = b"FINISH"
PROTO_STATUS_SUCCESS = b"OK"
PROTO_STATUS_FAILURE = b"FAIL"
PROTO_DEFAULT_TIMEOUT = 5000
PROTO_SESSION_TIMEOUT = 3600 * 1000  # 1hr in ms