Skip to content

Latest commit

 

History

History
147 lines (114 loc) · 5.44 KB

DEVGUIDE.rst

File metadata and controls

147 lines (114 loc) · 5.44 KB
Raw

Setup

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

  • git clone the repo: git clone [email protected]:giampaolo/psutil.git.
  • take a look at install instructions and satisfy system dependencies first.
  • bear in mind that make (see Makefile) is the designated tool to run tests, build etc. and that it is also available on Windows (see make.bat).
  • (UNIX only) run make install-git-hooks: this will reject your commit if it's not PEP8 compliant.
  • run make setup-dev-env: this will install test deps (e.g. mock lib) and other useful tools (e.g. ipdb, flake8).
  • 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
  • make test
  • make test-memleaks
  • make coverage
  • make flake8

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
test/test_psutil.py           # main test suite
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 code write the C implementation in psutil/_psutil_{platform}.c (e.g. psutil/_psutil_linux.c).
  • write a cross platform test in test/test_psutil.py.
  • write a platform specific test in test/_{platform}.py; platform specific tests usually test psutil against system CLI tools.
  • update doc.
  • make a pull request.

Continuous integration

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

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.4). 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 and it is controlled via .travis.yml. An icon in the home page (README) always shows the last coverage percentage:

Test coverage (coverall.io)

Code quality

Code quality is controlled by scrutinizer-ci which provides a report signaling duplicated code and other amenities. It is controlled by .scrutinizer.yml. An icon in the home page always shows a code quality score:

Code quality (scrutinizer-ci.com)

Documentation

  • doc source code is in /docs directory.
  • it uses RsT syntax and it's built with sphinx.
  • doc can be built with make setup-dev-env; cd docs; make html.
  • public doc is hosted on http://pythonhosted.org/psutil/.
  • it is uploaded on every new release with make upload-doc.

Releasing a new version

These are note for myself (Giampaolo):

  • make sure all tests pass and all builds are green.
  • upload source tarball on PYPI with make upload-src.
  • upload exe and wheel files for windows on PYPI with make upload-all.
  • upload updated doc on http://pythonhosted.org/psutil with make upload-doc.
  • GIT tag the new release with make git-tag-release.
  • post on psutil and python-announce mailing lists, twitter, g+, blog.