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
|
Contribute
==========
This page is intended for developers of (or contributing to) PyPubSub.
.. contents:: In this section:
:depth: 1
:local:
.. _label-contributing:
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
:ref:`label-support` section) or via http://github/schollii/pypubsub.
System Requirements
-------------------
In addition to the :ref:`label-install-reqs`, 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:
.. literalinclude:: sphinx_patch1.txt
.. literalinclude:: sphinx_patch2.txt
- 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 :file:`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 :command:`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, the Travis CI will automatically
run the tests on a Linux platform, for all versions of Python supported
by PyPubSub. The results will be at https://travis-ci.org/schollii/pypubsub/builds.
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 :file:`tests` folder.
It can be run from PyCharm via the perf build configuration. This will
generate a new :file:`.pstats` file which can be analysed.
The test can also be run directly from command shell via
:command:`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
:command:`make html` from the :file:`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 the setup.py classifiers (such as adding a new version of Python supported)
- 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 setup.py bdist_wheel sdist`
- Upload to PyPI: twine upload dist/\*:
- Verify new release info and links on pypi.python.org
- Create new branch (tag) in remote master repository
- Confirm installation will work: attempt to install locally via PyPI, then import
from Python shell
Py2Exe and cx_Freeze
--------------------
For packaging py2exe or cx_Freeze, see (possibly out of date):
.. toctree::
py2exe.rst
|
