Developer Guide

This part of the documentation currently acts as a note pad. Information contained may be incomplete and incoherent. It will improve over time.

Coding Conventions

Adding a new Source Code File

  1. Add the file to the packages section of setup.py.
  2. Add the copyright note.
  3. Document the file by using docstrings (Sphinx).
  4. Add the file to the documentation:
    1. Add the module to the proper .rst file. You may need to create a new one. In that case, ensure that the new .rst is also added to the proper file in the documentation tree.
    2. Create a new build of the documentation and check if your references are set correctly and see if new errors/warnings have occurred.
  5. If the file contains new features, ensure you have written a test case. Add it to the test package. Repeat steps 2-4 for the test file.

Generating the Documentation

Sphinx is used to document SeriesMarker. The documentation is rendered per default with the Alabaster theme. You may need to install both on your system beforehand:

$pip install sphinx alabaster

To generate the documentation for SeriesMarker, perform the following steps:

  1. Check out SeriesMarker.

  2. Change to the doc sub directory.

    • on Linux / OS X:

      execute make html.

    • on Windows:

      execute make.bat html.

  4. The resulting documentation can be found at the doc/build/html sub directory. It contains an index.html file, which can be opened with a browser to display the generated documentation.

Testing

To run all existing test cases, after checking out SeriesMarker, execute the following command at SeriesMarker’s root directory:

$python setup test

This will build SeriesMarker and run all tests against it. To skip the package creation, run the test suite directly via:

$python -m unittest seriesmarker/test/test_runner.py

To only run topic specific test cases, similar suits can be found in the sub packages of the test directory:

$python setup.py test --test-suite="seriesmarker.test.database.database_test_runner"
$python setup.py test --test-suite="seriesmarker.test.gui.gui_test_runner.py"

respectively

$python -m unittest seriesmarker/test/database/database_test_runner.py
$python -m unittest seriesmarker/test/gui/gui_test_runner.py

Distributing SeriesMarker

This section describes how a binary package of SeriesMarker can be built for various operating systems.

Microsoft Windows

On Microsoft Windows, cx_Freeze is the recommended tool to create a binary package of SeriesMarker.

Prerequisites

The prerequisites to build a binary package of SeriesMarker on Microsoft Windows are the same as for building from source. Please fulfill those first before continuing.

Install Dependencies

Install SeriesMarker’s dependencies via pip. In addition, cx_Freeze needs to be installed:

pip install cx_Freeze

Creating a Binary Distribution

This section describes, how to create an installer for SeriesMarker from source.

  1. Check out SeriesMarker.
  2. Open the Command Prompt (cmd.exe) and change to the root directory of SeriesMarker.
  3. Execute python setup.py bdist_msi to create a msi-installer, which can be found at the dist directory.

The installer can then be used as described in the install procedure for Microsoft Windows.

OS X

On OS X, py2app is the recommended tool to create a binary package of SeriesMarker.

Prerequisites

The prerequisites to build a binary package for SeriesMarker on OS X are the same as for building from source. Please fulfill those first before continuing.

Install Dependencies

Proceed as described in Install Dependencies. In addition, py2app needs to be installed:

$sudo port install py34-py2app

Prepare Packages

py2app

There is a py2app bug, which prevents the app to function properly with recent versions of one of its dependencies inside virtual environments. To resolve it, open the virtualenv recipe file of py2app, probably located at

/opt/local/Library/Frameworks/Python.framework/Versions/3.4/lib/python3.4/site-packages/py2app/recipes/virtualenv.py

and modify the load_module and scan_code method calls as shown in the bug report.

Creating a Binary distribution

When your system is prepared to build SeriesMarker as described in the previous sections, you can now create a distributable binary with the following steps:

  1. Check out SeriesMarker.
  2. Open a shell (Terminal) and change to the root directory of SeriesMarker.
  3. Execute python3.4 setup.py py2app to create an application and a disk image, containing a copy of the application. Both can be found at the dist directory.

The resulting app can then be used as usual. The disk image is the preferred way to distribute the application, providing a simple installer as shown in the install procedure for OS X.

Todo List

Todo

Update should also recognize/announce updated episodes.

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/gui/main_window.py:docstring of seriesmarker.gui.main_window.MainWindow.on_action_update_triggered, line 3.)

Todo

Should change view only if next style differs from current one - needs to compare with previous selection.

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/gui/main_window.py:docstring of seriesmarker.gui.main_window.MainWindow.on_tree_view_clicked, line 7.)

Todo

Should return a pixmap of an episode snapshot image instead of a default icon. By solving the todo, this method becomes obsolet and needs to be deleted - use/override DecoratedNode.banner_url() instead.

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/gui/model/episode_node.py:docstring of seriesmarker.gui.model.episode_node.EpisodeNode.decoration, line 6.)

Todo

The banner_loader may cause an access to an invalid index if another search with less results was initiated before all banner were loaded. Prevent the beginning of a new search before the last has been finished, or clear the banner_loader at clearing this model. Afterwards remove the warning log. Also remove the None check at setData of this model then.

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/gui/model/search/search_model.py:docstring of seriesmarker.gui.model.search.search_model.SearchModel.node_at, line 6.)

Todo

Update of CheckState / progress kinda ugly, may be done in check(value), but needs reference to index and model - add reference to each node? Example: for change in changes: self.dataChanged.emit(change.get_index())

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/gui/model/tree_series_model.py:docstring of seriesmarker.gui.model.tree_series_model.TreeSeriesModel.setData, line 24.)

Todo

After upgrade to QT5, use SignalSpy in test case to check if only changes are emitted if there was really a change after checking.

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/gui/model/tree_series_model.py:docstring of seriesmarker.gui.model.tree_series_model.TreeSeriesModel.setData, line 30.)

Todo

Accept button of SearchDialog should be disable while search is ongoing, or no valid result has been selected yet.

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/gui/search_dialog.py:docstring of seriesmarker.gui.search_dialog.SearchDialog.accept, line 7.)

Todo

Method may be omitted in favor of public attribute if unittest.mock offers a way to set it for testing.

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/gui/search_dialog.py:docstring of seriesmarker.gui.search_dialog.SearchDialog.result_value, line 5.)

Todo

Check if item really is generic, dispatch to proper remove function otherwise.

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/persistence/database.py:docstring of seriesmarker.persistence.database.db_remove_item, line 3.)

Todo

Convert banner_type to Enum, as soon as Python supports it (probably 3.4).

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/persistence/factory/banner_factory.py:docstring of seriesmarker.persistence.factory.banner_factory.BannerFactory.new_banner, line 13.)

Todo

Logging should be used to list differences on update of series/episodes.

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/persistence/factory/base_factory.py:docstring of seriesmarker.persistence.factory.base_factory.BaseFactory._handle_list_attribute, line 15.)

Todo

Episode specials have additional attributes where regular ones do not. The pytvdbapi logs an exception if it is tried to access them on a regular episode. Either check existence beforehand, or see if pytvdbapi changes output.

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/persistence/factory/episode_factory.py:docstring of seriesmarker.persistence.factory.episode_factory.EpisodeFactory.new_episode, line 13.)

Todo

Instead of adding each series sequentially, the model could be expanded with a method to add multiple series, which could speed up the application’s start.

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/seriesmarker.py:docstring of seriesmarker.seriesmarker.main, line 6.)

Todo

Might be merged with StoryTest in separate test-class to reduce boilerplate code (setUpClass, setUp).

(The original entry is located in /home/tobias/Workspaces/Python/SeriesMarker/seriesmarker/test/gui/sorting_test.py:docstring of seriesmarker.test.gui.sorting_test.SortingTest, line 8.)