Metadata-Version: 2.4
Name: vws-auth-tools
Version: 2026.8.16
Summary: Authentication and authorization tools for interacting with the Vuforia Web Services (VWS) API.
Author-email: Adam Dangoor <adamdangoor@gmail.com>
License-Expression: MIT
Project-URL: Documentation, https://vws-python.github.io/vws-auth-tools/
Project-URL: Source, https://github.com/VWS-Python/vws-auth-tools
Keywords: vuforia,vws
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.13
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: beartype>=0.22.9
Provides-Extra: dev
Requires-Dist: actionlint-py==1.7.12.24; extra == "dev"
Requires-Dist: check-manifest==0.51; extra == "dev"
Requires-Dist: deptry==0.25.1; extra == "dev"
Requires-Dist: doc8==2.0.0; extra == "dev"
Requires-Dist: doccmd==2026.7.19; extra == "dev"
Requires-Dist: freezegun==1.5.5; extra == "dev"
Requires-Dist: furo==2025.12.19; extra == "dev"
Requires-Dist: hypothesis==6.165.3; extra == "dev"
Requires-Dist: interrogate==1.7.0; extra == "dev"
Requires-Dist: mypy[faster-cache]==2.3.0; extra == "dev"
Requires-Dist: mypy-strict-kwargs==2026.7.19.1; extra == "dev"
Requires-Dist: no-defaults==2.1.0; extra == "dev"
Requires-Dist: prek==0.4.13; extra == "dev"
Requires-Dist: pydocstringformatter==1.0.0; extra == "dev"
Requires-Dist: pylint[spelling]==4.0.7; extra == "dev"
Requires-Dist: pylint-per-file-ignores==3.2.1; extra == "dev"
Requires-Dist: pyproject-fmt==2.27.0; extra == "dev"
Requires-Dist: pyrefly==1.2.0; extra == "dev"
Requires-Dist: pyright==1.1.411; extra == "dev"
Requires-Dist: pyroma==5.0.1; extra == "dev"
Requires-Dist: pytest==9.1.1; extra == "dev"
Requires-Dist: pytest-beartype-tests==2026.4.26; extra == "dev"
Requires-Dist: pytest-cov==7.1.0; extra == "dev"
Requires-Dist: requests==2.34.2; extra == "dev"
Requires-Dist: ruff==0.16.2; extra == "dev"
Requires-Dist: shellcheck-py==0.11.0.1; extra == "dev"
Requires-Dist: shfmt-py==4.0.0; extra == "dev"
Requires-Dist: sphinx==9.1.0; extra == "dev"
Requires-Dist: sphinx-copybutton==0.5.2; extra == "dev"
Requires-Dist: sphinx-lint==1.0.2; extra == "dev"
Requires-Dist: sphinx-pyproject==0.3.0; extra == "dev"
Requires-Dist: sphinx-substitution-extensions==2026.8.5; extra == "dev"
Requires-Dist: sphinxcontrib-spelling==8.0.2; extra == "dev"
Requires-Dist: sphinxcontrib-towncrier==0.5.0a0; extra == "dev"
Requires-Dist: strict-kwargs==2026.7.24; extra == "dev"
Requires-Dist: sybil==10.1.0; extra == "dev"
Requires-Dist: torch>=2.5.1; extra == "dev"
Requires-Dist: torchvision>=0.20.1; extra == "dev"
Requires-Dist: towncrier==25.8.0; extra == "dev"
Requires-Dist: ty==0.0.70; extra == "dev"
Requires-Dist: types-requests==2.33.0.20260712; extra == "dev"
Requires-Dist: vale==3.13.0.0; extra == "dev"
Requires-Dist: vulture==2.16; extra == "dev"
Requires-Dist: vws-python-mock==2026.2.22.3; extra == "dev"
Requires-Dist: yamlfix==1.19.1; extra == "dev"
Requires-Dist: zizmor==1.29.0; extra == "dev"
Provides-Extra: release
Requires-Dist: check-wheel-contents==0.6.3; extra == "release"
Requires-Dist: towncrier==25.8.0; extra == "release"
Dynamic: license-file

|Build Status| |PyPI|

VWS Auth Tools
==============

Authentication and authorization tools for interacting with the Vuforia Web Services (VWS) API.

Installation
------------

.. code-block:: shell

   pip install vws-auth-tools

This is tested on Python |minimum-python-version|\+.

Usage
-----

VWS and Query APIs
~~~~~~~~~~~~~~~~~~

.. code-block:: python

   """Make a request to the VWS API."""

   import os
   from http import HTTPStatus
   from urllib.parse import urljoin

   import requests

   from vws_auth_tools import authorization_header, rfc_1123_date

   access_key = os.environ["VWS_SERVER_ACCESS_KEY"]
   secret_key = os.environ["VWS_SERVER_SECRET_KEY"]
   request_path = "/targets"
   content = b""
   method = "GET"
   formatted_date = rfc_1123_date()
   authorization_header_value = authorization_header(
       access_key=access_key,
       secret_key=secret_key,
       method=method,
       content=content,
       content_type="",
       date=formatted_date,
       request_path=request_path,
   )

   headers = {
       "Authorization": authorization_header_value,
       "Date": formatted_date,
   }

   response = requests.request(
       method=method,
       url=urljoin(base="https://vws.vuforia.com", url=request_path),
       headers=headers,
       data=content,
       timeout=30,
   )

   assert response.status_code == HTTPStatus.OK, response.text

Model Target Web API
~~~~~~~~~~~~~~~~~~~~

The `Model Target Web API`_ authenticates with OAuth2 client credentials
rather than the VWS signature scheme.  This package builds the HTTP Basic
header for the ``POST /oauth2/token`` request and the ``Bearer`` header for
the dataset endpoints; making the token request, and caching the returned
token, are left to you.

.. code-block:: python

   """Build authorization headers for the Model Target Web API."""

   import os

   from vws_auth_tools import (
       basic_authorization_header,
       bearer_authorization_header,
   )

   client_id = os.environ["VWS_MODEL_TARGET_CLIENT_ID"]
   client_secret = os.environ["VWS_MODEL_TARGET_CLIENT_SECRET"]

   token_request_headers = {
       "Authorization": basic_authorization_header(
           client_id=client_id,
           client_secret=client_secret,
       ),
       "Content-Type": "application/x-www-form-urlencoded",
   }

   # Sending ``grant_type=client_credentials`` to ``POST /oauth2/token``
   # with those headers returns JSON with an ``access_token`` item.
   access_token = "eyJhbGciOiJtb2NrIn0.e30.example-signature"  # noqa: S105

   dataset_request_headers = {
       "Authorization": bearer_authorization_header(
           access_token=access_token,
       ),
   }

   assert token_request_headers["Authorization"].startswith("Basic ")
   assert dataset_request_headers["Authorization"].startswith("Bearer ")

.. _Model Target Web API: https://developer.vuforia.com/library/vuforia-engine/web-api/model-target-web-api/

Full Documentation
------------------

See the `full documentation <https://vws-python.github.io/vws-auth-tools/>`__.

.. |Build Status| image:: https://github.com/VWS-Python/vws-auth-tools/actions/workflows/ci.yml/badge.svg?branch=main
   :target: https://github.com/VWS-Python/vws-auth-tools/actions
.. |PyPI| image:: https://badge.fury.io/py/VWS-Auth-Tools.svg
   :target: https://badge.fury.io/py/VWS-Auth-Tools
.. |minimum-python-version| replace:: 3.13
