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
|
=======================
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 system deps (see `install instructions <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`__).
- install development deps; these are useful for running tests (e.g. mock,
unittest2), building doc (e.g. sphinx), running linters (flake8), etc. ::
$ make setup-dev-env
- bear in mind that ``make`` (see `Makefile <https://github.com/giampaolo/psutil/blob/master/Makefile>`_)
is the designated tool to run tests, build, install etc. and that it is also
available on Windows
(see `make.bat <https://github.com/giampaolo/psutil/blob/master/make.bat>`_).
- bear in mind that both psutil (``make install``) and any other lib
(``make setup-dev-env``) is installed as a limited user
(``pip install --user ...``), so develop as such (don't use root).
- (UNIX only) run ``make install-git-hooks``: this will reject your commits
if python code is not PEP8 compliant.
- run ``make test`` to run tests.
============
Coding style
============
- python code strictly follows `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_
styling guides and this is enforced by ``make install-git-hooks``.
- C code strictly follows `PEP 7 <https://www.python.org/dev/peps/pep-0007/>`_
styling guides.
========
Makefile
========
Some useful make commands::
$ make install # install
$ make setup-dev-env # install useful dev libs (pyflakes, unittest2, etc.)
$ make test # run all tests
$ make test-memleaks # run memory leak tests
$ make coverage # run test coverage
$ make flake8 # run PEP8 linter
====================
Adding a new feature
====================
Usually the files involved when adding a new functionality are:
.. code-block:: plain
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.
======================
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**, **OSX** and
**Windows** by using:
- `Travis <https://travis-ci.org/giampaolo/psutil>`_ (Linux, OSX)
- `Appveyor <https://ci.appveyor.com/project/giampaolo/psutil>`_ (Windows)
Test files controlling these are
`.travis.yml <https://github.com/giampaolo/psutil/blob/master/.travis.yml>`_
and
`appveyor.yml <https://github.com/giampaolo/psutil/blob/master/appveyor.yml>`_.
Both services run psutil test suite against all supported python version
(2.6 - 3.5).
Two icons in the home page (README) always show the build status:
.. image:: https://api.travis-ci.org/giampaolo/psutil.png?branch=master
:target: https://travis-ci.org/giampaolo/psutil
:alt: Linux tests (Travis)
.. image:: https://ci.appveyor.com/api/projects/status/qdwvw7v1t915ywr5/branch/master?svg=true
:target: https://ci.appveyor.com/project/giampaolo/psutil
:alt: Windows tests (Appveyor)
OSX, FreeBSD and Solaris are currently tested manually (sigh!).
Test coverage
-------------
Test coverage is provided by `coveralls.io <https://coveralls.io/github/giampaolo/psutil>`_,
it is controlled via `.travis.yml <https://github.com/giampaolo/psutil/blob/master/.travis.yml>`_
and it is updated on every git push.
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 <https://raw.githubusercontent.com/giampaolo/psutil/master/docs/index.rst>`_.
- it uses `RsT syntax <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
and it's built with `sphinx <http://sphinx-doc.org/>`_.
- 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 notes for myself (Giampaolo):
- ``make release``
- post announce (``make print-announce``) on psutil and python-announce mailing
lists, twitter, g+, blog.
=============
FreeBSD notes
=============
- setup:
.. code-block:: bash
$ 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).
|
