Development

This page contains resources for developing with Phonological CorpusTools

GUI

PCT uses PyQt5, which differs from PyQt4 primarily in the location of widgets in the API (QtWidgets rather than QtGui) and in some newer/renamed modules. The imports.py file should take care of this, since all GUI imports should be done there. GUI modules should then import via from .imports import *.

Tutorials

• http://www.pythoncentral.io/series/python-pyside-pyqt-tutorial/ - This page has 8 tutorials for various aspects of PySide/PyQt (using Qt4 version, so ignore the importing, but the rest should be the same). Also note that signals in imports.py are imported as Signal (similar to PySide) rather than pyqtSignal.
• http://zetcode.com/gui/pyqt5/ - Tutorial using PyQt5.

Model/View

• http://doc.qt.io/qt-5/model-view-programming.html - Qt5 Model/View overview (C++)
• http://doc.qt.io/qt-5/modelview.html - Qt5 Tutorial (C++)
• http://www.yasinuludag.com/blog/?p=98 - Model/View tutorial (youtube videos)
• http://files.meetup.com/2179791/pyqt-model-view-framework-overview.pdf - slides

API reference

• PySide (https://srinikom.github.io/pyside-docs/) Generally the same as PyQt4, more python oriented documentation (PySide should support Qt5 in the near future).
• PyQt4 (http://pyqt.sourceforge.net/Docs/PyQt4/classes.html) Same as PySide, copied from the Qt4 documentation (C++, not python, though it's pretty translatable).
• Qt5 (http://doc.qt.io/qt-5/) The actual version of Qt we're using. PyQt5's documentation just links to here.

Testing

PCT uses pytest as its unit testing suite. When creating new functions or when there are new bug reports, please create unit tests for them to prevent the issue from arising in the future (Relevant blog post: https://www.jeffknupp.com/blog/2013/12/09/improve-your-python-understanding-unit-testing/)

Examples available here: http://pytest.org/latest/example/

Documentation

PCT uses sphinx to build its documentation. PCT code should follow the NumPy style for documentation: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

To generate documentation:

• Make sure sphinx and numpydoc are installed (pip install sphinx numpydoc).
• Change directory to docs (cd CorpusTools/docs).
• Run sphinx-build source build (or sphinx-build -b latex source build to generate the LaTeX files for a pdf).
• HTML documentation (or LaTeX files) will be available in CorpusTools/docs/build.
• To make a pdf from LaTeX, pdflatex must be run on the generated LaTeX files.

Code quality

A talk I highly recommend is by Raymond Hettinger at PyCon 2015 titled "Beyond PEP 8 -- Best practices for beautiful intelligible code" available at https://www.youtube.com/watch?v=wf-BqAjZb8M.

PEP8 (https://www.python.org/dev/peps/pep-0008/) is the general style guide for Python.

Good blogs:

• http://jeffknupp.com/
• http://sahandsaba.com/
• https://www.reddit.com/r/Python
• http://gael-varoquaux.info/programming/improving-your-programming-style-in-python.html

Principles of software design

Principles of object-oriented programming https://en.wikipedia.org/wiki/SOLID_%28object-oriented_design%29

Additional resources:

• Don't repeat yourself (http://www.artima.com/intv/dry.html)
• Anti-patterns (http://sahandsaba.com/nine-anti-patterns-every-programmer-should-be-aware-of-with-examples.html)
• Patterns (http://python-3-patterns-idioms-test.readthedocs.org/en/latest/PatternConcept.html, https://en.wikipedia.org/wiki/Software_design_pattern)

Code smells

Code smells is a catch-all term for code that works, but is less than ideal for long term maintainability.

Resources:

• http://blog.codinghorror.com/code-smells/

Refactoring

Refactoring is an important part of code maintenance.

Resources:

• http://www.diveintopython3.net/refactoring.html
• http://electronician.hubpages.com/hub/How-To-Refactor-Code-In-Python-A-Beginners-Guide

Backwards compatibility

In most cases it's good to maintain backwards compatibility. When objects have new attributes that are used for functioning, compatibility checks can be added to the __setstate__ function of the class. __setstate__ is called while unpickling an object, and the state argument it takes is a dictionary of attributes and their values. The corpustools/corpus/lexicon.py file has many examples.

Executable building

The current build process is unfortunately fairly fragmented, due to mismatches in what freezer modules support on various platforms.

Windows

For Windows, esky (https://github.com/cloudmatrix/esky) is used to make the executable (due to the possibility of self updating, not working yet). To make an installer:

1. Run python esk_setup.py bdist_esky in the root directory, which will create a zip file in the dist/ folder.
2. Unzip that in the same folder.
3. Run pct.iss using InnoSetup (http://www.jrsoftware.org/isinfo.php). InnoSetup will create a Windows installer in the Output/ folder.

Mac

There are two potential ways of installing PCT and its dependencies for development and building. The Anaconda route is simpler in some sense (and probably faster) as it doesn't involve system level installations. Instead it uses virtual environments, so the installation is isolated from the system version of Python. The MacPorts version will involve more compilation and the potential for more issues.

NB: I have only tested it on MacOSX 10.8, on the same machine used to create the pyqt5 conda packages, which may be different enough from a given user's machine.

Might require Xcode 5.1.1 or higher? Maybe only 10.8+?

With Anaconda (probably easiest and more reliable):

1. Download Miniconda install script (https://repo.continuum.io/miniconda/Miniconda3-latest-MacOSX-x86_64.sh)
2. Open terminal and go to download location (cd ~/Downloads)
3. Install Miniconda (chmod +x Miniconda3-latest-MacOSX-x86_64.sh && ./Miniconda3-latest-MacOSX-x86_64.sh -b -p ~/miniconda)
4. Close terminal and reopen (the command conda list should work in new terminal)
5. Create pct environment (conda create -c mmcauliffe -n pct python=3 numpy scipy scikit-learn networkx pyqt5)
6. Activate pct environment (source activate pct)
7. Install python-acoustic-similarity (pip install acousticsim --allow-external textgrid --allow-unverified textgrid --process-dependency-links)
8. Install pytest (conda install pytest) -- Not needed for building
9. Install pytest-qt (git clone https://github.com/mmcauliffe/pytest-qt.git && cd pytest-qt && python setup.py install) -- Not needed for building
10. Install cx_Freeze (pip install cx-freeze) -- Not needed for development
11. Get CorpusTools (git clone https://github.com/PhonologicalCorpusTools/CorpusTools.git)
12. Make sure PCT works (python CorpusTools/bin/pct_qt_debug.py)
13. To build (in the CorpusTools directory) run python cx_setup.py bdist_dmg

With MacPorts (potentially more finicky):

1. Install MacPorts (https://www.macports.org/install.php)
2. Install python (sudo port install atlas python34 py34-pip py34-pyqt5)
3. Install prerequisites (sudo pip-3.4 install numpy scipy skikit-learn networkx)
4. Install pytest (sudo pip-3.4 install pytest) -- Not needed for building
5. Install pytest-qt (git clone https://github.com/mmcauliffe/pytest-qt.git && cd pytest-qt && sudo python3.4 setup.py install) -- Not needed for building
6. Install cx_Freeze (sudo pip-3.4 install cx-freeze) -- Not needed for development
7. Get CorpusTools (git clone https://github.com/PhonologicalCorpusTools/CorpusTools.git)
8. Make sure PCT works (python3.4 CorpusTools/bin/pct_qt_debug.py)
9. To build (in the CorpusTools directory) run python3.4 cx_setup.py bdist_dmg

For Mac, cx_freeze (http://cx-freeze.readthedocs.org/en/latest/) is used to make the .dmg file. To create the DMG, run python cx_setup.py bdist_dmg. The resulting DMG will be in the dist/ folder.