Contribute

This page is intended for developers of (or contributing to) PyPubSub.

Contributing

Contributions are welcome! There are many ways you could contribute:

  • bug fixes

  • new features

  • test results on different platforms

  • documentation

  • screencasts! (of applications using PyPubSub with output when user clicks)

  • example topic trees (using pubsub.utils.printTopicTree() in latest version, or print Publisher in versions 1)

  • other improvements

  • money!

Please contact by posting on the forum pypubsub-dev forum (link in the Support section) or via http://github/schollii/pypubsub.

System Requirements

In addition to the System Requirements, the following are required:

  • To run unit tests:

    • pytest

  • To generate the docs:

    • sphinx >= 1.4.8

    • In PyPubSub 3.3, which used an older version of sphinx, sphinx had to be patched as per post on sphinx-dev, but this no longer seems to be the required:

      --- C:/Python24/Lib/site-packages/Sphinx-0.6.5-py2.4.egg_orig/sphinx/environment.py	Thu Mar 18 09:59:23 2010
+++ C:/Python24/Lib/site-packages/Sphinx-0.6.5-py2.4.egg/sphinx/environment.py	Thu Mar 18 09:57:40 2010
@@ -933,12 +933,12 @@
             node['refuri'] = node['anchorname'] or '#'
         return toc
 
-    def get_toctree_for(self, docname, builder, collapse):
+    def get_toctree_for(self, docname, builder, **tmplKw):
         """Return the global TOC nodetree."""
         doctree = self.get_doctree(self.config.master_doc)
         for toctreenode in doctree.traverse(addnodes.toctree):
             result = self.resolve_toctree(docname, builder, toctreenode,
-                                          prune=True, collapse=collapse)
+                                          prune=True, **tmplKw)
             if result is not None:
                 return result
 

      --- C:/Python24/Lib/site-packages/Sphinx-0.6.5-py2.4.egg_orig/sphinx/builders/html.py	Thu Mar 18 09:59:25 2010
+++ C:/Python24/Lib/site-packages/Sphinx-0.6.5-py2.4.egg/sphinx/builders/html.py	Thu Mar 18 09:55:40 2010
@@ -623,9 +623,9 @@
         if self.indexer is not None and title:
             self.indexer.feed(pagename, title, doctree)
 
-    def _get_local_toctree(self, docname, collapse=True):
+    def _get_local_toctree(self, docname, **tmplKw):
         return self.render_partial(self.env.get_toctree_for(
-            docname, self, collapse))['fragment']
+            docname, self, **tmplKw))['fragment']
 
     def get_outfilename(self, pagename):
         return path.join(self.outdir, os_path(pagename) + self.out_suffix)

  • To change code: PyCharm is recommended (Community Edition is sufficient). Various build configurations are available via the PyPubSub project when loaded into PyCharm.

Scripts Available

Unit Testing:

The test suite is most conveniently run from PyCharm via the “py.test in suite” build configuration. The tests can also be run automatically via pytest suite from the tests folder.

Once this passes using the project’s default interpreter, a Terminal can be opened in PyCharm (or alternately a command shell from Windows), and from the PyPubSub root folder, run tox. This will attempt to run the test suite in every 3.x version of Python, x>=3 (ie 3.3, 3.4, etc).

After changes are committed to github, GitHub Actions will automatically run the tests on Linux across supported Python versions. Results at https://github.com/schollii/pypubsub/actions/workflows/ci.yml.

There is also a buildbot maintained by Jerome Laheurte to test on additional *nix flavors, including OSX. Test results can be viewed at https://jeromelaheurte.net/buildbot/pubsub/console.

Performance Test:

A small performance test is available in the tests folder. It can be run from PyCharm via the perf build configuration. This will generate a new .pstats file which can be analysed. The test can also be run directly from command shell via python perf.py 1000. The test is meant to compare the impact of changes before/after and is designed to compare on results on the same system (hardwards, OS).

Documentation:

The documentation can be generated locally on Windows via the Gen Docs build configuration in PyCharm. Alternatively, it can be generated by running make html from the docs folder of source distribution.

The documentation is automatically built and available online at http://pypubsub.readthedocs.io. The latest from master branch is at http://pypubsub.readthedocs.io/en/master/. The stable (released) documentation is at http://pypubsub.readthedocs.io/en/stable/.

Releases

PyPubSub uses the latest stable Python packaging and distribution tools: wheel, twine, and pypi.

Generating a new release involves the following sequence of steps:

  • Verify that tox, sphinx, wheel, twine, and setuptools are installed.

  • Ensure that pytest suite runs 100%, and that the examples run without error in examples/ folder (one of the examples requires wxPython – install latest stable)

  • Ensure that tox (run from pypubsub root folder) runs to completion without errors or warnings on all versions of Python (3.x)

  • Update version number via a search-replace in the Version Change scope of PyCharm:

    • src/pubsub/__init__.py: version

    • docs/changelog.rst

    • src/pubsub/RELEASE_NOTES.txt

    • README.rst

  • Add section at top of docs/changelog.rst with details of what changed (audience: pypubsub developers)

  • Update src/pubsub/RELEASE_NOTES.txt (audience: pypubsub end-users) to have high-level summary of changes for this release, handling incompatibilities, etc

  • Update project metadata (classifiers, python_requires) in pyproject.toml

  • In docs folder:

    • Update index.rst and docs/installation.rst

    • Regenerate HTML docs via make, confirm ok (no warnings etc)

Persist to server:

  • Commit and push to remote master repository

  • Confirm that travis CI all pass

Distribute:

  • Clean out the dist/ folder

  • Generate the source and wheel distributions: python -m build

  • Upload to PyPI: twine upload dist/*

  • Verify new release info and links on https://pypi.python.org

  • Create new branch (tag) in github

  • Verify documentation updated on pypubsub.readthedocs.io

  • Confirm installation will work: attempt to install locally via PyPI, then import from Python shell and verify version

Py2Exe and cx_Freeze

For packaging py2exe or cx_Freeze (legacy/possibly out of date):