PSI is split up in several modules, currently they are:
- arch: System and architecture details.
- process: Processes and process table.
- mount: Filesystems.
And some functions exist in the psi namespace directly (uptime, loadavg, ...).
The entire API should be documented extensively with docstrings, so that pydoc should be the primary documentation. If something is missing from the docstrings it is a bug! However some general concepts and topics are explained a bit more on this page.
All objects are snapshots at instantiation time, that means that if
you create a
psi.process.Process object and look at the
.cputime attribute you will see the used CPU time when you
created the object, if you later look at that attribute again it will
not have changed. In contrast to this methods on objects are
executed at the time you invoke them, e.g.
will only return the current children. Since it is possible that what
the objects represent have changed since you created it most objects
.refresh() method which will update all the attributes.
Note that some methods might alter the state of an object too, like
Process.kill(), in those cases you will have to call
.refresh() to see the updated state.
Even tough PSI provides a uniform API accross different platforms
sometimes certain platforms simply don't have the information
available. When reasonable PSI will construct this,
Process.command, but sometimes this is simply not possible.
Other times an API will be specific to just a few platforms,
psi.getzoneid(). In those cases the classes, functions,
methods or attributes are simply not present on platforms where they
are not applicable, so you can always check with
Class hierarch of exceptions:
Exception (Python) +-- StandardError (Python) | +-- AttributeError (Python) | | +-- AttrNotAvailableError (PSI) | | +-- AttrInsufficientPrivsError (PSI) | | +-- AttrNotImplementedError (PSI) | ... +-- InsufficientPrivsError (PSI) +-- MissingResourceError (PSI) | +-- NoSuchProcessError (PSI) | ... ...
The general rule is that when accessing an attribute (most of which
are implemented using the descriptor protocol internally) you will
always get a subclass of
AttributeError if you get an exception.
When you get a
[Attr]NotImplementedError it means development
of the feature for the platform is lagging.
Any part of the API which is experimental or which might still change will issue a FurureWarning. This helps reduce the number of required major version number changes (and hence module-import-name changes).
- Time API: PSI's own way of representing time, don't panic all normal ways are supported.
- Process names, arguments and executables: many attributes are involved with these with lots of platform-dependent quirks. This explains how it all works and how to easily work with them.