===============================
PSI - Python System Information
===============================


PSI is a Python package providing real-time access to processes and
other miscellaneous system information such as architecture, boottime
and filesystems. It has a pythonic API which is consistent accross all
supported platforms but also exposes platform-specific details where
desirable.


Install
=======

You need to check if it's supported on your platform, check the
docstring of setup.py for the exact supported platforms.

You will also need a working C compiler and the python development
files.  If a system is not supported yet the build will fail.  After
building it is best to run the test suite, on some platforms not all
tests might pass yet and you would rather know of these problems
before starting to use PSI.

So to fully install PSI from source::

  $ python setup.py build
  $ python setup.py test
  $ python setup.py install [<your options>]

See the Python documentation on installing Python module for more
control: http://docs.python.org/install/index.html


Here a rough list of packages you will need for some platforms, this
should give you an idea of what is needed.

Debian/Ubuntu:

 - python
 - python-dev
 - gcc

Redhat/CentOS:

 - python
 - python-devel
 - gcc

 AIX:
 - bos.perf.perfstat
 - bos.perf.libperfstat
 - python (manual or from Linux toolbox rpm)
 - compiler used to compile python



Limitations
===========

Solaris
-------

The argv array is read from the process memory on Solaris.  If you do
not have permissions to do this only the ``command`` and ``argc``
attributes of ``psi.process.Process`` will be available and using the
``args`` attribute will return the appropriate ``AttributeError``.


Unit Tests
==========

To run the unit tests::

  $ python setup.py test

Some tests require superuser privileges and will be silently skipped
when not running as root.  This is required to run test applications
with specific schedulers and priorities.

If any tests fail, please copy & paste the output and send operating
system version, python version, python executable format (32/64-bit)
and any other applicable details to the mailing list
(psi-discuss@googlegroups.com).


Examples
========

Examples are the best documentation.  :-)

