Metadata-Version: 2.4
Name: viyapy
Version: 3.0.0
Summary: A Python client for SAS Viya Intelligent Decisioning (Decisions + Micro Analytic Score) supporting Viya 3.5 and Viya 4.
Project-URL: Homepage, https://github.com/Shai-Alit/viyapy
Project-URL: Repository, https://github.com/Shai-Alit/viyapy
Project-URL: Issues, https://github.com/Shai-Alit/viyapy/issues
Project-URL: Changelog, https://github.com/Shai-Alit/viyapy/blob/main/CHANGELOG.md
Author-email: Sean Ford <psuaerofighter@gmail.com>
License: MIT License
        
        Copyright (c) 2022 Sean F
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: decisions,intelligent decisioning,mas,microanalytic,sas,scoring,viya
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: requests>=2.34.2
Requires-Dist: urllib3>=2.7.0
Provides-Extra: dev
Requires-Dist: build>=1.5.0; extra == 'dev'
Requires-Dist: hypothesis>=6.164.0; extra == 'dev'
Requires-Dist: mypy>=2.3.0; extra == 'dev'
Requires-Dist: nox>=2026.7.11; extra == 'dev'
Requires-Dist: pre-commit>=4.6.1; extra == 'dev'
Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
Requires-Dist: pytest>=9.1.1; extra == 'dev'
Requires-Dist: responses>=0.26.2; extra == 'dev'
Requires-Dist: ruff>=0.16.1; extra == 'dev'
Requires-Dist: twine>=7.0.0; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.7.7; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6.1; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=1.0.6; extra == 'docs'
Provides-Extra: drift
Requires-Dist: openapi-spec-validator>=0.9.0; extra == 'drift'
Requires-Dist: pyyaml>=6.0.3; extra == 'drift'
Requires-Dist: schemathesis>=4.24.3; extra == 'drift'
Description-Content-Type: text/markdown

# viyapy

[![PyPI](https://img.shields.io/pypi/v/viyapy.svg)](https://pypi.org/project/viyapy/)
[![Python versions](https://img.shields.io/pypi/pyversions/viyapy.svg)](https://pypi.org/project/viyapy/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![CI](https://github.com/Shai-Alit/viyapy/actions/workflows/ci.yml/badge.svg)](https://github.com/Shai-Alit/viyapy/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-%E2%89%A590%25-brightgreen.svg)](https://github.com/Shai-Alit/viyapy/actions/workflows/ci.yml)

A typed Python client for **SAS Viya Intelligent Decisioning** — inspect decision
flows and execute [Micro Analytic Score (MAS)](https://developer.sas.com/) modules
over the REST API. It supports both **Viya 3.5** and **Viya 4** (LTS and Stable)
through a version/dialect layer, and is built for production use: one hardened
HTTP stack with mandatory timeouts and retries, a typed exception hierarchy,
bearer-token redaction in the library's logs and `repr`, and full type hints
(`py.typed`).

## Install

> **Pre-release note:** the `ViyaClient` API documented below ships in
> **viyapy 3.0**, which is not yet published to PyPI (the current PyPI release
> predates this API). Until 3.0 is released, install from source:
> `pip install "git+https://github.com/Shai-Alit/viyapy@main"`.

Once 3.0 is published, the usual install applies:

```bash
pip install viyapy
```

Requires Python 3.9+.

## Quickstart

```python
import os

from viyapy import ViyaClient

my_token = os.environ["VIYA_TOKEN"]  # your OAuth2 bearer token
client = ViyaClient("https://viya.example.com", token=my_token)

# Inspect a decision flow and its models
decision = client.decisions.get("my-decision-id")
for model in decision.models:
    print(model.name, model.modified_by)

# Execute a published decision's MAS module against a feature dict
result = client.mas.execute("api_tester1_0", {"input_string": "this is a test"})
print(result.outputs["output_string"])
```

`ViyaClient` is also a context manager (`with ViyaClient(...) as client: ...`),
which closes the underlying HTTP session on exit.

### Choosing the Viya generation

The client targets Viya 4 by default. For a Viya 3.5 deployment, pass
`viya_version`:

```python
client = ViyaClient("https://viya.example.com", token=my_token, viya_version="3.5")
```

The dialect layer handles the endpoint, media-type, and response-shape
differences (including the MAS `output` vs `outputs` key) for you.

## Authentication

Provide credentials with exactly one of `token` or `auth`.

A static bearer token:

```python
client = ViyaClient("https://viya.example.com", token=os.environ["VIYA_TOKEN"])
```

Or an `auth` **token provider** — a zero-argument callable returning the current
token, called on every request. A provider that refreshes and caches internally
gives transparent token rotation:

```python
def bearer() -> str:
    return my_oauth_session.current_access_token()  # refreshes as needed

client = ViyaClient("https://viya.example.com", auth=bearer)
```

TLS verification is on by default; pass `verify="/path/to/ca-bundle.pem"` for a
custom CA, and see the docs before ever disabling it. The library does not write
the bearer token to its logs or `repr`; a redaction filter additionally scrubs
any `Bearer <token>` pattern from log records as a backstop. (A custom `auth`
provider is responsible for not leaking the token in its own exceptions/logs.)

## Error handling

Every failure raises a typed `ViyaError` subclass — the library never prints,
never swallows exceptions, and never returns `None` to signal failure. API
errors (`ViyaAPIError` and its subclasses) carry the HTTP status, the SAS Viya
error code and details, and a correlation id when the server provides one;
local configuration errors (`ViyaConfigError`) and malformed-response errors
(`ViyaResponseError`) carry their own context instead. Catch broadly or
precisely:

```python
from viyapy import ViyaError, ViyaNotFoundError, ViyaRateLimitError

try:
    result = client.mas.execute("api_tester1_0", {"input_string": "x"})
except ViyaNotFoundError:
    ...  # the module or step does not exist
except ViyaRateLimitError as exc:
    retry_after = exc.retry_after
except ViyaError as exc:
    logger.error("Viya call failed: %s", exc)  # base class catches everything
```

## Documentation

Full guides and the autodoc API reference are built with MkDocs (published in a
later release). In the meantime:

- **Migrating from the 2.x flat API:** [`MIGRATION.md`](MIGRATION.md)
- **Changelog:** [`CHANGELOG.md`](CHANGELOG.md)

## Supported versions

- **Python:** 3.9 – 3.13
- **SAS Viya:** 3.5 and Viya 4 (LTS and Stable tracks). Viya 3.5 **revision
  24w44 (October 2024) or later**, deployed on a supported Linux distribution,
  holds Standard Support through **October 1, 2027**; older revisions and other
  platforms fall under Limited Support. Confirm your deployment against SAS's
  current [Viya support policy](https://support.sas.com/).

## License

MIT © Sean Ford. See [`LICENSE`](LICENSE).

## References

1. SAS Institute Inc. 2020. *SAS® Intelligent Decisioning: Decision Management REST API Examples.* Cary, NC: SAS Institute Inc.
2. [SAS Developer — Decision Management REST API](https://developer.sas.com/apis/rest/DecisionManagement/)
