| Name | ansys-tools-protoc-helper JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | None |
| Summary | A utility for compiling '.proto' files to Python source. |
| upload_time | 2024-09-02 10:12:24 |
| maintainer | None |
| docs_url | None |
| author | ANSYS, Inc. |
| requires_python | <3.12,>=3.9 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
***************************
protobuf compilation helper
***************************
A utility to compile ``.proto`` files to Python source when building the package wheel. It supports dependencies to ``.proto`` files of different packages.
Quickstart
~~~~~~~~~~
The simplest way to get started is using the `template repository <https://github.com/ansys/ansys-api-template>`_.
Manual use
~~~~~~~~~~
To manually enable the use of ``ansys-tools-protoc-helper`` in your project, the following things need to be defined:
- A ``pyproject.toml`` file with the following contents:
.. code::
[build-system]
requires = ["setuptools>=42.0", "wheel", "ansys-tools-protoc-helper", <additional_dependencies>]
build-backend = "setuptools.build_meta:__legacy__"
where ``<additional_dependencies>`` are the packages that you depend on for ``.proto`` files.
- In the ``setuptools`` configuration (either ``setup.cfg`` or ``setup.py``). We only show the ``setuptools.setup()`` keywords (``setup.py`` variant) here:
- Run-time dependencies on the same ``<additional_dependencies>`` used above:
.. code:: python
install_requires=[grpcio, protobuf, <additional_dependencies>],
Refer to the `gRPC version strategy`_ section for details on which ``grpc`` and ``protobuf`` versions can be used.
- The ``package_data`` declares additional file names which are included in the package:
.. code:: python
package_data={
"": ["*.proto", "*.pyi", "py.typed"],
}
Note that ``*.proto`` is only needed if other packages should be able to depend on the ``*.proto`` files defined in your package.
The ``py.typed`` file is used to communicate that the package contains type information, see `PEP 561 <https://www.python.org/dev/peps/pep-0561/>`_. This file needs to be manually added.
- The ``cmdclass`` is used to specify that some ``setuptools`` commands should be executed by ``ansys-tools-protoc-helper``:
.. code:: python
from ansys.tools.protoc_helper import CMDCLASS_OVERRIDE
setup(
<...>,
cmdclass=CMDCLASS_OVERRIDE
)
The two commands which are overridden can also be specified individually. This may be useful in particular if you want to use the ``setup.cfg`` format:
.. code:: python
from ansys.tools.protoc_helper import BuildPyCommand, DevelopCommand
setup(
<...>,
cmdclass={"build_py": BuildPyCommand, "develop": DevelopCommand}
)
- If other projects should be able to depend on the ``.proto`` files contained in your project, an `entry point <https://packaging.python.org/en/latest/specifications/entry-points/>`_ needs to be defined declaring the presence of the ``*.proto`` files:
.. code:: python
entry_points={
"ansys.tools.protoc_helper.proto_provider": {
"<your.package.name>=<your.package.name>"
},
},
where ``<your.package.name>`` is the _importable_ name of your package. In other words, ``import <your.package.name>`` should work after installing the package.
By default, the ``.proto`` files will be copied to ``your/package/name``. If a different location should be used, append a semicolon to the entry point name, followed by the dot-separated target location:
.. code:: python
entry_points={
"ansys.tools.protoc_helper.proto_provider": {
"<your.package.name>:<target.location>=<your.package.name>"
},
},
For a complete example, see the ``test/test_data/testpkg-greeter-protos`` package.
gRPC version strategy
~~~~~~~~~~~~~~~~~~~~~
The ``ansys-tools-protoc-helper`` pins the versions of ``gRPC`` and ``protobuf`` that it depends on, in the ``dependencies = ...`` section of the `pyproject.toml <https://github.com/ansys/ansys-tools-protoc-helper/blob/main/pyproject.toml>`_ file.
For your own project, you can use any version of ``grpcio`` and ``protobuf`` that's newer (or equal) to the version pinned here, as long as it is the same major version.
For example, if ``ansys-tools-protoc-helper`` pins
.. code::
dependencies = [
"grpcio-tools==1.20.0",
"protobuf==3.19.3",
]
your own dependencies could be ``grpcio-tools~=1.20``, ``protobuf~=3.19`` (using the ``~=`` `compatible version operator <https://www.python.org/dev/peps/pep-0440/#compatible-release>`_).
.. note::
The ``protoc`` compiler version used is determined by the ``grpcio-tools`` package, *not* the ``protobuf`` dependency. The ``grpcio-tools==1.20.0`` uses ``protoc==3.7.0``.
The versions pinned by ``ansys-tools-protoc-helper`` were originally chosen as follows:
- The first version of ``grpcio-tools`` for which binary wheels are available on PyPI, for at least one of the Python versions we support.
- The first version of ``protobuf`` which is compatible with ``mypy-protobuf``, for generating type stubs.
Upgrade plans
^^^^^^^^^^^^^
The current plan for upgrading ``grpcio-tools`` and ``protobuf`` is as follows:
+----------------------------------------+----------------+--------------------------+----------------------+--------------------+
| ``ansys-tools-protoc-helper`` version | release date | ``grpcio-tools`` version | ``protobuf`` version | ``protoc`` version |
+========================================+================+==========================+======================+====================+
| ``0.2.x`` | 2022-12-09 | ``1.20.x`` | ``3.19.3`` | ``3.7.x`` |
+----------------------------------------+----------------+--------------------------+----------------------+--------------------+
| ``0.3.x`` | 2023-02-20 | ``1.25.x`` | ``3.19.3`` | ``3.8.x`` |
+----------------------------------------+----------------+--------------------------+----------------------+--------------------+
| ``0.4.x`` | 2023-02-20 | ``1.44.x`` | ``3.19.3`` | ``3.19.2`` |
+----------------------------------------+----------------+--------------------------+----------------------+--------------------+
| ``0.5.x`` | TBD | ``1.49.x`` | ``4.21.x`` | ``3.21.5`` |
+----------------------------------------+----------------+--------------------------+----------------------+--------------------+
The strategy for these upgrades is as follows:
- Upgrade ``grpcio-tools`` as necessary. For example, ``0.5.x`` enables building with Python ``3.11``.
- Match the version of ``protobuf`` to the version of ``protoc`` bundled into ``grpcio-tools``, or at least ``3.19.3``.
- Each upgrade is a breaking upgrade for the semantic version. Since we are currently using ``0.x`` versions, the minor version is bumped.
The ``protobuf`` Python runtime introduced a backwards-incompatible change with version ``4.21`` (matching protoc release ``3.21``). Code generated with ``protoc==3.19`` or newer should be compatible with the ``4.x`` runtime, which corresponds to the ``0.4`` release of ``ansys-tools-protoc-helper``.
If you need to support a specific *older* version of protobuf and / or gRPC, we encourage pinning ``ansys-tools-protoc-helper`` to its minor version.
Raw data
{
"_id": null,
"home_page": null,
"name": "ansys-tools-protoc-helper",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.9",
"maintainer_email": "PyAnsys developers <pyansys.support@ansys.com>",
"keywords": null,
"author": "ANSYS, Inc.",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4a/c5/3acd5f8953333cb43376e1c6eaf4277224dd5f12682537ff3b438df03f8d/ansys_tools_protoc_helper-0.5.0.tar.gz",
"platform": null,
"description": "***************************\nprotobuf compilation helper\n***************************\n\nA utility to compile ``.proto`` files to Python source when building the package wheel. It supports dependencies to ``.proto`` files of different packages.\n\nQuickstart\n~~~~~~~~~~\n\nThe simplest way to get started is using the `template repository <https://github.com/ansys/ansys-api-template>`_.\n\nManual use\n~~~~~~~~~~\n\nTo manually enable the use of ``ansys-tools-protoc-helper`` in your project, the following things need to be defined:\n\n- A ``pyproject.toml`` file with the following contents:\n\n .. code::\n\n [build-system]\n requires = [\"setuptools>=42.0\", \"wheel\", \"ansys-tools-protoc-helper\", <additional_dependencies>]\n build-backend = \"setuptools.build_meta:__legacy__\"\n\n where ``<additional_dependencies>`` are the packages that you depend on for ``.proto`` files.\n\n- In the ``setuptools`` configuration (either ``setup.cfg`` or ``setup.py``). We only show the ``setuptools.setup()`` keywords (``setup.py`` variant) here:\n\n - Run-time dependencies on the same ``<additional_dependencies>`` used above:\n\n .. code:: python\n\n install_requires=[grpcio, protobuf, <additional_dependencies>],\n\n Refer to the `gRPC version strategy`_ section for details on which ``grpc`` and ``protobuf`` versions can be used.\n\n - The ``package_data`` declares additional file names which are included in the package:\n\n .. code:: python\n\n package_data={\n \"\": [\"*.proto\", \"*.pyi\", \"py.typed\"],\n }\n\n Note that ``*.proto`` is only needed if other packages should be able to depend on the ``*.proto`` files defined in your package.\n\n The ``py.typed`` file is used to communicate that the package contains type information, see `PEP 561 <https://www.python.org/dev/peps/pep-0561/>`_. This file needs to be manually added.\n\n - The ``cmdclass`` is used to specify that some ``setuptools`` commands should be executed by ``ansys-tools-protoc-helper``:\n\n .. code:: python\n\n from ansys.tools.protoc_helper import CMDCLASS_OVERRIDE\n\n setup(\n <...>,\n cmdclass=CMDCLASS_OVERRIDE\n )\n\n The two commands which are overridden can also be specified individually. This may be useful in particular if you want to use the ``setup.cfg`` format:\n\n .. code:: python\n\n from ansys.tools.protoc_helper import BuildPyCommand, DevelopCommand\n\n setup(\n <...>,\n cmdclass={\"build_py\": BuildPyCommand, \"develop\": DevelopCommand}\n )\n\n - If other projects should be able to depend on the ``.proto`` files contained in your project, an `entry point <https://packaging.python.org/en/latest/specifications/entry-points/>`_ needs to be defined declaring the presence of the ``*.proto`` files:\n\n .. code:: python\n\n entry_points={\n \"ansys.tools.protoc_helper.proto_provider\": {\n \"<your.package.name>=<your.package.name>\"\n },\n },\n\n where ``<your.package.name>`` is the _importable_ name of your package. In other words, ``import <your.package.name>`` should work after installing the package.\n\n By default, the ``.proto`` files will be copied to ``your/package/name``. If a different location should be used, append a semicolon to the entry point name, followed by the dot-separated target location:\n\n .. code:: python\n\n entry_points={\n \"ansys.tools.protoc_helper.proto_provider\": {\n \"<your.package.name>:<target.location>=<your.package.name>\"\n },\n },\n\nFor a complete example, see the ``test/test_data/testpkg-greeter-protos`` package.\n\ngRPC version strategy\n~~~~~~~~~~~~~~~~~~~~~\n\nThe ``ansys-tools-protoc-helper`` pins the versions of ``gRPC`` and ``protobuf`` that it depends on, in the ``dependencies = ...`` section of the `pyproject.toml <https://github.com/ansys/ansys-tools-protoc-helper/blob/main/pyproject.toml>`_ file.\n\nFor your own project, you can use any version of ``grpcio`` and ``protobuf`` that's newer (or equal) to the version pinned here, as long as it is the same major version.\n\nFor example, if ``ansys-tools-protoc-helper`` pins\n\n.. code::\n\n dependencies = [\n \"grpcio-tools==1.20.0\",\n \"protobuf==3.19.3\",\n ]\n\nyour own dependencies could be ``grpcio-tools~=1.20``, ``protobuf~=3.19`` (using the ``~=`` `compatible version operator <https://www.python.org/dev/peps/pep-0440/#compatible-release>`_).\n\n.. note::\n\n The ``protoc`` compiler version used is determined by the ``grpcio-tools`` package, *not* the ``protobuf`` dependency. The ``grpcio-tools==1.20.0`` uses ``protoc==3.7.0``.\n\n\nThe versions pinned by ``ansys-tools-protoc-helper`` were originally chosen as follows:\n\n- The first version of ``grpcio-tools`` for which binary wheels are available on PyPI, for at least one of the Python versions we support.\n- The first version of ``protobuf`` which is compatible with ``mypy-protobuf``, for generating type stubs.\n\nUpgrade plans\n^^^^^^^^^^^^^\n\nThe current plan for upgrading ``grpcio-tools`` and ``protobuf`` is as follows:\n\n+----------------------------------------+----------------+--------------------------+----------------------+--------------------+\n| ``ansys-tools-protoc-helper`` version | release date | ``grpcio-tools`` version | ``protobuf`` version | ``protoc`` version |\n+========================================+================+==========================+======================+====================+\n| ``0.2.x`` | 2022-12-09 | ``1.20.x`` | ``3.19.3`` | ``3.7.x`` |\n+----------------------------------------+----------------+--------------------------+----------------------+--------------------+\n| ``0.3.x`` | 2023-02-20 | ``1.25.x`` | ``3.19.3`` | ``3.8.x`` |\n+----------------------------------------+----------------+--------------------------+----------------------+--------------------+\n| ``0.4.x`` | 2023-02-20 | ``1.44.x`` | ``3.19.3`` | ``3.19.2`` |\n+----------------------------------------+----------------+--------------------------+----------------------+--------------------+\n| ``0.5.x`` | TBD | ``1.49.x`` | ``4.21.x`` | ``3.21.5`` |\n+----------------------------------------+----------------+--------------------------+----------------------+--------------------+\n\nThe strategy for these upgrades is as follows:\n\n- Upgrade ``grpcio-tools`` as necessary. For example, ``0.5.x`` enables building with Python ``3.11``.\n- Match the version of ``protobuf`` to the version of ``protoc`` bundled into ``grpcio-tools``, or at least ``3.19.3``.\n- Each upgrade is a breaking upgrade for the semantic version. Since we are currently using ``0.x`` versions, the minor version is bumped.\n\nThe ``protobuf`` Python runtime introduced a backwards-incompatible change with version ``4.21`` (matching protoc release ``3.21``). Code generated with ``protoc==3.19`` or newer should be compatible with the ``4.x`` runtime, which corresponds to the ``0.4`` release of ``ansys-tools-protoc-helper``.\n\nIf you need to support a specific *older* version of protobuf and / or gRPC, we encourage pinning ``ansys-tools-protoc-helper`` to its minor version.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A utility for compiling '.proto' files to Python source.",
"version": "0.5.0",
"project_urls": {
"Source": "https://github.com/ansys/ansys-tools-protoc-helper"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ed94899aaa75784659eb95a4aa923cfe99358f877572a24039f69e182979e13b",
"md5": "33866bc3d3c1e18da2761b13f5dc7321",
"sha256": "852a0118a5a6e521ea2148cc10617136d321bc88376b4496ef12e4e94266ac66"
},
"downloads": -1,
"filename": "ansys_tools_protoc_helper-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "33866bc3d3c1e18da2761b13f5dc7321",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.9",
"size": 7537,
"upload_time": "2024-09-02T10:12:22",
"upload_time_iso_8601": "2024-09-02T10:12:22.691676Z",
"url": "https://files.pythonhosted.org/packages/ed/94/899aaa75784659eb95a4aa923cfe99358f877572a24039f69e182979e13b/ansys_tools_protoc_helper-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4ac53acd5f8953333cb43376e1c6eaf4277224dd5f12682537ff3b438df03f8d",
"md5": "112c3c82b2373a49fcad7b8f4d8d3c9e",
"sha256": "3af6b5d78e1edd389890b54fed4f3fd3e0862463366a2e3bc4e2b2dffbb6158f"
},
"downloads": -1,
"filename": "ansys_tools_protoc_helper-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "112c3c82b2373a49fcad7b8f4d8d3c9e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.9",
"size": 6048,
"upload_time": "2024-09-02T10:12:24",
"upload_time_iso_8601": "2024-09-02T10:12:24.419106Z",
"url": "https://files.pythonhosted.org/packages/4a/c5/3acd5f8953333cb43376e1c6eaf4277224dd5f12682537ff3b438df03f8d/ansys_tools_protoc_helper-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-02 10:12:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ansys",
"github_project": "ansys-tools-protoc-helper",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ansys-tools-protoc-helper"
}