::

  Python 2.5.2 (r252:60911, Oct  5 2008, 19:24:49)
  [GCC 4.3.2] on linux2
  Type "help", "copyright", "credits" or "license" for more information.
  >>> import psi
  >>>
  >>> a = psi.arch.arch_type()
  >>> a
  psi.arch.ArchLinux()
  >>> isinstance(a, psi.arch.ArchLinux)
  True
  >>> isinstance(a, psi.arch.ArchSunOS)
  False
  >>> a.sysname
  'Linux'
  >>> a.nodename
  'signy'
  >>> a.release
  '2.6.27-9-generic'
  >>> a.release_info
  (2L, 6L, 26L)
  >>> a.version
  '#1 SMP Thu Nov 20 21:57:00 UTC 2008'
  >>> a.machine
  'i686'
  >>>
  >>> psi.loadavg()
  (0.059999999999999998, 0.13, 0.13)
  >>>
  >>> import os
  >>> mypid = os.getpid()
  >>> mypid
  21374
  >>> p = psi.process.Process(mypid)
  >>> p.args
  ('python',)
  >>> p.exe
  '/usr/bin/python2.5'
  >>> p.uid
  1000
  >>> import pwd
  >>> pwd.getpwuid(p.uid)
  pwd.struct_passwd(pw_name='flub', pw_passwd='x', pw_uid=1000,
  pw_gid=1000, pw_gecos='Floris Bruynooghe,,,', pw_dir='/home/flub',
  pw_shell='/bin/bash')
  >>> p.start_time
  datetime.datetime(2009, 5, 11, 20, 4, 31, 709993)
  >>> help(psi.process.Process.start_time)
  Help on getset descriptor psi.process.Process.start_time:

  start_time
    Start time of process as datetime.datetime object

    Use .strftime('%s') to get seconds since epoch
  >>> p.ppid
  21304L
  >>> parent = psi.process.Process(pid=p.ppid)
  >>> parent.args
  ('bash',)
  >>> p.rss
  2293L
  >>>
  >>> pt = psi.process.ProcessTable()
  >>> len(pt)
  145
  >>> pt.keys()
  [1L, 2L, 3L, 4L, 5L, 6L, 7L, 6152L, 5660L, 6687L, 4648L, 5674L,
  5639L, 6834L, 46L, 48L, 50L, 51L, 5684L, 1081L, 2621L, 5184L, 6276L,
  2627L, 6217L, 6220L, 6221L, 4877L, 6224L, 6227L, 6229L, 6235L,
  6757L, 5729L, 6244L, 2149L, 6246L, 2152L, 2153L, 6763L, 6764L,
  6254L, 6248L, 6259L, 5749L, 2166L, 6249L, 2169L, 5242L, 2683L,
  6781L, 6273L, 6274L, 4740L, 6278L, 6279L, 5772L, 5776L, 6290L,
  5779L, 5268L, 6296L, 6809L, 156L, 157L, 158L, 6341L, 6307L, 2212L,
  6257L, 20654L, 6856L, 4786L, 4788L, 5814L, 5817L, 6263L, 5821L,
  6261L, 6336L, 4811L, 118L, 200L, 1739L, 5837L, 1742L, 1743L, 6349L,
  20693L, 6265L, 5852L, 122L, 4833L, 4834L, 1253L, 2793L, 1258L,
  6382L, 21374L, 6393L, 5885L, 1278L, 5376L, 6401L, 5675L, 1290L,
  1293L, 6445L, 5397L, 6262L, 5913L, 4385L, 4386L, 4392L, 4393L,
  4394L, 1074L, 6449L, 5426L, 6456L, 6458L, 5951L, 19779L, 5963L,
  5964L, 21327L, 21304L, 5466L, 4955L, 4444L, 2404L, 5501L, 6526L,
  4992L, 4993L, 6032L, 6572L, 6442L, 5573L, 5576L, 2794L, 17357L,
  4054L, 6397L, 6136L]
  >>> q = pt[6856]
  >>> q.args
  ('emacs22-gtk',)
  >>> q.env
  {'GNOME_DESKTOP_SESSION_ID': 'this-is-deprecated', 'LOGNAME':
  'flub', 'USER': 'flub', 'HOME': '/home/flub', 'PATH':
  '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games',
  'DISPLAY': ':0.0', 'SSH_AGENT_PID': '6217', 'LANG': 'en_GB.UTF-8',
  'SHELL': '/bin/bash', 'XDG_SESSION_COOKIE':
  '26100f517aa94dec0dc7b4aa494948ea-1231927234.615881-1120709651',
  'SESSION_MANAGER': 'local/signy:/tmp/.ICE-unix/6152',
  'XDG_DATA_DIRS': '/usr/local/share/:/usr/share/:/usr/share/gdm/',
  'WINDOWPATH': '7', 'GPG_AGENT_INFO':
  '/tmp/seahorse-SWS6qW/S.gpg-agent:6235:1', 'USERNAME': 'flub',
  'GDM_XSERVER_LOCATION': 'local', 'SSH_AUTH_SOCK':
  '/tmp/keyring-AStyaD/ssh', 'DESKTOP_SESSION': 'gnome', 'GDMSESSION':
  'gnome', 'DBUS_SESSION_BUS_ADDRESS':
  'unix:abstract=/tmp/dbus-HFM6sYANYS,guid=916b5b81c03bda327eaaa293496db7c5',
  'ORBIT_SOCKETDIR': '/tmp/orbit-flub', 'XAUTHORITY':
  '/home/flub/.Xauthority', 'GNOME_KEYRING_SOCKET':
  '/tmp/keyring-AStyaD/socket', 'GNOME_KEYRING_PID': '6246\n',
  'GDM_LANG': 'en_GB.UTF-8', 'PWD': '/home/flub', 'GTK_RC_FILES':
  '/etc/gtk/gtkrc:/home/flub/.gtkrc-1.2-gnome2'}
  >>>
  >>> r = []
  >>> for pp in pt.values():
  ...     if pp.args and 'evolution' in pp.args[0]:
  ...         r.append(pp)
  ...
  >>> r
  [psi.process.Process(pid=6336), psi.process.Process(pid=6572),
  psi.process.Process(pid=6397)]
  >>> for pp in r:
  ...     print ' '.join(pp.args)
  ...
  /usr/lib/evolution/2.24/evolution-exchange-storage --oaf-activate-iid=OAFIID:GNOME_Evolution_Exchange_Connector_CalFactory:1.2 --oaf-ior-fd=22
  evolution
  /usr/lib/evolution/evolution-data-server-2.24 --oaf-activate-iid=OAFIID:GNOME_Evolution_DataServer_CalFactory:1.2 --oaf-ior-fd=23
  >>>
  >>> init = psi.process.Process(1)
  >>> init.env
  Traceback (most recent call last):
    File "<stdin>", line 1, in <module>
  psi.InsufficientPrivsError: Insufficient privileges for Process.env
  >>>

Some sample scripts are also available in the examples/ subdirectory.


Development
===========

You should definitely read the DESIGN file, it will explain the ideas
behind how the code is structured and how you should extend it.  Also
very useful is the TODO file and the wiki
(http://bitbucket.org/chrismiles/psi/wiki/Development).

The setup.py has some extra features that help with development,
these are explained in its docstring.

The PSI source code is hosted at bitbucket in a Mercurial repository,
http://bitbucket.org/chrismiles/psi/


Porting
=======

If PSI does not yet work on your architecture/system then it needs to
be ported, the design is aimed at making this easy for you.  There is
no separate porting guide at the moment so you will have to read the
DESIGN file for details of what to do.


Help
====

There is a mailing list at psi-discuss@googlegroups.com where you can
post questions, patches, hints, bugs, etc.  Your feedback is welcome!