How to contribute ================= Submitting changes ------------------ Due to confidentiality issues, we are not able *for now* to publish any source- controlled repository (even if we do have a `Mercurial` repository for the project). However, this does not prevent motivated users from contributing to the project by sending patches applied to the last published version of the library. To compensate the absence of source repository, we try to update the library as often as we can in order to keep the public source archive version as close as possible to the internal development version. 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 `_ The easiest way to check that your code is following those guidelines is to run `pylint` (a note greater than 8/10 seems to be a reasonnable goal). PyQt v4.4 compatibility issues ------------------------------ The project has to be compatible with PyQt >= v4.4 which means that the following recommendations should be followed: * avoid using `super`: when writing classes deriving from a QObject child class (i.e. almost any single class imported from QtGui or QtCore), the `super` builtin-function should not be used outside the constructor method (call the parent class method directly instead) * before using any function or method from PyQt4, please check that the feature you are about to use was already implemented in PyQt4 v4.4 (more precisely in the Qt version used in PyQt4 v4.4) -- if not, a workaround should be implemented to avoid breaking compatibility * do not use the PyQt-specific QFileDialog static methods (not present in Qt) which were introduced in PyQt v4.6: `getOpenFileNameAndFilter`, `getOpenFileNamesAndFilter` and `getSaveFileNameAndFilter` (`guidata` provides wrappers around `QFileDialog` static methods handling the selected filter which were taken from the `spyderlib` library (from module `spyderlib.qt.compat`): they are available in `guidata.qt.compat`) PyQt / PySide compatibility --------------------------- The project should be mostly compatible with both PyQt and PySide (although PySide is not as popular as it used to be, so testing tend to be limited). PyQt5 compatibility ------------------- In its current implementation, the code base has to be compatible with PyQt API #2 (PySide-compatible API, PyQt >= v4.6) and with PyQt5, which means that the following recommendations should be followed: * `QVariant` objects must not be used (API #2 compatibility) * Use exclusively new-style signals and slots * Read carefully PyQt5 documentation regarding class inheritance behavior: it is quite different than the old PyQt4 implementation. Producing code compatible with both PyQt4 and PyQt5 can be tricky: testing is essential. Python 3 compatibility ---------------------- Regarding Python 3 compatibility, we chose to handle it by maintaining a single source branch being compatible with both Python 2.6-2.7 and Python 3. Here is what we have done. Fixing trivial things with 2to3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The first step is to run the `2to3` script (see Python documentation) to convert print statements to print function calls -- note that your source directory (named `directory_name`) has to be version controlled (no backup is done thanks to the `-n` option flag). `python 2to3.py -w -n -f print directory_name` Open each modified source file and add the following line at the beginning: from __future__ import print_function Then run again `2to3` with all other Python 2/3 compatible fixers: `python 2to3.py -w -n -f apply -f dict -f except -f exitfunc -f filter -f has_key -f map -f ne -f raise -f ws_comma -f xrange -f xreadlines -f zip directory_name` After these two steps, your code should be compatible with Python 2.6, 2.7 and 3.x, but only with respect to the simplest changes that occured between Python 2 and Python 3. However, this a step forward to Python 3 compatibility without breaking Python 2.6+ compatibility. Fixing unicode issues ~~~~~~~~~~~~~~~~~~~~~ In Python 3, `unicode` and `str` strings have been replaced by `str` and `bytes` strings: * `str` is the text string type, supporting unicode characters natively * `bytes` is the binary string type. As a consequence, Python 2 code involving strings may cause compatibility issues with Python 3. For example: * file I/O may return `bytes` instead of `str` in Python 3 (depending on the open mode): this can be solved by calling the `decode` method on the `bytes` object (this will work on both Python 2 `str` and Python 3 `bytes` objects) * in Python 3.0-3.2, the `u'unicode text'` or `u"unicode text"` syntax is not allowed and will raise a SyntaxError: this can be solved by inserting the `from __future__ import unicode_literals` at the beginning of the script and by removing all the `u` string prefixes * in Python 3 `isinstance(text, basestring)` can be replaced by `is_text_string(text)` (function of the `guidata.py3compat` module) * in Python 3 `isinstance(text, unicode)` can be replaced by `is_unicode(text)` (function of the `guidata.py3compat` module) * in Python 3 `unicode(text)` can be replaced by `to_text_string(text)` (function of the `guidata.py3compat` module)