Library Reference¶
Pikos is designed in layers. At the top layer we find the Monitor a decorator that acts as the entry point for the monitors provided by pikos. The next layer is the various monitors that are responsible to collect information (e.g. memory) during the execution of the decorated function. The retrieved information is recorded through the recorders and controlled with the filters.
Monitor Decorator¶
- class pikos.monitors.monitor.Monitor[source]¶
Bases: object
Base class of Pikos provides monitors.
The class provides the .attach decorating method to attach a pikos monitor to a function or method. Subclasses might need to provide their own implementation if required.
- __init__()¶
x.__init__(...) initializes x; see help(type(x)) for signature
- __call__(...) <==> x(...)¶
- attach(function)[source]¶
Attach (i.e. wrap) the monitor to the function.
Parameters: function (callable) – The callable to wrap Returns: fn (callable) – The wrapped function. fn has the same signature as function. Executing fn will run function inside the _monitor_object context. Raises: ValueError – Raised if the provided _monitor_object does not support the context manager interface.
- _abc_cache = <_weakrefset.WeakSet object at 0x1cd1050>¶
- _abc_negative_cache = <_weakrefset.WeakSet object at 0x1cd10d0>¶
- _abc_negative_cache_version = 20¶
- _abc_registry = <_weakrefset.WeakSet object at 0x1cc2f50>¶
Monitors¶
A monitor is a context manager object. The class is initialized with a recorder class. Each instance of a monitor class can be reused, the __enter__ method makes sure that the code that is executed inside the context will be monitored and that the associated recorder has been initialized. During the execution of the decorated function The information is collected into a name tuple and the tuple is forwarded to recorder that has been associated with the current monitor.
Pikos currently provides the following monitors:
| FunctionMonitor(recorder) | Record python function events. |
| LineMonitor(recorder) | Record python line events. |
| pikos.monitors.function_memory_monitor.FunctionMemoryMonitor | |
| pikos.monitors.line_memory_monitor.LineMemoryMonitor | |
| FocusedFunctionMonitor(*arguments, **keywords) | Record python function events. |
| FocusedLineMonitor(*arguments, **keywords) | Record python line events. |
| pikos.monitors.focused_function_memory_monitor.FocusedFunctionMemoryMonitor | |
| pikos.monitors.focused_line_memory_monitor.FocusedLineMemoryMonitor |
External Monitors¶
Pikos can act as entry point for external libraries and profilers.
| PythonCProfiler(*args, **kwrds) | The normal python Profile subclassed and adapted to work with the pikos Monitor decorator. |
| pikos.external.line_profiler.LineProfiler | |
| pikos.external.yappi_profiler.YappiProfiler |
Note
These profilers are experimental and not yet integrated fully with the pikos framework. Please check individual documentation for more information.
Recorders¶
The recorder (a subclass of AbstractRecorder) is responsible for recording the tuples from the monitor. What is recordered is controlled by a filter function
Pikos currently provides the following recorders:
| TextStreamRecorder(text_stream[, filter_, ...]) | The TextStreamRecorder is simple recorder that formats and writes the records directly to a stream. |
| TextFileRecorder(filename[, filter_, ...]) | The TextStreamRecorder that creates the file for the records. |
| CSVRecorder(stream[, filter_]) | The CSV Recorder is a simple text based recorder that records the tuple of values using a scv writer. |
| CSVFileRecorder(filename[, filter_]) | A CSVRecorder that creates the stream (i.e. |
| ListRecorder([filter_]) | The ListRecorder is simple recorder that records the tuple of values in memory as a list. |
| pikos.recorders.zeromq_recorder.ZeroMQRecorder |
Note
The standard Recorders are record type agnostic so it is possible to use the same recorder for multiple monitors. However, this feature is experimental and users are advised to use with care.
Filters¶
A filter controls if a record tuple will be recorded or not. The callable accepts the record and makes a decision based on that (i.e. return True or False. Functions (normal and lamda) and callable classes can be used in this case to remove clutter and speed up monitoring only of the desired code.
Pikos currently provides the following predefined filters:
| OnValue(field, *args) | A record filter that remove the record when a value is not contained. |
| OnChange(field) | A record filter that checks if the record field has changed. |
Records¶
Each monitor uses a specific record. A record is a subclass of named tuple augmented with two methods, header, line that can be optionally used to format the output.
Note
Currently only the TextStreamRecorder can take advantage of the additional format information.
The monitor records available are:
| FunctionRecord | |
| LineRecord | |
| pikos.monitors.function_memory_monitor.FunctionMemoryRecord | |
| pikos.monitors.line_memory_monitor.LineMemoryRecord |