Metadata-Version: 2.4
Name: piwebapiconnect
Version: 0.1.7
Summary: A professional library for PI Web API integration
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.26.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: python-dotenv>=1.0.0

# piwebapiconnect

A professional Python library for OSIsoft PI Web API integration. Built cleanly with `httpx` and `asyncio` to be purely asynchronous and incredibly robust.

## Installation

```bash
pip install piwebapiconnect
```

## Setup & Connecting

### 1. Using a `.env` file (Recommended)

Create a `.env` file in your root folder:

```env
PI_WEB_API_URL=https://your-pi-server/piwebapi
PI_WEB_API_USERNAME=domain\user
PI_WEB_API_PASSWORD=your-password
PI_SERVER_NAME=PISERVER01
PI_WEB_API_VERIFY_SSL=False  # Set to True in production
```

```python
from piwebapiconnect import get_service
service = get_service()
```

### 2. Passing credentials directly

```python
import asyncio
from piwebapiconnect import get_service

async def main():
    service = get_service(
        url="https://your-pi-server/piwebapi",
        username="domain\\user",
        password="your-password",
        server_name="PISERVER01",
        verify_ssl=False
    )

    print(await service.test_connection())
    await service.close()

if __name__ == "__main__":
    asyncio.run(main())
```

---

## Functions Provided

All service functions are **asynchronous** and must be `await`ed.

### Standard Data Fetching

- `get_current_value(tag_name: str)`: Fetch the current snapshot value of a tag.
- `get_real_time_data(tag_name: str)`: An alias for `get_current_value`.
- `get_recorded_values(tag_name: str, start_time: str, end_time: str)`: Fetch actual historical recorded values for a time range.
- `get_interpolated_values(tag_name: str, start_time: str, end_time: str, interval: str)`: Fetch evenly spaced interpolated values (e.g., `interval="1h"`).
- `get_multiple_current_values(tag_names: List[str])`: Fetch values for multiple tags simultaneously using high-efficiency StreamSets.
- `get_summary_data(tag_name: str, start_time: str, end_time: str, summary_type: str = "Average")`: Get Server-calculated statistics (`Average`, `Minimum`, `Maximum`, `Total`, etc.).

### Live Data Streams

- `get_live_data_stream(tag_name: str, interval_seconds: int = 60)`: Returns an asynchronous generator yielding live value updates continuously.
  ```python
  async for data in service.get_live_data_stream("SINUSOID", interval_seconds=5):
      print(data)
  ```

### Data Manipulation

- `write_value(tag_name: str, value: Any, timestamp: Any = None)`: Write a new value to a PI tag at the specified timestamp.
- `delete_value(tag_name: str, timestamp: str)`: Delete an exact point from a PI tag.

### Metadata & Architecture Options

- `search_tags(query: str)`: Search for PI tags based on a query pattern (e.g., `*temperature*`).
- `get_tag_attributes(tag_name: str)`: Fetch the configuration and metadata associated with a PI point.
- `get_asset_servers()`: List available PI AF Asset Servers.
- `get_organizations(asset_server: str)`: List AF Databases on a specified server.

### Utilities

- `test_connection()`: Safely verify connection status without throwing exceptions.
- `close()`: Cleanly drop the internal async HTTP client connections.

---

## Exception Handling

The library utilizes a custom `PIWebAPIError` class to safely report network crashes, HTTP errors, and typo issues, preventing your script from shutting down abruptly.

```python
from piwebapiconnect.service import PIWebAPIError

try:
    data = await service.get_current_value("INVALID_TAG_NAME")
except PIWebAPIError as e:
    print(f"PI Database Error: {e}")
```
