https://github.com/ansys/ansys-api-template
Template repository for gRPC API definitions
https://github.com/ansys/ansys-api-template
Last synced: 2 months ago
JSON representation
Template repository for gRPC API definitions
- Host: GitHub
- URL: https://github.com/ansys/ansys-api-template
- Owner: ansys
- License: mit
- Created: 2022-01-28T12:12:19.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-08-04T06:37:57.000Z (almost 2 years ago)
- Last Synced: 2025-01-25T20:42:44.786Z (4 months ago)
- Language: Python
- Size: 43 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Ansys API Template
This repository contains a template for creating gRPC API packages that compile to Python source code.
## Expected usage
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:
```bash
pip install ansys-api--
```
where ```` and ```` 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](https://github.com/ansys-internal) organization.
When making the API package public, a CI step can be enabled to automatically push
the Python package to PyPI.
## Installation and usage
Before using the template, run this command, preferably in a virtual environment, to install
package dependencies:
```bash
pip install 'cookiecutter~=2.0'
```
Next, create your repository via ssh with this command:
```bash
cookiecutter git+ssh://[email protected]/ansys/ansys-api-template
```
Optionally, if you prefer https, use this command:
```bash
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 be ``MAPDL``, ``DPF``, or ``tools``.
* `library_name`: Name of the library for which you are creating an API directory. For example, the library name could be ``core``, ``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 default ``0.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:
```json
{"modules": []}
```
For example, if you depend on the ``ansys-api-file-transfer`` and ``ansys-api-mapdl`` packages, you
would pass these dependencies:
```json
{"modules": ["ansys-api-tools-file-transfer", "ansys-api-mapdl-core"]}
```
## Maintaining your API repository
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](https://ansys.github.io/ansys-tools-protoc-helper/) 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/).
## Build packages
To build the gRPC packages, run these commands:
```bash
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.
#### Manual deployment
After building the packages, manually deploy them with these commands:
```bash
pip install twine
twine upload dist/*
```
Note that this should be automatically done through CI/CD. See the following section.
## Deploying wheels to public PyPI
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](https://pypi.org/). For example, to push tags for version
``v0.5.0``, you would use these commands:
```bash
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.