======================= Setup and running tests ======================= If you plan on hacking on psutil this is what you're supposed to do first: - clone the GIT repository: .. code-block:: bash $ git clone git@github.com:giampaolo/psutil.git - install test deps and GIT hooks: .. code-block:: bash make setup-dev-env - run tests: .. code-block:: bash 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 ``make install-git-hooks``. - C code strictly follows `PEP 7 `_ styling guides. ======== Makefile ======== Some useful make commands: .. code-block:: bash make install # install make setup-dev-env # install useful dev libs (pyflakes, unittest2, etc.) make test # run unit tests make test-memleaks # run memory leak tests make test-coverage # run test coverage make flake8 # run PEP8 linter 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 set PYTHON=C:\python35\python.exe && make test ...or: .. code-block:: bat make -p 35 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 set TSCRIPT=foo.py && make test ==================== 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. ``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. =================== Make a pull request =================== - fork psutil - create your feature branch (``git checkout -b my-new-feature``) - commit your changes (``git commit -am 'add some feature'``) - push to the branch (``git push origin my-new-feature``) - create a new 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 `_ (Linux, OSX) - `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%20/%20OSX :target: https://travis-ci.org/giampaolo/psutil :alt: Linux 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) OSX, BSD, AIX and Solaris are currently tested manually (sigh!). Test coverage ------------- Test coverage is provided by `coveralls.io `_, it is controlled via `.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 `_. - 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. ============= 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).