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, and pypy3 environments each build an environment from the corresponding Python version, install zope.i18nmessageid and testing dependencies, and runs the tests. It then installs Sphinx and runs the doctest snippets.

  • The coverage environment builds a virtual environment, installs zope.i18nmessageid and dependencies, installs coverage, and runs the tests with statement and branch coverage.

  • The docs environment builds a virtual environment, installs zope.i18nmessageid and dependencies, installs Sphinx 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: