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.
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.
- zerojson.common.dict_to_wire(data, with_version=True)[source]¶
Pack Python dictionary data into wire format.
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