Hacking on zope.i18nmessageid
¶
Getting the Code¶
The main repository for zope.i18nmessageid
is in the Zope Foundation
Github repository:
You can get a read-only checkout from there:
$ git clone https://github.com/zopefoundation/zope.i18nmessageid.git
or fork it and get a writeable checkout of your fork:
$ git clone git@github.com/jrandom/zope.i18nmessageid.git
Working in a Python virtual environment¶
Installing¶
You can use Python’s standard venv
package to create lightweight Python
development environments, where you can run the tests using nothing more
than the python
binary in a virtualenv. First, create a scratch
environment:
$ python3.12 -m venv /tmp/hack-zope.i18nmessageid
Next, install this package in “development mod” in the newly-created environment:
$ /tmp/hack-zope.i8nmessageid/bin/pip install -e .
Running the tests¶
Once installed, you can run the tests using the standard library’s
unittest
module:
$ /tmp/hack-zope.i8nmessageid/bin/python -m unittest discover -s src
.........................................
----------------------------------------------------------------------
Ran 41 tests in 0.002s
OK
You can install a more comprehensive set of tools using the testing
extra:
$ /tmp/hack-zope.i8nmessageid/bin/pip install -e ".[testing]"
That command installs the tools needed to run
the tests: in particular, the zope.testrunner
(see
:external+testrunner:std:doc:`getting-started`) and
:external+coverage:std:doc:`index` tools.
To run the tests via zope.testrunner
:
$ /tmp/hack-zope.i8nmessageid/bin/zope-testrunner --test-path=src
Running zope.testrunner.layer.UnitTests tests:
Set up zope.testrunner.layer.UnitTests in 0.000 seconds.
Ran 41 tests with 0 failures, 0 errors and 0 skipped in 0.003 seconds.
Tearing down left over layers:
Tear down zope.testrunner.layer.UnitTests in 0.000 seconds.
Running the tests under coverage
lets you see how well the tests
cover the code:
$ /tmp/hack-zope.i8nmessageid/bin/coverage run -m zope.testrunner \
--test-path=src
...
$ coverage report -i -m --fail-under=100
Name Stmts Miss Branch BrPart Cover Missing
----------------------------------------------------------------------------------
src/zope/i18nmessageid/__init__.py 4 0 0 0 100.00%
src/zope/i18nmessageid/message.py 52 0 18 0 100.00%
src/zope/i18nmessageid/tests.py 189 0 38 0 100.00%
----------------------------------------------------------------------------------
TOTAL 245 0 56 0 100.00%
Building the documentation¶
zope.i18nmessageid
uses the nifty Sphinx
documentation system
for building its docs. Using the same virtualenv you set up to run the
tests, you can build the docs:
The docs
command alias downloads and installs Sphinx and its dependencies:
$ /tmp/hack-zope.i8nmessageid/bin/pip install ".[docs]"
...
$ /tmp/hack-zope.i8nmessageid/bin/sphinx-build -b html -d docs/_build/doctrees docs docs/_build/html
...
build succeeded.
The HTML pages are in docs/_build/html.
You can also test the code snippets in the documentation:
$ /tmp/hack-zope.i8nmessageid/bin/sphinx-build -b doctest -d docs/_build/doctrees docs docs/_build/doctest
...
running tests...
Document: narr
--------------
1 items passed all tests:
35 tests in default
35 tests in 1 items.
35 passed and 0 failed.
Test passed.
Doctest summary
===============
35 tests
0 failures in tests
0 failures in setup code
0 failures in cleanup code
build succeeded.
Testing of doctests in the sources finished, look at the results in docs/_build/doctest/output.txt.
Using tox
¶
Running Tests on Multiple Python Versions¶
tox is a Python-based test automation tool designed to run tests against multiple Python versions. It creates a virtual environment for each configured version, installs the current package and configured dependencies into each environment, and then runs the configured commands.
zope.i18nmessageid
configures the following tox
environments via
its tox.ini
file:
The
lint
environment runs various “code quality” tests on the source, and fails on any errors they find.The
py38
,py39
,py310
,py311
,py312
,py313
, andpypy3
environments each build an environment from the corresponding Python version, installzope.i18nmessageid
and testing dependencies, and runs the tests. It then installsSphinx
and runs the doctest snippets.The
coverage
environment builds a virtual environment, installszope.i18nmessageid
and dependencies, installscoverage
, and runs the tests with statement and branch coverage.The
docs
environment builds a virtual environment, installszope.i18nmessageid
and dependencies, installsSphinx
and dependencies, and then builds the docs and exercises the doctest snippets.
This example requires that you have a working python3.12
on your path,
as well as installing tox
:
$ tox -e py312
py312: install_deps> python -I -m pip install 'setuptools<69' Sphinx
...
py312: commands[0]> zope-testrunner --test-path=src -vc
Running tests at level 1
Running zope.testrunner.layer.UnitTests tests:
Set up zope.testrunner.layer.UnitTests in 0.000 seconds.
Running:
.........................................
Ran 41 tests with 0 failures, 0 errors, 0 skipped in 0.003 seconds.
Tearing down left over layers:
Tear down zope.testrunner.layer.UnitTests in 0.000 seconds.
py312: commands[1]> sphinx-build -b doctest -d /home/tseaver/projects/Zope/Z3/zope.i18nmessageid/.tox/py312/.cache/doctrees docs /home/tseaver/projects/Zope/Z3/zope.i18nmessageid/.tox/py312/.cache/doctest
Running Sphinx v7.3.7
...
running tests...
Document: narr
--------------
1 items passed all tests:
35 tests in default
35 tests in 1 items.
35 passed and 0 failed.
Test passed.
Doctest summary
===============
35 tests
0 failures in tests
0 failures in setup code
0 failures in cleanup code
build succeeded.
Testing of doctests in the sources finished, look at the results in .tox/py312/.cache/doctest/output.txt.
py312: OK (16.29=setup[15.11]+cmd[0.26,0.92] seconds)
congratulations :) (16.56 seconds)
Running tox
with no arguments runs all the configured environments,
including building the docs and testing their snippets:
$ tox
lint: commands[0]> isort --check-only --diff /home/tseaver/projects/Zope/Z3/zope.i18nmessageid/src /home/tseaver/projects/Zope/Z3/zope.i18nmessageid/setup.py
lint: commands[1]> flake8 src setup.py
lint: OK (0.50=setup[0.02]+cmd[0.19,0.28] seconds)
congratulations :) (0.73 seconds)
...
__________________________________ summary ____________________________________
lint: commands succeeded
py37: commands succeeded
...
pypy3: commands succeeded
docs: commands succeeded
coverage: commands succeeded
congratulations :)
Contributing to zope.i18nmessageid
¶
Submitting a Bug Report¶
zope.i18nmessageid
tracks its bugs on Github:
Please submit bug reports and feature requests there.
Sharing Your Changes¶
Note
Please ensure that all tests are passing before you submit your code. If possible, your submission should include new tests for new features or bug fixes, although it is possible that you may have tested your new code by updating existing tests.
If have made a change you would like to share, the best route is to fork the Githb repository, check out your fork, make your changes on a branch in your fork, and push it. You can then submit a pull request from your branch: