|pyansys| |python| |pypi| |GH-CI| |MIT| |black| |pre-commit-ci|
.. |pyansys| image:: https://img.shields.io/badge/Py-Ansys-ffc107.svg?labelColor=black&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC
:target: https://docs.pyansys.com/
:alt: PyAnsys
.. |python| image:: https://img.shields.io/pypi/pyversions/ansys-openapi-common?logo=pypi
:target: https://pypi.org/project/ansys-openapi-common/
:alt: Python
.. |pypi| image:: https://img.shields.io/pypi/v/ansys-openapi-common.svg?logo=python&logoColor=white
:target: https://pypi.org/project/ansys-openapi-common
:alt: PyPI
.. |GH-CI| image:: https://github.com/pyansys/openapi-common/actions/workflows/ci_cd.yml/badge.svg
:target: https://github.com/ansys/openapi-common/actions/workflows/ci_cd.yml
:alt: GH-CI
.. |MIT| image:: https://img.shields.io/badge/License-MIT-yellow.svg
:target: https://opensource.org/licenses/MIT
:alt: MIT
.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=flat
:target: https://github.com/psf/black
:alt: Black
.. |pre-commit-ci| image:: https://results.pre-commit.ci/badge/github/ansys/openapi-common/main.svg
:target: https://results.pre-commit.ci/latest/github/ansys/openapi-common/main
:alt: pre-commit.ci status
Overview
--------
OpenAPI-Common is intended for use with the custom code generation
template in the `PyAnsys project <https://github.com/pyansys>`_.
It provides the source code for an authentication-aware
client for OpenAPI client libraries.
OpenAPI-Common supports authentication with Basic, Negotiate, NTLM,
and OpenID Connect. Most features of the underlying requests session
are exposed for use. Some basic configuration is also provided by default.
Installation
------------
Install the ``openapi-common`` repository with this code:
.. code::
pip install ansys-openapi-common
Alternatively, clone and install the repository with this code:
.. code::
git clone https://github.com/pyansys/openapi-common
cd openapi-common
pip install .
Usage
-----
The API client class is intended to be wrapped by code that implements a client library.
You should override the ``__init__()`` or ``connect()`` method to add any
additional behavior that might be required.
Authentication is configured through the ``ApiClientFactory`` object and its ``with_xxx()``
methods. If no authentication is required, you can use the ``with_anonymous()`` method.
You can provide additional configuration with the ``SessionConfiguration`` object.
.. code:: python
>>> from ansys.openapi.common import ApiClientFactory
>>> session = ApiClientFactory('https://my-api.com/v1.svc')
... .with_autologon()
... .connect()
<ApiClient url: https://my-api.com/v1.svc>
Authentication schemes
----------------------
OpenAPI-Common supports API servers configured with no authentication, API keys,
client certificates, and basic authentication schemes.
Windows users can also use Windows Integrated Authentication to connect to Kerberos-enabled
APIs with their Windows credentials and to NTLM where it is supported.
Linux users can make use of Kerberos authentication via the ``[linux-kerberos]`` extra. This
requires a working installation of either MIT Kerberos or Heimdal, as well as some
platform-specific build steps. An additional requirement is a correctly configured ``krb5.keytab``
file on your system.
Windows and Linux users can authenticate with OIDC-enabled APIs by using the ``[oidc]`` extra.
Currently only the Authorization Code authentication flow is supported.
.. list-table:: Authentication methods by platform
:header-rows: 1
* - Authentication method
- Windows
- Linux
- Builder method
- Additional settings
* - API Key
- ✔️
- ✔️
- ``.with_anonymous()``
- Set the appropriate header in ``api_session_configuration``
* - Client Certificate
- ✔️
- ✔️
- Any
- Provide ``client_cert_path`` and optionally ``client_cert_key`` in ``api_session_configuration``
* - Basic
- ✔️
- ✔️
- ``.with_credentials()``
-
* - NTLM
- ✔️
- ❌
- ``.with_credentials()``
-
* - Kerberos
- ✔️
- ➕ with ``[linux-kerberos]`` extra
- ``.with_autologon()``
-
* - OIDC
- ➕ with ``[oidc]`` extra
- ➕ with ``[oidc]`` extra
- ``.with_oidc()``
-
HTTPS Certificates
~~~~~~~~~~~~~~~~~~
The ``requests`` library uses the ``certifi`` package to verify TLS certificates instead of a local system certificate store.
These means only TLS certificates signed by a public CA can be verified by ``requests`` in its default configuration. If you
need to verify internally-signed TLS certificates, there are two recommended approaches:
pip-system-certs
================
The ``pip-system-certs`` library patches the certificate loading mechanism for ``requests`` causing it to
use your system certificate store. This is the simplest solution, but there are two potential limitations:
1. ``pip-system-certs`` does not support every platform that is supported by CPython, so it may not
be supported on your platform.
2. The change to ``requests`` affects every package in your environment, including pip. Make sure you are
using a virtual environment.
.. note::
If you are using OIDC authentication and your service provides a internally-signed certificate you will need
to use this option.
Custom certificate store
========================
The ``SessionConfiguration`` object allows you to provide a path to a custom CA certificate. If provided, this will be
used to verify the service's TLS certificate instead of the ``certifi`` package.
Platform-specific Kerberos configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Kerberos authentication should be supported wherever the MIT or Heimdal Kerberos client
can be installed. OpenAPI-Common has been tested on the platforms that follow.
If you manage to use it on another platform, consider contributing installation steps for
your platform by making a pull request.
Ubuntu 20.04
============
Ubuntu requires the ``gssapi`` Python module to be built from source. This requires the
Kerberos headers, Python headers for the version of Python that you are using (here we have
installed python3.10 from the deadsnakes ppa), and a supported compiler. (GCC works well.))
You should then be able to install this module with the ``[linux-kerberos]`` extra.
.. code-block:: bash
sudo apt install build-essential python3.10-dev libkrb5-dev
pip install ansys-openapi-common[linux-kerberos]
Once the installation completes, ensure that your ``krb5.conf`` file is set up correctly
for your Kerberos configuration and that you have a valid ``keytab`` file, which is
normally in ``/etc/krb5.keytab``.
License
-------
OpenAPI-Common is provided under the terms of the MIT license. You can find
the license text in the LICENSE file at the root of the repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/ansys/openapi-common",
"name": "ansys-openapi-common",
"maintainer": "ANSYS, Inc.",
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": "pyansys.core@ansys.com",
"keywords": "Ansys, OpenAPI",
"author": "ANSYS, Inc.",
"author_email": "pyansys.core@ansys.com",
"download_url": "https://files.pythonhosted.org/packages/78/59/839692401c222b4de708cdfbb57d663f6bd5f29eae53ae0dc9db8434ea3e/ansys_openapi_common-2.2.0.tar.gz",
"platform": null,
"description": "|pyansys| |python| |pypi| |GH-CI| |MIT| |black| |pre-commit-ci|\n\n.. |pyansys| image:: https://img.shields.io/badge/Py-Ansys-ffc107.svg?labelColor=black&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC\n :target: https://docs.pyansys.com/\n :alt: PyAnsys\n\n.. |python| image:: https://img.shields.io/pypi/pyversions/ansys-openapi-common?logo=pypi\n :target: https://pypi.org/project/ansys-openapi-common/\n :alt: Python\n\n.. |pypi| image:: https://img.shields.io/pypi/v/ansys-openapi-common.svg?logo=python&logoColor=white\n :target: https://pypi.org/project/ansys-openapi-common\n :alt: PyPI\n\n.. |GH-CI| image:: https://github.com/pyansys/openapi-common/actions/workflows/ci_cd.yml/badge.svg\n :target: https://github.com/ansys/openapi-common/actions/workflows/ci_cd.yml\n :alt: GH-CI\n\n.. |MIT| image:: https://img.shields.io/badge/License-MIT-yellow.svg\n :target: https://opensource.org/licenses/MIT\n :alt: MIT\n\n.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=flat\n :target: https://github.com/psf/black\n :alt: Black\n\n.. |pre-commit-ci| image:: https://results.pre-commit.ci/badge/github/ansys/openapi-common/main.svg\n :target: https://results.pre-commit.ci/latest/github/ansys/openapi-common/main\n :alt: pre-commit.ci status\n\n\nOverview\n--------\n\nOpenAPI-Common is intended for use with the custom code generation\ntemplate in the `PyAnsys project <https://github.com/pyansys>`_.\nIt provides the source code for an authentication-aware\nclient for OpenAPI client libraries.\n\nOpenAPI-Common supports authentication with Basic, Negotiate, NTLM,\nand OpenID Connect. Most features of the underlying requests session\nare exposed for use. Some basic configuration is also provided by default.\n\nInstallation\n------------\n\nInstall the ``openapi-common`` repository with this code:\n\n.. code::\n\n pip install ansys-openapi-common\n\nAlternatively, clone and install the repository with this code:\n\n.. code::\n\n git clone https://github.com/pyansys/openapi-common\n cd openapi-common\n pip install .\n\n\nUsage\n-----\n\nThe API client class is intended to be wrapped by code that implements a client library.\nYou should override the ``__init__()`` or ``connect()`` method to add any\nadditional behavior that might be required.\n\nAuthentication is configured through the ``ApiClientFactory`` object and its ``with_xxx()``\nmethods. If no authentication is required, you can use the ``with_anonymous()`` method.\nYou can provide additional configuration with the ``SessionConfiguration`` object.\n\n.. code:: python\n\n >>> from ansys.openapi.common import ApiClientFactory\n >>> session = ApiClientFactory('https://my-api.com/v1.svc')\n ... .with_autologon()\n ... .connect()\n <ApiClient url: https://my-api.com/v1.svc>\n\n\nAuthentication schemes\n----------------------\n\nOpenAPI-Common supports API servers configured with no authentication, API keys,\nclient certificates, and basic authentication schemes.\n\nWindows users can also use Windows Integrated Authentication to connect to Kerberos-enabled\nAPIs with their Windows credentials and to NTLM where it is supported.\n\nLinux users can make use of Kerberos authentication via the ``[linux-kerberos]`` extra. This\nrequires a working installation of either MIT Kerberos or Heimdal, as well as some\nplatform-specific build steps. An additional requirement is a correctly configured ``krb5.keytab``\nfile on your system.\n\nWindows and Linux users can authenticate with OIDC-enabled APIs by using the ``[oidc]`` extra.\nCurrently only the Authorization Code authentication flow is supported.\n\n.. list-table:: Authentication methods by platform\n :header-rows: 1\n\n * - Authentication method\n - Windows\n - Linux\n - Builder method\n - Additional settings\n * - API Key\n - \u2714\ufe0f\n - \u2714\ufe0f\n - ``.with_anonymous()``\n - Set the appropriate header in ``api_session_configuration``\n * - Client Certificate\n - \u2714\ufe0f\n - \u2714\ufe0f\n - Any\n - Provide ``client_cert_path`` and optionally ``client_cert_key`` in ``api_session_configuration``\n * - Basic\n - \u2714\ufe0f\n - \u2714\ufe0f\n - ``.with_credentials()``\n -\n * - NTLM\n - \u2714\ufe0f\n - \u274c\n - ``.with_credentials()``\n -\n * - Kerberos\n - \u2714\ufe0f\n - \u2795 with ``[linux-kerberos]`` extra\n - ``.with_autologon()``\n -\n * - OIDC\n - \u2795 with ``[oidc]`` extra\n - \u2795 with ``[oidc]`` extra\n - ``.with_oidc()``\n -\n\nHTTPS Certificates\n~~~~~~~~~~~~~~~~~~\n\nThe ``requests`` library uses the ``certifi`` package to verify TLS certificates instead of a local system certificate store.\nThese means only TLS certificates signed by a public CA can be verified by ``requests`` in its default configuration. If you\nneed to verify internally-signed TLS certificates, there are two recommended approaches:\n\npip-system-certs\n================\n\nThe ``pip-system-certs`` library patches the certificate loading mechanism for ``requests`` causing it to\nuse your system certificate store. This is the simplest solution, but there are two potential limitations:\n\n1. ``pip-system-certs`` does not support every platform that is supported by CPython, so it may not\nbe supported on your platform.\n\n2. The change to ``requests`` affects every package in your environment, including pip. Make sure you are\nusing a virtual environment.\n\n.. note::\n If you are using OIDC authentication and your service provides a internally-signed certificate you will need\n to use this option.\n\nCustom certificate store\n========================\n\nThe ``SessionConfiguration`` object allows you to provide a path to a custom CA certificate. If provided, this will be\nused to verify the service's TLS certificate instead of the ``certifi`` package.\n\nPlatform-specific Kerberos configuration\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nKerberos authentication should be supported wherever the MIT or Heimdal Kerberos client\ncan be installed. OpenAPI-Common has been tested on the platforms that follow.\nIf you manage to use it on another platform, consider contributing installation steps for\nyour platform by making a pull request.\n\nUbuntu 20.04\n============\n\nUbuntu requires the ``gssapi`` Python module to be built from source. This requires the\nKerberos headers, Python headers for the version of Python that you are using (here we have\ninstalled python3.10 from the deadsnakes ppa), and a supported compiler. (GCC works well.))\n\nYou should then be able to install this module with the ``[linux-kerberos]`` extra.\n\n.. code-block:: bash\n\n sudo apt install build-essential python3.10-dev libkrb5-dev\n pip install ansys-openapi-common[linux-kerberos]\n\n\nOnce the installation completes, ensure that your ``krb5.conf`` file is set up correctly\nfor your Kerberos configuration and that you have a valid ``keytab`` file, which is\nnormally in ``/etc/krb5.keytab``.\n\nLicense\n-------\nOpenAPI-Common is provided under the terms of the MIT license. You can find\nthe license text in the LICENSE file at the root of the repository.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Provides a helper to create sessions for use with Ansys OpenAPI clients.",
"version": "2.2.0",
"project_urls": {
"Documentation": "https://openapi.docs.pyansys.com",
"Homepage": "https://github.com/ansys/openapi-common",
"Repository": "https://github.com/ansys/openapi-common"
},
"split_keywords": [
"ansys",
" openapi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4fb279bb9394f567efcbc668b8feb4e102eefa76092fdccb331f3844b5a18074",
"md5": "b40515b6d825604de5d58a780a112de0",
"sha256": "3b95bd0ee38acd37800179489a451a854d6fe0312a5f0b1182e1407c8ad57e9e"
},
"downloads": -1,
"filename": "ansys_openapi_common-2.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b40515b6d825604de5d58a780a112de0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 36478,
"upload_time": "2024-10-25T08:58:14",
"upload_time_iso_8601": "2024-10-25T08:58:14.735713Z",
"url": "https://files.pythonhosted.org/packages/4f/b2/79bb9394f567efcbc668b8feb4e102eefa76092fdccb331f3844b5a18074/ansys_openapi_common-2.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7859839692401c222b4de708cdfbb57d663f6bd5f29eae53ae0dc9db8434ea3e",
"md5": "99bd406a97338a7f3d91a6e6b14c1793",
"sha256": "176928ec15cfc6690dbb3ba7b806f01046a70b44c898530af390682973282195"
},
"downloads": -1,
"filename": "ansys_openapi_common-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "99bd406a97338a7f3d91a6e6b14c1793",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 30447,
"upload_time": "2024-10-25T08:58:15",
"upload_time_iso_8601": "2024-10-25T08:58:15.815460Z",
"url": "https://files.pythonhosted.org/packages/78/59/839692401c222b4de708cdfbb57d663f6bd5f29eae53ae0dc9db8434ea3e/ansys_openapi_common-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-25 08:58:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ansys",
"github_project": "openapi-common",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ansys-openapi-common"
}
JSON
