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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
Build, setup and running tests
===============================
Make sure to `install <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`__
a C compiler first, then:
.. code-block:: bash
git clone git@github.com:giampaolo/psutil.git
make setup-dev-env
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
a commit GIT hook installed via ``make install-git-hooks``.
- C code follows `PEP-7`_ styling guides.
Makefile
========
Some useful make commands:
.. code-block:: bash
make install # install
make setup-dev-env # install useful dev libs (flake8, unittest2, etc.)
make test # run unit tests
make test-memleaks # run memory leak tests
make test-coverage # run test coverage
make lint # run Python (PEP8) and C linters
There are some differences between ``make`` on UNIX and Windows.
For instance, to run a specific Python version. On UNIX:
.. code-block:: bash
make test PYTHON=python3.5
On Windows:
.. code-block:: bat
make -p C:\python35\python.exe test
If you want to modify psutil and run a script on the fly which uses it do
(on UNIX):
.. code-block:: bash
make test TSCRIPT=foo.py
On Windows:
.. code-block:: bat
make test foo.py
Adding a new feature
====================
Usually the files involved when adding a new functionality are:
.. code-block:: bash
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. `psutil/tests/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``.
- make a pull request.
Make a pull request
===================
- fork psutil (go to https://github.com/giampaolo/psutil and click on "fork")
- git clone your fork locally: ``git clone git@github.com:YOUR-USERNAME/psutil.git``)
- create your feature branch:``git checkout -b new-feature``
- commit your changes: ``git commit -am 'add some feature'``
- push to the branch: ``git push origin new-feature``
- create a new pull request by via github web interface
- remember to update `HISTORY.rst`_ and `CREDITS`_ files.
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:
- `Travis`_ (Linux, macOS)
- `Appveyor`_ (Windows)
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:
.. image:: https://img.shields.io/travis/giampaolo/psutil/master.svg?maxAge=3600&label=Linux,%20OSX,%20PyPy
:target: https://travis-ci.org/giampaolo/psutil
:alt: Linux, macOS and PyPy3 tests (Travis)
.. image:: https://img.shields.io/appveyor/ci/giampaolo/psutil/master.svg?maxAge=3600&label=Windows
:target: https://ci.appveyor.com/project/giampaolo/psutil
:alt: Windows tests (Appveyor)
.. image:: https://img.shields.io/cirrus/github/giampaolo/psutil?label=FreeBSD
:target: https://cirrus-ci.com/github/giampaolo/psutil-cirrus-ci
:alt: FreeBSD tests (Cirrus-CI)
BSD, AIX and Solaris are currently tested manually.
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:
.. image:: https://coveralls.io/repos/giampaolo/psutil/badge.svg?branch=master&service=github
:target: https://coveralls.io/github/giampaolo/psutil?branch=master
:alt: Test coverage (coverall.io)
Documentation
=============
- doc source code is written in a single file: `/docs/index.rst`_.
- 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://psutil.readthedocs.io/
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.
.. _`.travis.yml`: https://github.com/giampaolo/psutil/blob/master/.travis.ym
.. _`appveyor.yml`: https://github.com/giampaolo/psutil/blob/master/appveyor.ym
.. _`Appveyor`: https://ci.appveyor.com/project/giampaolo/psuti
.. _`coveralls.io`: https://coveralls.io/github/giampaolo/psuti
.. _`doc/index.rst`: https://github.com/giampaolo/psutil/blob/master/doc/index.rst
.. _`HISTORY.rst`: https://github.com/giampaolo/psutil/blob/master/HISTORY.rst
.. _`make.bat`: https://github.com/giampaolo/psutil/blob/master/make.bat
.. _`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
.. _`RsT syntax`: http://docutils.sourceforge.net/docs/user/rst/quickref.htm
.. _`sphinx`: http://sphinx-doc.org
.. _`Travis`: https://travis-ci.org/giampaolo/psuti
.. _`HISTORY.rst`: https://github.com/giampaolo/psutil/blob/master/HISTORY.rst
.. _`CREDITS`: https://github.com/giampaolo/psutil/blob/master/CREDITS
|
