varlink - varlink Documentation
An implementation of the varlink protocol
See https://www.varlink.org for more information about the varlink protocol and interface definition
files.
For server implementations use the varlink.Server class.
For client implementations use the varlink.Client class.
For installation and examples, see the GIT repository https://github.com/varlink/python. or the sourcecode of varlink.tests.test_orgexamplemoreclassvarlink.Client(address=None,resolve_interface=None,resolver=None)
Bases: object
Varlink client class.
>>> with varlink.Client("unix:/run/org.example.ping") as client, client.open('org.example.ping') as connection:
>>> assert connection.Ping("Test")["pong"] == "Test"
If the varlink resolver is running:
>>> client = varlink.Client(resolve_interface='com.redhat.logging')
>>> print(client.get_interfaces()['com.redhat.logging'].get_description())
# Query and monitor the log messages of a system.
interface com.redhat.logging
type Entry (cursor: string, time: string, message: string, process: string, priority: string)
# Monitor the log. Returns the @initial_lines most recent entries in the
# first reply and then continuously replies when new entries are available.
method Monitor(initial_lines: int) -> (entries: Entry[])
>>> connection = client.open("com.redhat.logging")
connection now holds an object with all the varlink methods available.
Do varlink method call with varlink arguments and a single varlink return structure wrapped in a
namespace class:
>>> ret = connection.Monitor(initial_lines=1)
>>> ret
namespace(entries=[namespace(cursor='s=[…]',
message="req:1 'dhcp4-change' [wlp3s0][…]", priority='critical',
process='nm-dispatcher', time='2018-01-29 12:19:59Z')])
>>> ret.entries[0].process
'nm-dispatcher'
Do varlink method call with varlink arguments and a multiple return values in monitor mode, using
the "_more" keyword:
>>> for m in connection.Monitor(_more=True):
>>> for e in m.entries:
>>> print("%s: %s" % (e.time, e.message))
2018-01-29 12:19:59Z: [system] Activating via systemd: service name='[…]
2018-01-29 12:19:59Z: Starting Network Manager Script Dispatcher Service...
2018-01-29 12:19:59Z: bound to 10.200.159.150 -- renewal in 1423 seconds.
2018-01-29 12:19:59Z: [system] Successfully activated service 'org.freedesktop.nm_dispatcher'
2018-01-29 12:19:59Z: Started Network Manager Script Dispatcher Service.
2018-01-29 12:19:59Z: req:1 'dhcp4-change' [wlp3s0]: new request (6 scripts)
2018-01-29 12:19:59Z: req:1 'dhcp4-change' [wlp3s0]: start running ordered scripts...
"_more" is special to this python varlink binding. If "_more=True", then the method call does not
return a normal namespace wrapped varlink return value, but a generator, which yields the return
values and waits (blocks) for the service to return more return values in the generator's
.__next__() call.
__init__(address=None,resolve_interface=None,resolver=None)
Creates a Client object to reach the interfaces of a varlink service. For more
constructors see the class constructor methods new_with_*() returning an Client object.
Parameters
• address -- the exact address like "unix:/run/org.varlink.resolver"
• resolve_interface -- an interface name, which is resolved with the system wide
resolver
• resolver -- the exact address of the resolver to be used to resolve the interface
name
RaisesConnectionError -- could not connect to the service or resolver
add_interface(interface)
Manually add or overwrite an interface definition from an Interface object.
Parametersinterface -- an Interface() object
cleanup()get_interface(interface_name,socket_connection=None)get_interfaces(socket_connection=None)
Returns the a list of Interface objects the service implements.
handler
alias of SimpleClientInterfaceHandlerclassmethodnew_with_activate(argv)
Creates a Client object to a varlink service server started via socket activation.
Parametersargv -- executable in argv[0] and parameters in argv[1:] to run the varlink service
server via socket activation.
classmethodnew_with_address(address)
Creates a Client object to reach the interfaces of a varlink service.
Parametersaddress -- the exact address like "unix:/run/org.varlink.resolver"
RaisesConnectionError -- could not connect to the service or resolver
classmethodnew_with_bridge(argv)
Creates a Client object to a varlink service started via the bridge command. The bridge
command like "ssh <host> varlink bridge" is executed for every connection. This client
object will do IO via stdio to the bridge command.
Parametersargv -- executable in argv[0] and parameters in argv[1:] to run the varlink service
server via the bridge connection.
classmethodnew_with_resolved_interface(interface,resolver_address=None)
Creates a Client object to reach the interfaces of a varlink service.
Parameters
• interface -- an interface name, which is resolved with the system wide resolver
• resolver_address -- the exact address of the resolver to be used to resolve the
interface name
RaisesConnectionError -- could not connect to the service or resolver
open(interface_name,namespaced=False,connection=None)
Open a new connection and get a client interface handle with the varlink methods installed.
Parameters
• interface_name -- an interface name, which the service this client object is
connected to, provides.
• namespaced -- If arguments and return values are instances of SimpleNamespace
rather than dictionaries.
• connection -- If set, get the interface handle for an already opened connection.
RaisesInterfaceNotFound -- if the interface is not found
open_connection()
Open a new connection and return the socket. :exception OSError: anything socket.connect()
throws
classvarlink.ClientInterfaceHandler(interface,namespaced=False)
Bases: object
Base class for varlink client, which wraps varlink methods of an interface to the class
__init__(interface,namespaced=False)
Base class for varlink client, which wraps varlink methods of an interface.
The object allows to talk to a varlink service, which implements the specified interface
transparently by calling the methods. The call blocks until enough messages are received.
For monitor calls with '_more=True' a generator object is returned.
Parameters
• interface -- an Interface object
• namespaced -- if True, varlink methods return SimpleNamespace objects instead of
dictionaries
close()
To be implemented.
exceptionvarlink.ConnectionError
Bases: OSError
Connection error.
__init__(*args,**kwargs)classvarlink.ForkingServer(server_address,RequestHandlerClass,bind_and_activate=True)
Bases: ForkingMixIn, Serverclassvarlink.Interface(description)
Bases: object
Class for a parsed varlink interface definition.
__init__(description)
description -- description string in varlink interface definition language
filter_params(parent_name,varlink_type,_namespaced,args,kwargs)get_description()
return the description string in varlink interface definition language
get_method(name)exceptionvarlink.InterfaceNotFound(interface)
Bases: VarlinkError
The standardized varlink InterfaceNotFound error as a python exception
__init__(interface)classmethodnew(message,namespaced=False)exceptionvarlink.InvalidParameter(name)
Bases: VarlinkError
The standardized varlink InvalidParameter error as a python exception
__init__(name)classmethodnew(message,namespaced=False)exceptionvarlink.MethodNotFound(method)
Bases: VarlinkError
The standardized varlink MethodNotFound error as a python exception
__init__(method)classmethodnew(message,namespaced=False)exceptionvarlink.MethodNotImplemented(method)
Bases: VarlinkError
The standardized varlink MethodNotImplemented error as a python exception
__init__(method)classmethodnew(message,namespaced=False)classvarlink.RequestHandler(request,client_address,server)
Bases: StreamRequestHandler
Varlink request handler
To use as an argument for the VarlinkServer constructor. Instantiate your own class and set the
class variable service to your global Service object.
handle()service=Noneclassvarlink.Scanner(string)
Bases: object
Class for scanning a varlink interface definition.
__init__(string)end()expect(expected)get(expected)read_member()read_struct()read_type(lastmaybe=False)classvarlink.Server(server_address,RequestHandlerClass,bind_and_activate=True)
Bases: BaseServer
The same as the standard socketserver.TCPServer, to initialize with a subclass of RequestHandler.
>>> import varlink
>>> import os
>>>
>>> service = varlink.Service(vendor='Example', product='Examples', version='1', url='http://example.com',
>>> interface_dir=os.path.dirname(__file__))
>>>
>>> class ServiceRequestHandler(varlink.RequestHandler):
>>> service = service
>>>
>>> @service.interface('com.example.service')
>>> class Example:
>>> # com.example.service method implementation here …
>>> pass
>>>
>>> server = varlink.ThreadingServer(sys.argv[1][10:], ServiceRequestHandler)
>>> server.serve_forever()
__init__(server_address,RequestHandlerClass,bind_and_activate=True)
Constructor. May be extended, do not override.
address_family=2allow_reuse_address=Trueclose_request(request)
Called to clean up an individual request.
fileno()
Return socket file number.
Interface required by selector.
get_request()
Get the request and client address from the socket.
May be overridden.
request_queue_size=5server_activate()
Called by constructor to activate the server.
May be overridden.
server_bind()
Called by constructor to bind the socket.
May be overridden.
server_close()
Called to clean-up the server.
May be overridden.
shutdown_request(request)
Called to shutdown and close an individual request.
socket_type=1classvarlink.Service(vendor='',product='',version='',url='',interface_dir='.',namespaced=False)
Bases: object
Varlink service server handler
To use the Service, a global object is instantiated:
>>> service = Service(
>>> vendor='Red Hat',
>>> product='Manage System Accounts',
>>> version='1',
>>> interface_dir=os.path.dirname(__file__)
>>> )
For the class implementing the methods of a specific varlink interface a decorator is used:
>>> @service.interface('com.redhat.system.accounts')
>>> class Accounts:
>>> pass
The varlink file corresponding to this interface is loaded from the 'interface_dir' specified in
the constructor of the Service. It has to end in '.varlink'.
Use a RequestHandler with your Service object and run a Server with it.
If you want to use your own server with the Service object, split the incoming stream for every
null byte and feed it to the Service.handle() method. Write any message returned from this
generator function to the output stream.
>>> for outgoing_message in service.handle(incoming_message):
>>> connection.write(outgoing_message)
Note: varlink only handles one method call at a time on one connection.
GetInfo()
The standardized org.varlink.service.GetInfo() varlink method.
GetInterfaceDescription(interface)
The standardized org.varlink.service.GetInterfaceDescription() varlink method.
__init__(vendor='',product='',version='',url='',interface_dir='.',namespaced=False)
Initialize the service with the data org.varlink.service.GetInfo() returns
Parametersinterface_dir -- the directory with the *.varlink files for the interfaces
handle(message,_server=None,_request=None)
This generator function handles any incoming message.
Write any returned bytes to the output stream.
>>> for outgoing_message in service.handle(incoming_message):
>>> connection.write(outgoing_message)
interface(filename)classvarlink.SimpleClientInterfaceHandler(interface,file_or_socket,namespaced=False)
Bases: ClientInterfaceHandler
A varlink client for an interface doing send/write and receive/read on a socket or file stream
__init__(interface,file_or_socket,namespaced=False)
Creates an object with the varlink methods of an interface installed.
The object allows to talk to a varlink service, which implements the specified interface
transparently by calling the methods. The call blocks until enough messages are received.
For monitor calls with '_more=True' a generator object is returned.
Parameters
• interface -- an Interface object
• file_or_socket -- an open socket or io stream
• namespaced -- if True, varlink methods return SimpleNamespace objects instead of
dictionaries
close()
To be implemented.
classvarlink.ThreadingServer(server_address,RequestHandlerClass,bind_and_activate=True)
Bases: ThreadingMixIn, Serverclassvarlink.VarlinkEncoder(*,skipkeys=False,ensure_ascii=True,check_circular=True,allow_nan=True,sort_keys=False,indent=None,separators=None,default=None)
Bases: JSONEncoder
The Encoder used to encode JSON
default(o)
Implement this method in a subclass such that it returns a serializable object for o, or
calls the base implementation (to raise a TypeError).
For example, to support arbitrary iterators, you could implement default like this:
def default(self, o):
try:
iterable = iter(o)
except TypeError:
pass
else:
return list(iterable)
# Let the base class default method raise the TypeError
return super().default(o)
exceptionvarlink.VarlinkError(message,namespaced=False)
Bases: Exception
The base class for varlink error exceptions
__init__(message,namespaced=False)as_dict()error()
returns the exception varlink error name
classmethodnew(message,namespaced=False)parameters(namespaced=False)
returns the exception varlink error parameters
varlink.get_listen_fd()
Install Now
PNG Icons