Skip to content

Latest commit

 

History

History
209 lines (147 loc) · 6.24 KB

DEVGUIDE.rst

File metadata and controls

209 lines (147 loc) · 6.24 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 git@github.com:giampaolo/psutil.git
  • install test deps and GIT hooks:
make setup-dev-env
  • run tests:
make test
  • 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).
  • do not use sudo; make install installs psutil as a limited user in "edit" mode; also make setup-dev-env installs deps as a limited user.
  • use make help to see the list of available commands.

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 unit tests
make test-memleaks  # run memory leak tests
make test-coverage  # run test coverage
make flake8         # run PEP8 linter

There are some differences between make on UNIX and Windows. For instance, to run a specific Python version. On UNIX:

make test PYTHON=python3.5

On Windows:

set PYTHON=C:\python35\python.exe && make test

...or:

make -p 35 test

If you want to modify psutil and run a script on the fly which uses it do (on UNIX):

make test TSCRIPT=foo.py

On Windows:

set TSCRIPT=foo.py && make test

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.

Make a pull request

  • fork psutil
  • create your feature branch (git checkout -b my-new-feature)
  • commit your changes (git commit -am 'add some feature')
  • push to the branch (git push origin my-new-feature)
  • create a new 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, macOS 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.6). Two icons in the home page (README) always show the build status:

Linux and macOS tests (Travis)

Windows tests (Appveyor)

BSD, AIX and Solaris are currently tested manually.

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