This package contains the following modules:
- * srv -- Server module
- * cli -- Client module
- * perf -- Library for implementing object for the PERF protocol
+ - srv -- Server module
+ - cli -- Client module
+ - perf -- Library for implementing object for the PERF protocol
The protocol allows multiple management subprotocols for different
modes of operation. Currently, the following two management protocols
are supported.
- * The REPL protocol implements a simple read-eval-print loop which
+ - The REPL protocol implements a simple read-eval-print loop which
accepts arbitrary Python code, executes it in the daemon process,
and returns its replies, all in text form. The protocol is simple,
generic, and has few failure modes, but is hardly suitable for
programmatic interaction. See the documentation for pdm.srv.repl
and pdm.cli.replclient for further details.
- * The PERF protocol is intended for programmatic interaction with the
+ - The PERF protocol is intended for programmatic interaction with the
daemon process. Various Python modules may expose objects that
implement one or several of a few pre-defined interfaces that allow
for various forms of inspection and management of the program
"""Create a client object connected to the specified
server. `sk' can either be a socket object, which is used as
it is, or a string specification very similar to the
- specification for pdm.srv.listen, so see its documentation for
- details. The differences are only that this function does not
- take arguments specific to socket creation, like the mode and
- group arguments for Unix sockets. If `proto' is given, that
- subprotocol will negotiated with the server (by calling the
- select() method).
+ specification for L{pdm.srv.listen}, so see its documentation
+ for details. The differences are only that this function does
+ not take arguments specific to socket creation, like the mode
+ and group arguments for Unix sockets. If `proto' is given,
+ that subprotocol will negotiated with the server (by calling
+ the select() method).
"""
self.sk = resolve(sk)
self.buf = b""
class replclient(client):
"""REPL protocol client
- Implements the client side of the REPL protocol; see pdm.srv.repl
- for details on the protocol and its functionality.
+ Implements the client side of the REPL protocol; see
+ L{pdm.srv.repl} for details on the protocol and its functionality.
"""
def __init__(self, sk):
"""Create a connected client as documented in the `client' class."""
def run(self, code):
"""Run a single block of Python code on the server. Returns
- the output of the command (as documented in pdm.srv.repl) as a
- string.
+ the output of the command (as documented in L{pdm.srv.repl})
+ as a string.
"""
while True:
ncode = code.replace("\n\n", "\n")
class perfclient(client):
"""PERF protocol client
- Implements the client side of the PERF protocol; see pdm.srv.perf
- for details on the protocol and its functionality.
+ Implements the client side of the PERF protocol; see
+ L{pdm.srv.perf} for details on the protocol and its functionality.
This client class implements functions for finding PERF objects on
the server, and returns, for each server-side object looked up, a
they implement a close() method for that purpose, and can also be
used in `with' statements.
- See pdm.srv.perf for details on the various PERF interfaces that
- the proxy objects might implement.
+ See L{pdm.srv.perf} for details on the various PERF interfaces
+ that the proxy objects might implement.
"""
def __init__(self, sk):
"""Create a connected client as documented in the `client' class."""
classes to implement some standard PERF objects that can be used by
PERF clients connecting to any PERF server.
-See the documentation for pdm.srv.perf for a description of the
+See the documentation for L{pdm.srv.perf} for a description of the
various PERF interfaces.
It contains two named PERF objects:
- * sysres -- A directory containing the following objects pertaining
- to the resource usage of the server process:
- * realtime -- An attribute returning the amount of real time
- since the PDM module was imported (which likely
- coincides with the amount of time the server process
- has been running).
- * cputime -- An attribute returning the amount of CPU time
- consumed by the server process (in both user and
- kernel mode).
- * utime -- An attribute returning the amount of CPU time the
- server process has spent in user mode.
- * stime -- An attribute returning the amount of CPU time the
- server process has spent in kernel mode.
- * maxrss -- An attribute returning the largest resident set size
- the server process has used during its lifetime.
- * rusage -- An attribute returning the current rusage of the
- server process.
-* sysinfo -- A directory containing the following objects pertaining
- to the environment of the server process:
- * pid -- An attribute returning the PID of the server process.
- * uname -- An attribute returning the uname information of the
- system.
- * hostname -- An attribute returning the hostname of the system.
- * platform -- An attribute returning the Python build platform.
+ - sysres -- A directory containing the following objects pertaining
+ to the resource usage of the server process:
+
+ - realtime -- An attribute returning the amount of real time since
+ the PDM module was imported (which likely coincides with the
+ amount of time the server process has been running).
+
+ - cputime -- An attribute returning the amount of CPU time
+ consumed by the server process (in both user and kernel mode).
+
+ - utime -- An attribute returning the amount of CPU time the
+ server process has spent in user mode.
+
+ - stime -- An attribute returning the amount of CPU time the
+ server process has spent in kernel mode.
+
+ - maxrss -- An attribute returning the largest resident set size
+ the server process has used during its lifetime.
+
+ - rusage -- An attribute returning the current rusage of the
+ server process.
+
+ - sysinfo -- A directory containing the following objects pertaining
+ to the environment of the server process:
+
+ - pid -- An attribute returning the PID of the server process.
+
+ - uname -- An attribute returning the uname information of the
+ system.
+
+ - hostname -- An attribute returning the hostname of the system.
+
+ - platform -- An attribute returning the Python build platform.
"""
import os, sys, resource, time, socket, threading
class attrinfo(object):
"""The return value of the `attrinfo' method on `attr' objects as
- described in pdm.srv.perf.
+ described in L{pdm.srv.perf}.
Currently contains a single data field, `desc', which should have
a human-readable description of the purpose of the attribute.
"""REPL protocol handler
Provides a read-eval-print loop. The primary client-side interface
- is the pdm.cli.replclient class. Clients can send arbitrary code,
- which is compiled and run on its own thread in the server process,
- and output responses that are echoed back to the client.
+ is the L{pdm.cli.replclient} class. Clients can send arbitrary
+ code, which is compiled and run on its own thread in the server
+ process, and output responses that are echoed back to the client.
Each client is provided with its own module, in which the code
runs. The module is prepared with a function named `echo', which
already be imported. PDM will not import new modules for clients;
rather, the daemon process needs to import all modules that
clients should be able to interact with. PDM itself always imports
- the pdm.perf module, which contains a few basic PERF objects. See
- its documentation for details.
+ the L{pdm.perf} module, which contains a few basic PERF
+ objects. See its documentation for details.
The following interfaces are currently known to PERF.
- * attr:
+ - attr:
An object that implements the `attr' interface models an
attribute that can be read by clients. The attribute can be
anything, as long as its representation can be
description of the attribute. Both should be
idempotent. `readattr' can return any pickleable object, and
`attrinfo' should return either None to indicate that it has no
- description, or an instance of the pdm.perf.attrinfo class.
+ description, or an instance of the L{pdm.perf.attrinfo} class.
- * dir:
+ - dir:
The `dir' interface models a directory of other PERF
objects. An object implementing it must implement methods
called `lookup' and `listdir'. `lookup' is called with a single
used as argument to `lookup', but the list is not required to
be exhaustive and may also be empty.
- * invoke:
+ - invoke:
The `invoke' interface allows a more arbitrary form of method
calls to objects implementing it. Such objects must implement a
method called `invoke', which is called with one positional
the client. In case the method name is not recognized, `invoke'
should raise an AttributeError.
- * event:
+ - event:
The `event' interface allows PERF objects to notify clients of
events asynchronously. Objects implementing it must implement
methods called `subscribe' and `unsubscribe'. `subscribe' will
`event' object should then call all such registered callables
with a single argument describing the event. The argument could
be any object that can be pickled, but should be an instance of
- a subclass of the pdm.perf.event class. If `subscribe' is
+ a subclass of the L{pdm.perf.event} class. If `subscribe' is
called with a callback object that it has already registered,
it should raise a ValueError. `unsubscribe' is called with a
single argument, which is a previously registered callback
object is not, in fact, registered, a ValueError should be
raised.
- The pdm.perf module contains a few convenience classes which
+ The L{pdm.perf} module contains a few convenience classes which
implements the interfaces, but PERF objects are not required to be
instances of them. Any object can implement a PERF interface, as
long as it does so as described above.
- The pdm.cli.perfclient class is the client-side implementation.
+ The L{pdm.cli.perfclient} class is the client-side implementation.
"""
def __init__(self, cl):
self.cl = cl