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
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
.. _coding-guide:
==============================
Taurus development guidelines
==============================
Overview
---------
This document describes taurus from the perspective of developers. Most
importantly, it gives information for people who want to contribute to the
development of taurus. So if you want to help out, read on!
How to contribute to taurus
----------------------------
Taurus is Free Software developed in open way. Contributions to code,
documentation, etc. are always welcome.
The "official" Taurus source code is hosted in a `git repository
<https://github.com/taurus-org/taurus>`_.
The details in how to contribute are described in the `CONTRIBUTING.md` file
at the root of the git repository.
Documentation
-------------
All standalone documentation should be written in plain text (``.rst``) files
using reStructuredText_ for markup and formatting. All such
documentation should be placed in directory :file:`docs/source` of the taurus
source tree. The documentation in this location will serve as the main source
for taurus documentation and all existing documentation should be converted
to this format.
Coding conventions
------------------
- Code in Taurus should follow the standard Python style conventions as
described in PEP8_. Specially:
- Use 4 spaces for indentation
- Respect the maximum of 79 characters per line
- Surround top-level function and class definitions with two blank lines.
- use ``lower_case`` for module names. If possible prefix module names with the
word ``taurus`` (like :file:`taurusutil.py`) to avoid import mistakes.
- use ``CamelCase`` for class names
- use ``lower_case`` for method names, except in the context of taurus.qt
where the prevailing convention is ``mixedCase`` due to influence from PyQt
- Code must be simultaneously compatible with python 2.7 and >=3.5. If required,
the future_ module can be used for helping in writing python 2+3 compatible code.
- Every python module file should contain license information (see template below).
The preferred license is the LGPL_. If you need/want to use a different one,
it should be compatible with the LGPL v3+.
- avoid polluting namespace by making private definitions private (``__`` prefix)
or/and implementing ``__all__`` (see template below)
- whenever a python module can be executed from the command line, it should
contain a ``main`` function and a call to it in a ``if __name__ == "__main__"``
like statement (see template below)
- All public API code should be documented (modules, classes and public API) using
Sphinx_ extension to reStructuredText_
The following code can serve as a template for writing new python modules to
taurus::
#!/usr/bin/env python
#############################################################################
##
# This file is part of Taurus
##
# http://taurus-scada.org
##
# Copyright 2011 CELLS / ALBA Synchrotron, Bellaterra, Spain
##
# Taurus is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
##
# Taurus is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Lesser General Public License for more details.
##
# You should have received a copy of the GNU Lesser General Public License
# along with Taurus. If not, see <http://www.gnu.org/licenses/>.
##
#############################################################################
"""A :mod:`taurus` module written for template purposes only"""
__all__ = ["TaurusDemo"]
__docformat__ = "restructuredtext"
class TaurusDemo(object):
"""This class is written for template purposes only"""
def main():
print "TaurusDemo"
if __name__ == "__main__":
main()
Special notes about Qt programming
-----------------------------------
The following Qt guidelines are intended to ensure compatibility between all
PyQt4, PyQt5 and PySide versions.
1. Avoid importing PyQt / PySide directly. Imports like::
from PyQt4 import Qt
from PyQt4 import QtCore
from PyQt4 import QtGui
from PyQt4 import QtNetwork
from PyQt4 import QtWebKit
from PyQt4 import Qwt5
Should be replaced by::
from taurus.external.qt import Qt
from taurus.external.qt import QtCore
from taurus.external.qt import QtGui
from taurus.external.qt import QtNetwork
from taurus.external.qt import QtWebKit
from taurus.external.qt import Qwt5
2. Since Taurus v>=4.0, Qt-based code in Taurus assumes
that `PyQt API v2`_ is used. PyQt API 1 code is not accepted in taurus.
- Use standard python strings (e.g., use :class:`str` for Qt strings instead of
:class:`QString`). Code like::
my_string = Qt.QString(" hello ")
my_string2 = my_string.trimmed()
Should be replaced by::
my_string = " hello "
my_string2 = my_string.strip()
- Do not use :class:`QVariant`. Code like::
def setData(self, index, qvalue, role=Qt.Qt.EditRole):
value = qvalue.toString() # this assumes qvalue to be a :class:`QVariant`
self.buffer[index.column()] = value
def data(self, index, role=Qt.Qt.DisplayRole):
value = self.buffer[index.column()]
if role == Qt.Qt.DisplayRole:
return Qt.QVariant(value)
else:
return Qt.QVariant()
Should be replaced by::
def setData(self, index, value, role=Qt.Qt.EditRole):
self.buffer[index.column()] = value # value is already a python object
def data(self, index, role=Qt.Qt.DisplayRole):
value = self.buffer[index.column()]
if role == Qt.Qt.DisplayRole:
return value
else:
return None
For backwards-compatibility reasons, `taurus.external.qt.QtCore` defines `QVariant`,
`from_qvariant()` and `to_qvariant()`, but they are deprecated and should not be used
anymore.
3. Use `new-style signals`_.
Old-style code like the following::
class MyWidget(Qt.QWidget):
def foo(self):
self.connect(self, Qt.SIGNAL('mySignal(int)', self.bar))
self.emit(Qt.SIGNAL('mySignal(int)', 123))
Should be replaced by::
class MyWidget(Qt.QWidget):
mySignal = Qt.pyqtSignal(int)
def foo(self):
self.mySignal.connect(self.bar)
self.mySignal.emit(123)
4. The `taurus.external.qt.compat` module defines some convenience utilities
that help in writing Qt-binding agnostic code
5. Use of :class:`taurus.qt.qtgui.application.TaurusApplication` instead of
:class:`QApplication` is recommended (it takes care of various
initialization and exit tasks that are convenient).
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://www.sphinx-doc.org
.. _PEP8: http://www.python.org/peps/pep-0008.html
.. _LGPL: http://www.gnu.org/licenses/lgpl.html
.. _`PyQt API v2`: http://pyqt.sourceforge.net/Docs/PyQt4/incompatible_apis.html
.. _`new-style signals`: http://pyqt.sourceforge.net/Docs/PyQt4/new_style_signals_slots.html
.. _future: https://python-future.org/
|
