Introduction
============
This package compiles po files.
It contains a `zest.releaser`_ entrypoint and a stand-alone command line tool.
Goal
====
You want to release a package that has a ``locales`` dir
(or ``locale``, or something else as long as it has a ``LC_MESSAGES`` folder somewhere in it)
with translations in ``.po`` files.
You want to include the compiled ``.mo`` files in your release as well,
but you do not want to keep those in a revision control system (like git) as they are binary and can be easily recreated.
That is good.
This package helps with that.
Want ``.mo`` files? Add a ``MANIFEST.in`` file.
================================================
When you use ``python setup.py sdist`` to create a source distribution, Python does *not* automatically include all files.
It might look at the information of the revision control system (RCS), but that may or may not work.
This depends on your RCS, your Python version, setuptools, or extra packages like ``setuptools-git``.
Since the compiled ``.mo`` files are best not stored in git (or any other RCS), you need to give a hint on which files to include.
You do this by adding a ``MANIFEST.in`` file.
Let's say your package has roughly these contents (not all files are shown)::
your.package/setup.py
your.package/your/package/locales/nl/LC_MESSAGES/domain.po
Then you need a ``MANIFEST.in`` file like this::
recursive-include your *
Or with a bigger example::
recursive-include your *
recursive-include docs *
include *
global-exclude *.pyc
I will explain the lines one by one for clarity.
And yes: I (Maurits) now simply go to this page on PyPI if I want to have an example of a proper ``MANIFEST.in`` file.
So this documentation is now getting slightly larger than strictly needed. :-)
``recursive-include your *``
This tells distutils to recursively include all (``*``) files and directories within the ``your`` directory.
Try it: create a directory structure like the above example with a proper ``setup.py``,
copy the ``domain.po`` file to ``domain.mo`` as a silly test,
run ``python setup.py sdist``
and check that the ``.mo`` file ends up in the created distribution.
``recursive-include docs *``
Include files in the ``docs`` directory.
If this directory does not exist, you will get a warning, so you may want to remove it then, but leaving it there does not hurt.
``include *``
Include unrecognized files in the root directory.
Oterwise by default only standard files like ``README.txt``, ``setup.py``, and ``setup.cfg`` are included.
So for example a ``CHANGES.txt`` file must be explicitly included (here with ``*``).
``global-exclude *.pyc``
This avoids unnecessarily adding compiled python files in the release.
When these are not there, for example after a fresh checkout, you will get a harmless warning: ``no previously-included files matching '*.pyc' found anywhere in distribution``.
For more info on creating a source distribution and how to use ``MANIFEST.in`` see the `Python distutils documentation <http://docs.python.org/distutils/sourcedist.html>`_
or the `setuptools documentation <https://setuptools.readthedocs.io/en/latest/setuptools.html>`_.
With this part working, the only thing this ``zest.pocompile`` package needs to do, is to actually find all ``.po`` files and compile them to ``.mo`` files.
It simply looks for directories that are named ``LC_MESSAGES`` and compiles all ``.po`` files found in there.
Command line tool
=================
When you ``pip install zest.pocompile`` you get a command line tool ``pocompile``.
When you run it, this walks the current directory, finds all po translation files in a properly formed locales directory, and compiles them into ``.mo`` files.
You can also give it a list of directories as arguments instead.
Run it with the ``--help`` option to get some help.
In the above example, if you are in the ``your.package`` directory and run ``pocompile`` it will create this file::
your.package/your/package/locales/nl/LC_MESSAGES/domain.mo
zest.releaser entry point
=========================
You do not need `zest.releaser`_ for a proper functioning of ``zest.pocompile``.
But if you use the two together, in combination with a proper ``MANIFEST.in`` file, releasing a source distribution with compiled ``.mo`` files is made easy.
The ``release`` (or ``fullrelease``) command of ``zest.releaser`` creates a (git or other) tag and checks out this tag.
Then it creates a source distribution (``sdist``) and possibly a wheel (``bdist_wheel``) and uploads it to PyPI.
When ``zest.pocompile`` is added to the mix, it compiles the ``.po`` files immediately after checking out the tag.
This is right in time for creating the distributions, which should now contain the ``.mo`` files.
You may want the full release to fail early when ``zest.pocompile`` is not available.
Since version 1.6.0 this is possible by editing the ``setup.cfg`` of the package where you want this, and add the following section::
[zest.releaser]
prereleaser.before =
zest.pocompile.available
Credits
=======
This package has been cobbled together by Maurits van Rees.
It depends on the `python-gettext <https://pypi.org/project/python-gettext/>`_ package,.
This itself suggests using the `Babel <https://pypi.org/project/Babel/>`_ package.
But it does exactly what we need and its releases are stored on PyPI, so we ignore that suggestion.
The main functions are taken from the ``build_mo`` command of `collective.releaser <https://pypi.org/project/collective.releaser/>`_.
Thanks!
To Do
=====
- Add tests.
.. _`zest.releaser`: https://pypi.org/project/zest.releaser/
Changelog
=========
2.0.0 (2023-09-11)
------------------
- Make final release. Nothing changed since the last alpha. [maurits]
2.0.0a1 (2023-07-13)
--------------------
- Require Python 3.8+ and switch to native namespace packages.
This is needed because ``zest.releaser`` 9.0.0a1 does the same.
[maurits]
1.6.0 (2022-09-13)
------------------
- Add ``zest.pocompile.available``.
You can use this to let the full release of a package fail early when ``zest.pocompile`` is not available.
Edit its ``setup.cfg``, and add a ``[zest.releaser]`` section with value
``prereleaser.before = zest.pocompile.available``
[maurits]
1.5.0 (2020-01-29)
------------------
- Claim Python 2 and 3 compatibility.
Seems to work fine.
[maurits]
1.4 (2013-07-05)
----------------
- Moved to https://github.com/zestsoftware/zest.pocompile.
[maurits]
1.3 (2011-12-16)
----------------
- Fixed the example MANIFEST.in.
[maurits]
1.2 (2011-12-16)
----------------
- Added a larger example of a MANIFEST.in file in the readme. Also
add a MANIFEST.in in zest.pocompile itself, so the CHANGES.txt is
included in the source distribution.
[maurits]
1.1 (2011-12-15)
----------------
- Look for ``.po`` files in any ``LC_MESSAGES`` directory. It no
longer matters if this is contained in a language directory within a
``locales`` or ``locale`` directory, as they could also have names
like ``plonelocales`` or ``locales_for_version_2_only``. Note that
in Plone ``.po`` files can also be in an i18n directory, but those
should not be compiled; this does not have a ``LC_MESSAGES``
directory, so we automatically skip it.
[maurits]
1.0 (2010-10-19)
----------------
- Initial release
Raw data
{
"_id": null,
"home_page": "https://github.com/zestsoftware/zest.pocompile",
"name": "zest.pocompile",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "i18n locales po compile release",
"author": "Maurits van Rees",
"author_email": "m.van.rees@zestsoftware.nl",
"download_url": "https://files.pythonhosted.org/packages/5c/18/f14477e104dcab1795f6c6d594c9b87a47cdeb7d9700928764baaf4b64d6/zest.pocompile-2.0.0.tar.gz",
"platform": null,
"description": "Introduction\n============\n\nThis package compiles po files.\nIt contains a `zest.releaser`_ entrypoint and a stand-alone command line tool.\n\n\nGoal\n====\n\nYou want to release a package that has a ``locales`` dir\n(or ``locale``, or something else as long as it has a ``LC_MESSAGES`` folder somewhere in it)\nwith translations in ``.po`` files.\nYou want to include the compiled ``.mo`` files in your release as well,\nbut you do not want to keep those in a revision control system (like git) as they are binary and can be easily recreated.\nThat is good.\nThis package helps with that.\n\n\nWant ``.mo`` files? Add a ``MANIFEST.in`` file.\n================================================\n\nWhen you use ``python setup.py sdist`` to create a source distribution, Python does *not* automatically include all files.\nIt might look at the information of the revision control system (RCS), but that may or may not work.\nThis depends on your RCS, your Python version, setuptools, or extra packages like ``setuptools-git``.\n\nSince the compiled ``.mo`` files are best not stored in git (or any other RCS), you need to give a hint on which files to include.\nYou do this by adding a ``MANIFEST.in`` file.\nLet's say your package has roughly these contents (not all files are shown)::\n\n your.package/setup.py\n your.package/your/package/locales/nl/LC_MESSAGES/domain.po\n\nThen you need a ``MANIFEST.in`` file like this::\n\n recursive-include your *\n\nOr with a bigger example::\n\n recursive-include your *\n recursive-include docs *\n include *\n global-exclude *.pyc\n\nI will explain the lines one by one for clarity.\nAnd yes: I (Maurits) now simply go to this page on PyPI if I want to have an example of a proper ``MANIFEST.in`` file.\nSo this documentation is now getting slightly larger than strictly needed. :-)\n\n``recursive-include your *``\n This tells distutils to recursively include all (``*``) files and directories within the ``your`` directory.\n Try it: create a directory structure like the above example with a proper ``setup.py``,\n copy the ``domain.po`` file to ``domain.mo`` as a silly test,\n run ``python setup.py sdist``\n and check that the ``.mo`` file ends up in the created distribution.\n\n``recursive-include docs *``\n Include files in the ``docs`` directory.\n If this directory does not exist, you will get a warning, so you may want to remove it then, but leaving it there does not hurt.\n\n``include *``\n Include unrecognized files in the root directory.\n Oterwise by default only standard files like ``README.txt``, ``setup.py``, and ``setup.cfg`` are included.\n So for example a ``CHANGES.txt`` file must be explicitly included (here with ``*``).\n\n``global-exclude *.pyc``\n This avoids unnecessarily adding compiled python files in the release.\n When these are not there, for example after a fresh checkout, you will get a harmless warning: ``no previously-included files matching '*.pyc' found anywhere in distribution``.\n\nFor more info on creating a source distribution and how to use ``MANIFEST.in`` see the `Python distutils documentation <http://docs.python.org/distutils/sourcedist.html>`_\nor the `setuptools documentation <https://setuptools.readthedocs.io/en/latest/setuptools.html>`_.\n\nWith this part working, the only thing this ``zest.pocompile`` package needs to do, is to actually find all ``.po`` files and compile them to ``.mo`` files.\nIt simply looks for directories that are named ``LC_MESSAGES`` and compiles all ``.po`` files found in there.\n\n\nCommand line tool\n=================\n\nWhen you ``pip install zest.pocompile`` you get a command line tool ``pocompile``.\nWhen you run it, this walks the current directory, finds all po translation files in a properly formed locales directory, and compiles them into ``.mo`` files.\nYou can also give it a list of directories as arguments instead.\nRun it with the ``--help`` option to get some help.\n\nIn the above example, if you are in the ``your.package`` directory and run ``pocompile`` it will create this file::\n\n your.package/your/package/locales/nl/LC_MESSAGES/domain.mo\n\n\nzest.releaser entry point\n=========================\n\nYou do not need `zest.releaser`_ for a proper functioning of ``zest.pocompile``.\nBut if you use the two together, in combination with a proper ``MANIFEST.in`` file, releasing a source distribution with compiled ``.mo`` files is made easy.\n\nThe ``release`` (or ``fullrelease``) command of ``zest.releaser`` creates a (git or other) tag and checks out this tag.\nThen it creates a source distribution (``sdist``) and possibly a wheel (``bdist_wheel``) and uploads it to PyPI.\nWhen ``zest.pocompile`` is added to the mix, it compiles the ``.po`` files immediately after checking out the tag.\nThis is right in time for creating the distributions, which should now contain the ``.mo`` files.\n\nYou may want the full release to fail early when ``zest.pocompile`` is not available.\nSince version 1.6.0 this is possible by editing the ``setup.cfg`` of the package where you want this, and add the following section::\n\n [zest.releaser]\n prereleaser.before =\n zest.pocompile.available\n\n\nCredits\n=======\n\nThis package has been cobbled together by Maurits van Rees.\n\nIt depends on the `python-gettext <https://pypi.org/project/python-gettext/>`_ package,.\nThis itself suggests using the `Babel <https://pypi.org/project/Babel/>`_ package.\nBut it does exactly what we need and its releases are stored on PyPI, so we ignore that suggestion.\n\nThe main functions are taken from the ``build_mo`` command of `collective.releaser <https://pypi.org/project/collective.releaser/>`_.\n\nThanks!\n\n\nTo Do\n=====\n\n- Add tests.\n\n\n.. _`zest.releaser`: https://pypi.org/project/zest.releaser/\n\nChangelog\n=========\n\n2.0.0 (2023-09-11)\n------------------\n\n- Make final release. Nothing changed since the last alpha. [maurits]\n\n\n2.0.0a1 (2023-07-13)\n--------------------\n\n- Require Python 3.8+ and switch to native namespace packages.\n This is needed because ``zest.releaser`` 9.0.0a1 does the same.\n [maurits]\n\n\n1.6.0 (2022-09-13)\n------------------\n\n- Add ``zest.pocompile.available``.\n You can use this to let the full release of a package fail early when ``zest.pocompile`` is not available.\n Edit its ``setup.cfg``, and add a ``[zest.releaser]`` section with value\n ``prereleaser.before = zest.pocompile.available``\n [maurits]\n\n\n1.5.0 (2020-01-29)\n------------------\n\n- Claim Python 2 and 3 compatibility.\n Seems to work fine.\n [maurits]\n\n\n1.4 (2013-07-05)\n----------------\n\n- Moved to https://github.com/zestsoftware/zest.pocompile.\n [maurits]\n\n\n1.3 (2011-12-16)\n----------------\n\n- Fixed the example MANIFEST.in.\n [maurits]\n\n\n1.2 (2011-12-16)\n----------------\n\n- Added a larger example of a MANIFEST.in file in the readme. Also\n add a MANIFEST.in in zest.pocompile itself, so the CHANGES.txt is\n included in the source distribution.\n [maurits]\n\n\n1.1 (2011-12-15)\n----------------\n\n- Look for ``.po`` files in any ``LC_MESSAGES`` directory. It no\n longer matters if this is contained in a language directory within a\n ``locales`` or ``locale`` directory, as they could also have names\n like ``plonelocales`` or ``locales_for_version_2_only``. Note that\n in Plone ``.po`` files can also be in an i18n directory, but those\n should not be compiled; this does not have a ``LC_MESSAGES``\n directory, so we automatically skip it.\n [maurits]\n\n\n1.0 (2010-10-19)\n----------------\n\n- Initial release\n\n",
"bugtrack_url": null,
"license": "GPL",
"summary": "Compile po files when releasing a package",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/zestsoftware/zest.pocompile"
},
"split_keywords": [
"i18n",
"locales",
"po",
"compile",
"release"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b3c585e1c4ec19bcfc0cf7196dc9e9008ef3687739c4062e38cdcd8c84e82698",
"md5": "15fdc3b2a9e9a96e1e0ce6ed86a18c80",
"sha256": "e315cbbe2880fe96953306319da048b4ee349de3cf05a34064abf140f26d4b79"
},
"downloads": -1,
"filename": "zest.pocompile-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "15fdc3b2a9e9a96e1e0ce6ed86a18c80",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6358,
"upload_time": "2023-09-11T09:13:00",
"upload_time_iso_8601": "2023-09-11T09:13:00.548081Z",
"url": "https://files.pythonhosted.org/packages/b3/c5/85e1c4ec19bcfc0cf7196dc9e9008ef3687739c4062e38cdcd8c84e82698/zest.pocompile-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5c18f14477e104dcab1795f6c6d594c9b87a47cdeb7d9700928764baaf4b64d6",
"md5": "bca43bf9675ff95e76a355dc94d82b16",
"sha256": "4a531e1dc14e9fc04a8c349ad29b719c83449ba39f666137520de7737e2321b1"
},
"downloads": -1,
"filename": "zest.pocompile-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "bca43bf9675ff95e76a355dc94d82b16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7040,
"upload_time": "2023-09-11T09:13:02",
"upload_time_iso_8601": "2023-09-11T09:13:02.033999Z",
"url": "https://files.pythonhosted.org/packages/5c/18/f14477e104dcab1795f6c6d594c9b87a47cdeb7d9700928764baaf4b64d6/zest.pocompile-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-11 09:13:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zestsoftware",
"github_project": "zest.pocompile",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "zest.pocompile"
}
JSON
