PyAnsys Protos Generator Packaging Tool
Project description
This package allows you to automatically generate a python package from proto files stored according to gRPC proto file conventions.
Installation
Install the python packaging tool with:
pip install ansys-tools-protos-generator
Usage
Once installed, this package can be run directly from the command line with:
python -m ansys.tools.protos_generator <directory-containing-protosfiles>
The protos-samples directory contains a simple sample service containing the following directory structure.
─ansys │ ├───api │ │ ├───sample │ │ │ ├───v1 │ │ │ │ ├───sample.proto │ │ │ │ └───VERSION
Running:
python -m ansys.tools.protos_generator ansys/api/sample-example/v1
Will generate the following python package:
dist/ansys-api-sample-v1-0.5.3.tar.gz
This package can then be installed via:
pip install dist/ansys-api-sample-v1-0.5.3.tar.gz
Or uploaded to pypi with:
twine upload dist/ansys-api-sample-v1-0.5.3.tar.gz
Contact alexander.kaszynski@ansys.com for the token and credentials to upload to pypi under the pyansys account.
Non-Default Directory
You can change the default directory to a non-default directory with:
python -m ansys.tools.protos_generator <protosfiles_path> <outdir>
For more details, run:
python -m ansys.tools.protos_generator -h
Run from within Python
You can run this within python with:
from ansys.tools.protos_generator.generator import package_protos
protosfiles_path = 'proto-samples/ansys/api/sample/v1/'
outdir = 'C:/tmp' # or Linux: '/tmp'
dist_file = package_protos(protosfiles_path, outdir)
Ansys gRPC Directory Structure - Standards
In the gRPC proto file naming and directory convention see (gRPC standards), each module is placed in a directory tree that contains the origin of the module. The origin of all modules should be ansys, followed by api, followed by <product/service>.
For example
─ansys │ ├───api │ │ ├───<product/service> │ │ │ ├───v1 │ │ │ │ └───service.proto │ │ │ │ └───other_service.proto │ │ │ │ └───VERSION
This convention follows the gRPC standards except for the VERSION file containing a single semantic version string. Due to the complexity of Ansys services, the vX version cannot be used to fully describe state of the version of the service. For example, if the service were to add a single message to a service, we need a way of tracking that in the version of our auto-generated gRPC interface files and packages. Hence a semantic version.
There are other advantages to having a semantic version, namely that python packages containing the autogenerated gRPC interface files will also have this version. This will give any downstream dependencies the ability to depend on a compatible API. For example, if higher level package requires a certain version of autogenerated gRPC package:
ansys.<product>.<feature>==0.2.0 depends on ansys.api.<product>.v1==0.8.0 ansys.<product>.<feature>==0.3.0 depends on ansys.api.<product>.v1==0.9.0
This way, you can maintain backwards compatibility with various versions of a product for the entire dependency chain without encountering forwards/backwards compatibility issues.
Note that we still use vX. This is required by Google gRPC APIs and affords us the ability to expose two APIs similtaniously from a gRPC service. For example, both a v1 and v2 could be exposed similtaniously from a service, each with their own semantic version to describe the granular state of that API.
This will be handled manually by creating a new directory containing the next version of the API you choose to expose.
─ansys │ ├───api │ │ ├───sample │ │ │ ├───v1 │ │ │ │ ├───sample.proto │ │ │ │ └───VERSION │ │ │ ├───v2 │ │ │ │ ├───sample.proto │ │ │ │ └───VERSION
For all other questions regarding gRPC standards, please reference gRPC Documentation, gRPC Motivation and Design Principles, and API Design Guide.
Development
Run unit testing with:
git clone https://github.com/pyansys/pyansys-protos-generator.git
cd pyansys-protos-generator
pip install -e .
pip install requirements_test.txt
pytest -v
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.
Source Distribution
Hashes for ansys-tools-protos-generator-0.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4e69a03155cd6ab73b80bfb39ab9ae3596ddb74d62a6200ca4272b2678f1818c |
|
MD5 | a76a68ca59a2b0636051511dada77547 |
|
BLAKE2b-256 | de59e68d66d027d68c2e2fd4feb72f5d613605ef282f36ee302b82c46f6ebf14 |