Utilities to help build Workbench modules
Project description
Utilities for CJWorkbench modules.
Workbench modules may optionally depend on the latest version of this Python package for its handy utilities:
cjwmodule.arrow.format
: functions to convert Arrow arrays to text.cjwmodule.http
: HTTP helpers, including the handyhttpfile
format.cjwmodule.i18n
: Atrans()
function for producing translatable text.cjwmodule.testing
: Functions to help in unit testing.cjwmodule.util.colnames
: Functions to help build a valid table's column names.
Developing
- Run
tox
to confirm that unit tests pass - Write a failing unit test in
tests/
- Make it pass by editing code in
cjwmodule/
black cjwmodule tests && isort --recursive cjwmodule tests
- Submit a pull request
Be very, very, very careful to preserve a consistent API. Workbench will upgrade this dependency without module authors' explicit consent. Add new features; fix bugs. Never change functionality.
I18n
Marking strings for translation
Strings in cjwmodule
can be marked for translation using cjwmodule.i18n._trans_cjwmodule
.
Each translation message must have a (unique) ID. ICU is supported for the content.
For example,
from cjwmodule.i18n import _trans_cjwmodule
err = "Error 404"
with_arguments = _trans_cjwmodule(
"greatapi.exception.message",
"Something is wrong: {error}",
{"error": err}
)
without_arguments = _trans_cjwmodule(
"greatapi.exception.general",
"Something is wrong",
)
Workbench is wired to accept the return value of _trans_cjwmodule
wherever an error/warning or quick fix is expected.
Creating po
catalogs
Calls to _trans_cjwmodule
can (and must) be parsed to create cjwmodule
's .po
files.
Update the .po
files with:
./setup.py extract_messages
The first time you run this, you'll need to install dependencies: pip3 install .[maintenance]
Unit testing
In case a _trans_cjwmodule
invocation needs to be unit tested, you can use cjwmodule.testing.i18n.cjwmodule_i18n_message
in a manner similar to the following:
from cjwmodule.testing.i18n import cjwmodule_i18n_message
import with_arguments, without_arguments
assert with_arguments == cjwmodule_i18n_message("greatapi.exception.message", {"error": "Error 404"})
assert without_arguments == cjwmodule_i18n_message("greatapi.exception.general")
Message deprecation
For backwards compatibility, messages in cjwmodule
's po
files are never deleted!
Publishing
- Write a new
__version__
tocjwmodule/__init__.py
. Adhere to semver. (As changes must be backwards-compatible, the version will always start with1
and look like1.x.y
.) - Prepend notes to
CHANGELOG.md
about the new version git commit
git tag v1.x.y
git push --tags && git push
- Wait for Travis to push our changes to PyPI
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.