Skip to content

Latest commit

 

History

History
161 lines (121 loc) · 5.72 KB

DEVGUIDE.rst

File metadata and controls

161 lines (121 loc) · 5.72 KB
Raw

Setup and running tests

If you plan on hacking on psutil this is what you're supposed to do first:

  • clone the GIT repository:

    $ git clone [email protected]:giampaolo/psutil.git

  • install system deps (see install instructions).

  • install development deps; these are useful for running tests (e.g. mock, unittest2), building doc (e.g. sphinx), running linters (flake8), etc.

    $ make setup-dev-env

  • bear in mind that make (see Makefile) is the designated tool to run tests, build, install etc. and that it is also available on Windows (see make.bat).

  • bear in mind that both psutil (make install) and any other lib (make setup-dev-env) is installed as a limited user (pip install --user ...), so develop as such (don't use root).

  • (UNIX only) run make install-git-hooks: this will reject your commits if python code is not PEP8 compliant.

  • run make test to run tests.

Coding style

  • python code strictly follows PEP 8 styling guides and this is enforced by make install-git-hooks.
  • C code strictly follows PEP 7 styling guides.

Makefile

Some useful make commands:

$ make install        # install
$ make setup-dev-env  # install useful dev libs (pyflakes, unittest2, etc.)
$ make test           # run all tests
$ make test-memleaks  # run memory leak tests
$ make coverage       # run test coverage
$ make flake8         # run PEP8 linter

Adding a new feature

Usually the files involved when adding a new functionality are:

psutil/__init__.py                   # main psutil namespace
psutil/_ps{platform}.py              # python platform wrapper
psutil/_psutil_{platform}.c          # C platform extension
psutil/_psutil_{platform}.h          # C header file
psutil/tests/test_process|system.py  # main test suite
psutil/tests/test_{platform}.py      # platform specific test suite

Typical process occurring when adding a new functionality (API):

  • define the new function in psutil/__init__.py.
  • write the platform specific implementation in psutil/_ps{platform}.py (e.g. psutil/_pslinux.py).
  • if the change requires C, write the C implementation in psutil/_psutil_{platform}.c (e.g. psutil/_psutil_linux.c).
  • write a generic test in psutil/tests/test_system.py or psutil/tests/test_process.py.
  • if possible, write a platform specific test in psutil/tests/test_{platform}.py (e.g. test_linux.py). This usually means testing the return value of the new feature against a system CLI tool.
  • update doc in doc/index.py.
  • update HISTORY.rst.
  • update README.rst (if necessary).
  • make a pull request.

Continuous integration

All of the services listed below are automatically run on git push.

Unit tests

Tests are automatically run for every GIT push on Linux, OSX and Windows by using:

Test files controlling these are .travis.yml and appveyor.yml. Both services run psutil test suite against all supported python version (2.6 - 3.5). Two icons in the home page (README) always show the build status:

Linux tests (Travis) Windows tests (Appveyor)

OSX, FreeBSD and Solaris are currently tested manually (sigh!).

Test coverage

Test coverage is provided by coveralls.io, it is controlled via .travis.yml and it is updated on every git push. An icon in the home page (README) always shows the last coverage percentage:

Test coverage (coverall.io)

Documentation

Releasing a new version

These are notes for myself (Giampaolo):

  • make release
  • post announce (make print-announce) on psutil and python-announce mailing lists, twitter, g+, blog.

FreeBSD notes

  • setup:
$ pkg install python python3 gcc git vim screen bash
$ chsh -s /usr/local/bin/bash user  # set bash as default shell
  • /usr/src contains the source codes for all installed CLI tools (grep in it).