Clone wiki

psi / Documentation


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. Process.children() will only return the current children. Since it is possible that what the objects represent have changed since you created it most objects have a .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, c.f. Process.command, but sometimes this is simply not possible. Other times an API will be specific to just a few platforms, e.g. 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 hasattr().


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).

Detailed Topics

  • Time API: PSI's own way of representing time, don't panic all normal ways are supported.