Package: ansys-tools-protoc-helper
A utility to compile.protofiles to Python source when building the package wheel. It supports dependencies to.protofiles of different packages.QuickstartThe simplest way to get started is using thetemplate repository.Manual useTo manually enable the use ofansys-tools-protoc-helperin your project, the following things need to be defined:Apyproject.tomlfile with the following contents:[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.protofiles.In thesetuptoolsconfiguration (eithersetup.cfgorsetup.py). We only show thesetuptools.setup()keywords (setup.pyvariant) here:Run-time dependencies on the same<additional_dependencies>used above:install_requires=[grpcio,protobuf,<additional_dependencies>],Refer to thegRPC version strategysection for details on whichgrpcandprotobufversions can be used.Thepackage_datadeclares additional file names which are included in the package:package_data={"":["*.proto","*.pyi","py.typed"],}Note that*.protois only needed if other packages should be able to depend on the*.protofiles defined in your package.Thepy.typedfile is used to communicate that the package contains type information, seePEP 561. This file needs to be manually added.Thecmdclassis used to specify that somesetuptoolscommands should be executed byansys-tools-protoc-helper:fromansys.tools.protoc_helperimportCMDCLASS_OVERRIDEsetup(<...>,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 thesetup.cfgformat:fromansys.tools.protoc_helperimportBuildPyCommand,DevelopCommandsetup(<...>,cmdclass={"build_py":BuildPyCommand,"develop":DevelopCommand})If other projects should be able to depend on the.protofiles contained in your project, anentry pointneeds to be defined declaring the presence of the*.protofiles: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.protofiles will be copied toyour/package/name. If a different location should be used, append a semicolon to the entry point name, followed by the dot-separated target location:entry_points={"ansys.tools.protoc_helper.proto_provider":{"<your.package.name>:<target.location>=<your.package.name>"},},For a complete example, see thetest/test_data/testpkg-greeter-protospackage.gRPC version strategyTheansys-tools-protoc-helperpins the versions ofgRPCandprotobufthat it depends on, in thedependencies = ...section of thepyproject.tomlfile.For your own project, you can use any version ofgrpcioandprotobufthat’s newer (or equal) to the version pinned here, as long as it is the same major version.For example, ifansys-tools-protoc-helperpinsdependencies = [
    "grpcio-tools==1.20.0",
    "protobuf==3.19.3",
]your own dependencies could begrpcio-tools~=1.20,protobuf~=3.19(using the~=compatible version operator).NoteTheprotoccompiler version used is determined by thegrpcio-toolspackage,nottheprotobufdependency. Thegrpcio-tools==1.20.0usesprotoc==3.7.0.The versions pinned byansys-tools-protoc-helperwere originally chosen as follows:The first version ofgrpcio-toolsfor which binary wheels are available on PyPI, for at least one of the Python versions we support.The first version ofprotobufwhich is compatible withmypy-protobuf, for generating type stubs.Upgrade plansThe current plan for upgradinggrpcio-toolsandprotobufis as follows:ansys-tools-protoc-helperversionrelease dategrpcio-toolsversionprotobufversionprotocversion0.2.x2022-12-091.20.x3.19.33.7.x0.3.x2023-02-201.25.x3.19.33.8.x0.4.x2023-02-201.44.x3.19.33.19.20.5.xTBD1.49.x4.21.x3.21.5The strategy for these upgrades is as follows:
- Upgradegrpcio-toolsas necessary. For example,0.5.xenables building with Python3.11.
- Match the version ofprotobufto the version ofprotocbundled intogrpcio-tools, or at least3.19.3.
- Each upgrade is a breaking upgrade for the semantic version. Since we are currently using0.xversions, the minor version is bumped.TheprotobufPython runtime introduced a backwards-incompatible change with version4.21(matching protoc release3.21). Code generated withprotoc==3.19or newer should be compatible with the4.xruntime, which corresponds to the0.4release ofansys-tools-protoc-helper.If you need to support a specificolderversion of protobuf and / or gRPC, we encourage pinningansys-tools-protoc-helperto its minor version.