1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
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 <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`__.
Once you have a compiler installed run:
.. code-block:: bash
git clone git@github.com: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:
.. code-block:: bash
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:
.. code-block:: bash
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:
.. code-block:: bash
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:
.. code-block:: bash
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:
.. code-block:: bash
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
-----------------
.. code-block:: bash
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:
- Define the new API 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 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. `psutil/tests/test_linux.py`_).
This usually means testing the return value of the new API against
a system CLI tool.
- Update the doc in ``docs/index.py``.
- Update `HISTORY.rst`_ and `CREDITS`_ files.
- Make a pull request.
Make a pull request
-------------------
- Fork psutil (go to https://github.com/giampaolo/psutil and click on "fork")
- Git clone the fork locally: ``git clone git@github.com: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.
.. _`CREDITS`: https://github.com/giampaolo/psutil/blob/master/CREDITS
.. _`CONTRIBUTING.md`: https://github.com/giampaolo/psutil/blob/master/CONTRIBUTING.md
.. _`HISTORY.rst`: https://github.com/giampaolo/psutil/blob/master/HISTORY.rst
.. _`make.bat`: https://github.com/giampaolo/psutil/blob/master/make.bat
.. _`winmake.py`: https://github.com/giampaolo/psutil/blob/master/scripts/internal/winmake.py
.. _`Makefile`: https://github.com/giampaolo/psutil/blob/master/Makefile
.. _`PEP-7`: https://www.python.org/dev/peps/pep-0007/
.. _`PEP-8`: https://www.python.org/dev/peps/pep-0008/
.. _`psutil/__init__.py`: https://github.com/giampaolo/psutil/blob/master/psutil/__init__.py
.. _`psutil/_pslinux.py`: https://github.com/giampaolo/psutil/blob/master/psutil/_pslinux.py
.. _`psutil/_psutil_linux.c`: https://github.com/giampaolo/psutil/blob/master/psutil/_psutil_linux.c
.. _`psutil/tests/test_linux.py`: https://github.com/giampaolo/psutil/blob/master/psutil/tests/test_linux.py
.. _`psutil/tests/test_process.py`: https://github.com/giampaolo/psutil/blob/master/psutil/tests/test_process.py
.. _`psutil/tests/test_system.py`: https://github.com/giampaolo/psutil/blob/master/psutil/tests/test_system.py
|
