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
|
How to contribute
-----------------
Coding guidelines
^^^^^^^^^^^^^^^^^
In general, we try to follow the standard Python coding guidelines, which cover
all the important coding aspects (docstrings, comments, naming conventions,
import statements, ...) as described here:
* `Style Guide for Python Code <http://www.python.org/peps/pep-0008.html>`_
The easiest way to check that your code is following those guidelines is to
run `pylint` (a note greater than 9/10 seems to be a reasonable goal).
Moreover, the following guidelines should be followed:
* Write docstrings for all classes, methods and functions. The docstrings
should follow the `Google style <http://google-styleguide.googlecode.com/svn/trunk/pyguide.html?showone=Comments#Comments>`_.
* Add typing annotations for all functions and methods. The annotations should
use the future syntax (``from __future__ import annotations``) and the
``if TYPE_CHECKING`` pattern to avoid circular imports (see
`PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_).
.. note::
To ensure that types are properly referenced by ``sphinx`` in the
documentation, you may need to import the individual types for Qt
(e.g. ``from qtpy.QtCore import QRectF``) instead of importing the whole
module (e.g. ``from qtpy import QtCore as QC``): this is a limitation of
``sphinx-qt-documentation`` extension. As for objects provided by the
``PythonQwt`` package, you may need to import the module itself (e.g.
``import qwt.scale_map``, then ``qwt.scale_map.QwtScaleMap``) instead of
importing the individual types (e.g. ``from qwt.scale_map import QwtScaleMap``):
this is a limitation of ``intersphinx`` extension.
* Try to keep the code as simple as possible. If you have to write a complex
piece of code, try to split it into several functions or classes.
* Add as many comments as possible. The code should be self-explanatory, but
it is always useful to add some comments to explain the general idea of the
code, or to explain some tricky parts.
* Do not use ``from module import *`` statements, even in the ``__init__``
module of a package.
* Avoid using mixins (multiple inheritance) when possible. It is often
possible to use composition instead of inheritance.
* Avoid using ``__getattr__`` and ``__setattr__`` methods. They are often used
to implement lazy initialization, but this can be done in a more explicit
way.
Submitting patches
^^^^^^^^^^^^^^^^^^
Check-list
~~~~~~~~~~
Before submitting a patch, please check the following points:
* The code follows the coding guidelines described above.
* Build the documentation and check that it is correctly generated. *No warning
should be displayed.*
* Run pylint on the code and check that there is no error:
.. code-block:: bash
pylint --disable=fixme,C,R,W plotpy
* Run the tests and check that they all pass:
.. code-block:: bash
pytest plotpy
Pull request
~~~~~~~~~~~~
If you want to contribute to the project, you can submit a patch. The
recommended way to do this is to fork the project on GitHub, create a branch
for your modifications and then send a pull request. The pull request will be
reviewed and merged if it is accepted.
Setting up development environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want to contribute to the project, you will probably want to set up a
development environment. The easiest way to do this is to use `virtualenv
<http://pypi.python.org/pypi/virtualenv>`_ and `pip
<http://pypi.python.org/pypi/pip>`_.
Some parameters are required to be set before using the project from within
Visual Studio Code (used in `launch.json` and `tasks.json`). These are:
* ``PPSTACK_PYTHONEXE``: The path to the Python interpreter to use. This is
used to launch the application from within Visual Studio Code. If not set,
the default Python interpreter will be used.
* `.env` file: This file is used to set environment variables for the
application. It is used to set the ``PYTHONPATH`` environment variable to
the root of the project. This is required to be able to import the project
modules from within Visual Studio Code. To create this file, copy the
``.env.template`` file to ``.env`` (and eventually add your own paths).
|
