diff --git a/README.rst b/README.rst index f739a9c5..e5723b76 100644 --- a/README.rst +++ b/README.rst @@ -29,161 +29,61 @@ :alt: pre-commit.ci status -Overview --------- +OpenAPI-Common +============== -OpenAPI-Common is intended for use with the custom code generation +.. + _after-badges + +OpenAPI Common is designed for use with the custom code generation template in the `PyAnsys project `_. -It provides the source code for an authentication-aware -client for OpenAPI client libraries. +It provides the source code for an authentication-aware client for +OpenAPI client libraries. + +Background +---------- +A widely used standard for HTTP REST-style APIs is the OpenAPI standard, +formerly known as Swagger. OpenAPI-Common is designed to be used alongside +code generation tools to produce client libraries for HTTP APIs. + +Because some Ansys products expose HTTP APIs rather than gRPC +APIs, this Python library provides a common client to consume +HTTP APIs, minimizing overhead and reducing code duplication. 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 +Dependencies ------------ +.. readme_software_requirements -Install the ``openapi-common`` repository with this code: - -.. code:: - - pip install ansys-openapi-common - -Alternatively, clone and install the repository with this code: +The ``ansys.openapi.common`` package currently supports Python version 3.10 through 3.13. -.. 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() - - - -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. +.. readme_software_requirements_end Platform-specific Kerberos configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. readme_kerberos + 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.)) +Kerberos headers, Python headers for the version of Python that you are using, and a +supported compiler. (GCC works well.) -You should then be able to install this module with the ``[linux-kerberos]`` extra. +You should then be able to install this module with the ``[linux-kerberos]`` extra: -.. code-block:: bash +.. code-block:: sh - sudo apt install build-essential python3.10-dev libkrb5-dev + sudo apt install build-essentials python3.8-dev libkrb5-dev pip install ansys-openapi-common[linux-kerberos] @@ -191,7 +91,38 @@ Once the installation completes, ensure that your ``krb5.conf`` file is set up c 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. +.. readme_kerberos_end + + +Installation +------------ +.. readme_installation + +To install the latest OpenAPI-Common release from `PyPI `_, +run this command: + +.. code:: + + pip install ansys-openapi-common + +Alternatively, to install the latest development version from the `OpenAPI-Common repository `_, +run this command: + +.. code:: + + pip install git+https://github.com/ansys/openapi-common.git + + +To install a local *development* version with Git and Poetry, run these commands: + +.. code:: + + git clone https://github.com/ansys/openapi-common + cd openapi-common + poetry install + + +The preceding commands install the package in development mode so that you can modify +it locally. Your changes are reflected in your Python setup after restarting the Python kernel. + +.. readme_installation_end diff --git a/doc/changelog.d/706.documentation.md b/doc/changelog.d/706.documentation.md new file mode 100644 index 00000000..db9bcb31 --- /dev/null +++ b/doc/changelog.d/706.documentation.md @@ -0,0 +1 @@ +Reorganize documentation \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index 3d2ad8d6..8f2c7e1a 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -32,6 +32,7 @@ "sphinx_copybutton", "sphinx.ext.extlinks", "sphinx.ext.coverage", + "sphinx_design", ] # Sphinx diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst new file mode 100644 index 00000000..254e91f3 --- /dev/null +++ b/doc/source/getting_started/index.rst @@ -0,0 +1,43 @@ +.. _ref_getting_started: + +Getting started +############### + +.. _ref_software_requirements: + +Software requirements +~~~~~~~~~~~~~~~~~~~~~~ +.. include:: ../../../README.rst + :start-after: readme_software_requirements + :end-before: readme_software_requirements_end + + +Installation +~~~~~~~~~~~~ +.. include:: ../../../README.rst + :start-after: readme_installation + :end-before: readme_installation_end + + +Brief example +~~~~~~~~~~~~~ +This brief example demonstrates how the client works: + +.. code:: python + + >>> from ansys.openapi.common import ApiClientFactory + >>> client = ApiClientFactory("https://my-api.com") + ... .with_autologon() + ... .connect() + >>> print(client) + + + + +The client is now ready and available for use with an OpenAPI client. + +Platform-specific Kerberos configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. include:: ../../../README.rst + :start-after: readme_kerberos + :end-before: readme_kerberos_end diff --git a/doc/source/index.rst b/doc/source/index.rst index 1efcf21b..9ef5e1bb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,152 +1,47 @@ OpenAPI-Common |version| ======================== -.. toctree:: - :hidden: - :maxdepth: 3 - - api/index - contributing - - -Introduction ------------- OpenAPI-Common is part of the larger `PyAnsys `_ effort to facilitate the use of Ansys technologies directly from Python. -Because some Ansys products expose HTTP APIs rather than gRPC -APIs, this Python library provides a common client to consume -HTTP APIs, minimizing overhead and reducing code duplication. - - -Background ----------- -A widely used standard for HTTP REST-style APIs is the OpenAPI standard, -formerly known as Swagger. OpenAPI-Common is designed to be used alongside -code generation tools to produce client libraries for HTTP APIs. - - -Brief example -------------- -This brief example demonstrates how the client works: - -.. code:: python - - >>> from ansys.openapi.common import ApiClientFactory - >>> client = ApiClientFactory("https://my-api.com") - ... .with_autologon() - ... .connect() - >>> print(client) - - - - -The client is now ready and available for use with an OpenAPI client. - -Authentication schemes ----------------------- -OpenAPI-Common supports API servers configured with no authentication, API keys, -client certificates, and basic authentication. +.. grid:: 1 2 2 2 -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. + .. grid-item-card:: Getting started :material-regular:`directions_run` + :padding: 2 2 2 2 + :link: getting_started/index + :link-type: doc -Windows and Linux users can authenticate with OIDC-enabled APIs by using the ``[oidc]`` extra. -Currently only the Authorization Code authentication flow is supported. + Learn how to install OpenAPI-Common. -.. list-table:: Authentication methods by platform - :header-rows: 1 - :widths: 30 15 15 40 + .. grid-item-card:: User guide :material-regular:`menu_book` + :padding: 2 2 2 2 + :link: user_guide/index + :link-type: doc - * - Authentication method - - Windows - - Linux - - Builder method - * - API Key - - ✔️ - - ✔️ - - ``.with_anonymous()`` [1]_ - * - Basic - - ✔️ - - ✔️ - - ``.with_credentials()`` - * - NTLM - - ✔️ - - ❌ - - ``.with_credentials()`` - * - Kerberos - - ✔️ - - ➕ [2]_ - - ``.with_autologon()`` - * - OIDC - - ➕ [3]_ - - ➕ [3]_ - - ``.with_oidc()`` + Understand how to use OpenAPI-Common as a base for OpenAPI-based + client applications. -.. [1] Set the appropriate header in ``api_session_configuration``. -.. [2] When installed as ``pip install ansys-openapi-common[linux-kerberos]``. -.. [3] When installed as ``pip install ansys-openapi-common[oidc]``. + .. grid-item-card:: API reference :material-regular:`bookmark` + :padding: 2 2 2 2 + :link: api/index + :link-type: doc -Advanced features ------------------ -You can set all options that are available in Python library *requests* through -the client. This enables you to configure custom SSL certificate validation, send -client certificates if your API server requires them, and configure many other options. + Understand the classes and methods that make up OpenAPI-Common. -For example, to send a client certificate with every request: + .. grid-item-card:: Contribute :material-regular:`group` + :padding: 2 2 2 2 + :link: contributing + :link-type: doc -.. code:: python + Learn how to contribute to the OpenAPI-Common codebase or documentation. - >>> from ansys.openapi.common import SessionConfiguration - >>> configuration = SessionConfiguration( - ... client_cert_path='./my-client-cert.pem', - ... client_cert_key='secret-key' - ... ) - >>> client.configuration = configuration +.. toctree:: + :hidden: + :maxdepth: 3 -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, and a -supported compiler. (GCC works well.) - -You should then be able to install this module with the ``[linux-kerberos]`` extra: - -.. code-block:: sh - - sudo apt install build-essentials python3.8-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``. - -API reference -------------- -For comprehensive API documentation, see :doc:`API reference `. - -Contributions -------------- -Contributions to this library are welcome. For more information, see -:ref:`contributing_openapi`. - -Project index -------------- - -* :ref:`genindex` + getting_started/index + user_guide/index + api/index + contributing diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst new file mode 100644 index 00000000..300cfd11 --- /dev/null +++ b/doc/source/user_guide/index.rst @@ -0,0 +1,124 @@ +.. _ref_user_guide: + +.. currentmodule:: ansys.openapi.common + +User guide +########## + +Basic usage +----------- + +The :class:`.ApiClient` class is designed to be wrapped by code that implements a client +library. You should override the :meth:`~.ApiClient.__init__` or :meth:`~.connect` methods +to add additional required behavior. + +Authentication is configured through the :class:`.ApiClientFactory` object and its +``with_xxx()`` methods. If no authentication is required, you can use the +:meth:`~.ApiClientFactory.with_anonymous()` method. + +.. code:: python + + >>> from ansys.openapi.common import ApiClientFactory + >>> session = ApiClientFactory('https://my-api.com/v1.svc') + ... .with_autologon() + ... .connect() + + + +Authentication schemes +---------------------- +OpenAPI-Common supports API servers configured with no authentication, API keys, +client certificates, and basic authentication. + +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 + :widths: 30 15 15 40 + + * - Authentication method + - Windows + - Linux + - Builder method + * - API Key + - ✔️ + - ✔️ + - ``.with_anonymous()`` [1]_ + * - Basic + - ✔️ + - ✔️ + - ``.with_credentials()`` + * - NTLM + - ✔️ + - ❌ + - ``.with_credentials()`` + * - Kerberos + - ✔️ + - ➕ [2]_ + - ``.with_autologon()`` + * - OIDC + - ➕ [3]_ + - ➕ [3]_ + - ``.with_oidc()`` + +.. [1] Set the appropriate header in ``api_session_configuration``. +.. [2] When installed as ``pip install ansys-openapi-common[linux-kerberos]``. +.. [3] When installed as ``pip install ansys-openapi-common[oidc]``. + + +Session configuration +--------------------- +You can set all options that are available in Python library *requests* through +the client with the :class:`~.SessionConfiguration` object. This enables you to +configure custom SSL certificate validation, send client certificates if your API +server requires them, and configure many other options. + +For example, to send a client certificate with every request: + +.. code:: python + + >>> from ansys.openapi.common import SessionConfiguration + >>> configuration = SessionConfiguration( + ... client_cert_path='./my-client-cert.pem', + ... client_cert_key='secret-key' + ... ) + >>> client.configuration = configuration + + +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 an internally signed certificate you must + use this option. + +Custom certificate store +~~~~~~~~~~~~~~~~~~~~~~~~ + +The :class:`~.SessionConfiguration` object allows you to provide a path to a custom CA certificate. If provided, the +custom CA certificate is used to verify the service's TLS certificate instead of the ``certifi`` package. diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index eca9bb0d..8c0c14a9 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -10,3 +10,4 @@ THIRDPARTY subclassed subclassing Intersphinx +pip\-system\-certs diff --git a/poetry.lock b/poetry.lock index 786a15f1..2fd0c0ca 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1656,6 +1656,31 @@ sphinx = ">=1.8" code-style = ["pre-commit (==2.12.1)"] rtd = ["ipython", "myst-nb", "sphinx", "sphinx-book-theme", "sphinx-examples"] +[[package]] +name = "sphinx-design" +version = "0.6.1" +description = "A sphinx extension for designing beautiful, view size responsive web components." +optional = false +python-versions = ">=3.9" +files = [ + {file = "sphinx_design-0.6.1-py3-none-any.whl", hash = "sha256:b11f37db1a802a183d61b159d9a202314d4d2fe29c163437001324fe2f19549c"}, + {file = "sphinx_design-0.6.1.tar.gz", hash = "sha256:b44eea3719386d04d765c1a8257caca2b3e6f8421d7b3a5e742c0fd45f84e632"}, +] + +[package.dependencies] +sphinx = ">=6,<9" + +[package.extras] +code-style = ["pre-commit (>=3,<4)"] +rtd = ["myst-parser (>=2,<4)"] +testing = ["defusedxml", "myst-parser (>=2,<4)", "pytest (>=8.3,<9.0)", "pytest-cov", "pytest-regressions"] +testing-no-myst = ["defusedxml", "pytest (>=8.3,<9.0)", "pytest-cov", "pytest-regressions"] +theme-furo = ["furo (>=2024.7.18,<2024.8.0)"] +theme-im = ["sphinx-immaterial (>=0.12.2,<0.13.0)"] +theme-pydata = ["pydata-sphinx-theme (>=0.15.2,<0.16.0)"] +theme-rtd = ["sphinx-rtd-theme (>=2.0,<3.0)"] +theme-sbt = ["sphinx-book-theme (>=1.1,<2.0)"] + [[package]] name = "sphinx-notfound-page" version = "1.0.4" @@ -1947,4 +1972,4 @@ oidc = ["keyring", "requests_auth"] [metadata] lock-version = "2.0" python-versions = "^3.10" -content-hash = "5650d830317400fd2d9b6da8e43b7e4582a81bf8fe0cdd48a3e2e0983b10c1f3" +content-hash = "1f5c61a798595d73b94f5784542385f9f5ba006bac24b4603f9042e15fefe9ee" diff --git a/pyproject.toml b/pyproject.toml index 7ff22611..c04c6bf7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -67,6 +67,7 @@ types-requests = { version = "*" } types-python-dateutil = { version = "*" } requests_auth = { version = "*" } keyring = { version = "*" } +sphinx-design = "^0.6.0" [tool.poetry.group.dev-linux] optional = true