This repository contains a template for creating gRPC API packages that compile to Python source code.
Using this template, you can create a Python package to generate a Python wheel that exposes the interface files generated from gRPC PROTO files.
Install the resulting package with this command:
pip install ansys-api-<product_name>-<library_name>
where <product_name>
and <library_name>
are the names you can choose
when instantiating the template.
You can then use this package in a "higher-level" Python library.
The directory created by this template is fully compatible with GitHub and can be uploaded to the Ansys-Internal organization.
When making the API package public, a CI step can be enabled to automatically push the Python package to PyPI.
Before using the template, run this command, preferably in a virtual environment, to install package dependencies:
pip install 'cookiecutter~=2.0'
Next, create your repository via ssh with this command:
cookiecutter git+ssh://git@github.com/ansys/ansys-api-template
Optionally, if you prefer https, use this command:
cookiecutter gh:ansys/ansys-api-template
You are then prompted for the following inputs:
-
product_name
: Name of the product for which you are creating an API directory. For example, the product name could beMAPDL
,DPF
, ortools
. -
library_name
: Name of the library for which you are creating an API directory. For example, the library name could becore
,file-transfer
, or an empty string. -
project_name_slug
: Name for the API package. In most cases, the suggested default should work fine. -
api_version
: Version number of the API package. If you're just getting started,0
should be used. -
api_package_version
: Version of the API package. If this is the first release, the default0.1.0
is suitable. -
protos_dir
: Path to a directory that contains the PROTO files to include in the API package. This can be left empty, in which case must manually copy in the PROTO files later.NOTE: The path must be given relative to the root of the package that is to be created. In other words, you should add a leading
../
compared path relative to your working directory, or alternatively use an absolute path. -
proto_dependencies
: Specifies whether your PROTO files depend on another API package. If they are independent, you can accept the default. Otherwise, you must pass dependencies as a JSON dictionary:{"modules": [<your dependencies here>]}
For example, if you depend on the
ansys-api-file-transfer
andansys-api-mapdl
packages, you would pass these dependencies:{"modules": ["ansys-api-tools-file-transfer", "ansys-api-mapdl-core"]}
Once your API repository has been generated, you can initialize a git
repository inside the new directory. Any changes to PROTO files can then be made directly in your repository.
For information on how the compilation of PROTO files works and how compilation can be controlled from the setup.py
and pyproject.toml
files, see the documentation for the ansys-tools-protoc-helper
package.
NOTE: You must not create an __init__.py
file directly in the ansys
or ansys/api
directories. Doing so would make it impossible to use other packages that use the ansys.
or ansys.api
namespace alongside your package. This is because implicit namespace packages are used. For more information, see [PEP 420] - Implicit Namespace Packages (https://www.python.org/dev/peps/pep-0420/).
To build the gRPC packages, run these commands:
pip install build
python -m build
The preceding commands create both the source distribution containing only the PROTO files and the wheel containing the PROTO files and build Python interface files.
Note that the interface files are identical regardless of the version of Python
used to generate them, but the last pre-built wheel for grpcio~=1.17
was
Python 3.7. To improve your build time, use Python 3.7 when building the
wheel.
After building the packages, manually deploy them with these commands:
pip install twine
twine upload dist/*
Note that this should be automatically done through CI/CD. See the following section.
The repository generated from this template contains a .github
directory
with the ci.yml
workflow file. This file uses GitHub Actions
to automatically build the packages for the gRPC Python interface files. By
default, these are built on PRs, the main branch, and on tags when
pushing. Artifacts are uploaded for each PR.
It also contains the following (commented out) action:
- name: Upload to Public PyPI
run: |
pip install twine
twine upload --skip-existing ./**/*.whl
twine upload --skip-existing ./**/*.tar.gz
env:
TWINE_USERNAME: __token__
TWINE_PASSWORD: {% raw %}${{ secrets.PYPI_TOKEN }} {%- endraw %}
This action is triggered only when tags are pushed. It is commented out to avoid
inadvertently pushing wheels to public PyPI. Once you uncomment this section,
you can deploy to PyPI. For example, to push tags for version
v0.5.0
, you would use these commands:
git tag v0.5.0
git push --tags
NOTE: The preceding upload action uses the organizational secret. Be sure to replace it with a project-specific token.