Metadata-Version: 2.4
Name: pi-web-api-python-sdk
Version: 0.1.0
Summary: A modern, typed Python SDK for AVEVA PI Web API
Author: Tycho Data
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/tychodata/pi-web-api-python-sdk
Project-URL: Source, https://github.com/tychodata/pi-web-api-python-sdk
Project-URL: Documentation, https://tychodata.github.io/pi-web-api-python-sdk
Project-URL: Issue Tracker, https://github.com/tychodata/pi-web-api-python-sdk/issues
Keywords: PI System,PI Web API,AVEVA,OSIsoft,historian,industrial data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: kerberos
Requires-Dist: httpx-gssapi>=0.3; extra == "kerberos"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: pre-commit>=4; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.27; extra == "docs"
Dynamic: license-file

# PI Web API Python SDK

A modern, typed Python SDK for PI Web API.

> This is an independent open-source project. It is not an AVEVA product and is not
> affiliated with, sponsored by, or endorsed by AVEVA. PI System, PI Web API, AVEVA,
> and OSIsoft are trademarks of their respective owners.

The SDK focuses on the PI Web API workflows that show up repeatedly in real PI
applications: AF discovery, element and attribute lookup, bulk time-series reads,
Event Frames, AF Tables, Stream Updates, and Batch requests.

## Installation

```bash
pip install pi-web-api-python-sdk
```

For Kerberos / Negotiate support:

```bash
pip install "pi-web-api-python-sdk[kerberos]"
```

## Quick start

```python
from pi_web_api import PIWebAPIClient

with PIWebAPIClient(
    "https://pi.example.com/piwebapi",
    auth=("DOMAIN\\user", "password"),
) as client:
    attribute = client.attributes.get_by_path(
        r"\\AFSERVER\Plant\Pump-101|Discharge Pressure"
    )

    history = client.stream_sets.get_recorded(
        web_ids=[attribute.web_id],
        start_time="*-8h",
        end_time="*",
    )

    for value in history.items[0].items:
        print(value.timestamp, value.value)
```

## Async client

The asynchronous client exposes the same resource-oriented API:

```python
from pi_web_api import AsyncPIWebAPIClient

async with AsyncPIWebAPIClient("https://pi.example.com/piwebapi") as client:
    result = await client.stream_sets.get_values(["WEBID1", "WEBID2"])
```

## Authentication

The core SDK accepts anything supported by `httpx`:

```python
# Basic
client = PIWebAPIClient(url, auth=("DOMAIN\\user", "password"))

# Bearer
from pi_web_api.auth import BearerAuth
client = PIWebAPIClient(url, auth=BearerAuth("token"))

# Custom httpx.Auth
client = PIWebAPIClient(url, auth=my_auth)
```

Kerberos is an optional dependency:

```python
from pi_web_api.auth import KerberosAuth
client = PIWebAPIClient(url, auth=KerberosAuth())
```

## Supported areas in v0.1

- PI Web API root and System status/user info
- Asset Servers and AF Databases
- Elements, Attributes, Element Templates, Attribute Templates
- Enumeration Sets and values
- StreamSet current, recorded, interpolated, plot, joined, recorded-at-time(s)
- StreamSet recorded-value writes/removals
- Stream Updates registration and marker polling
- Event Frame lookup, search, create, update, delete, acknowledge, annotations
- AF Table lookup, reads, and whole-table updates
- Batch, including dependent subrequests
- Sync and async clients
- Typed Pydantic v2 models with unknown-field preservation
- Raw request escape hatch

## Development

```bash
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate

pip install -e ".[dev,docs]"
pytest
ruff check .
mypy src
mkdocs serve
python -m build
```

See `docs/` for endpoint guides, API reference, and contributor conventions.

## License

Apache-2.0. See `LICENSE`.
