Skip to content

Latest commit

 

History

History
152 lines (117 loc) · 6.03 KB

DEVGUIDE.rst

File metadata and controls

152 lines (117 loc) · 6.03 KB

psutil development guide

Build, setup and running tests

psutil makes extensive use of C extension modules, meaning a C compiler is required, see install instructions. Once you have a compiler installed run:

git clone [email protected]:giampaolo/psutil.git
make install-sysdeps      # install gcc and python headers
make install-pydeps-test  # install python deps necessary to run unit tests
make build
make install
make test
  • If you don't have the source code, and just want to test psutil installation. This will work also if pytest module is not installed (e.g. production environments) by using unittest's test runner:
python3 -m psutil.tests
  • make (and the accompanying Makefile) is the designated tool to build, install, run tests and do pretty much anything that involves development. This also includes Windows, meaning that you can run make command similarly as if you were on UNIX (see make.bat and winmake.py). Some useful commands are:
make clean                # remove build files
make install-pydeps-dev   # install dev deps (ruff, black, ...)
make test                 # run tests
make test-parallel        # run tests in parallel (faster)
make test-memleaks        # run memory leak tests
make test-coverage        # run test coverage
make lint-all             # run linters
make fix-all              # fix linters errors
make uninstall
make help
  • To run a specific unit test:
make test ARGS=psutil/tests/test_system.py::TestDiskAPIs::test_disk_usage
  • If you're working on a new feature and you wish to compile & test it "on the fly" from a test script, this is a quick & dirty way to do it:
make test ARGS=test_script.py     # on UNIX
make test test_script.py          # on Windows
  • Do not use sudo. make install installs psutil as a limited user in "edit" / development mode, meaning you can edit psutil code on the fly while you develop.
  • If you want to target a specific Python version:
make test PYTHON=python3.5           # UNIX
make test -p C:\python35\python.exe  # Windows

Coding style

  • Python code strictly follows PEP-8 styling guide. In addition we use black and ruff code formatters / linters. This is enforced by a GIT commit hook, installed via make install-git-hooks, which will reject the commit if code is not compliant.
  • C code should follow PEP-7 styling guides, but things are more relaxed.
  • Linters are enforced also for .rst and .toml files.

Code organization

psutil/__init__.py                   # main psutil namespace ("import psutil")
psutil/_ps{platform}.py              # platform-specific python wrapper
psutil/_psutil_{platform}.c          # platform-specific C extension
psutil/tests/test_process|system.py  # main test suite
psutil/tests/test_{platform}.py      # platform-specific test suite

Adding a new API

Typically, this is what you do:

Make a pull request

  • Fork psutil (go to https://github.com/giampaolo/psutil and click on "fork")
  • Git clone the fork locally: git clone [email protected]:YOUR-USERNAME/psutil.git
  • Create a branch: git checkout -b new-feature
  • Commit your changes: git commit -am 'add some feature'
  • Push the branch: git push origin new-feature
  • Create a new PR via the GitHub web interface and sign-off your work (see CONTRIBUTING.md guidelines)

Continuous integration

Unit tests are automatically run on every git push on Linux, macOS, Windows, FreeBSD, NetBSD, OpenBSD. AIX and Solaris does not have continuous test integration.

Documentation

  • doc source code is written in a single file: docs/index.rst.
  • doc can be built with make install-pydeps-dev; cd docs; make html.
  • public doc is hosted at https://psutil.readthedocs.io.