Metadata-Version: 2.4
Name: barb-sdk
Version: 1.0.0
Summary: Python SDK for Barb APIs and integrations.
Author: Barb
License-Expression: MIT
Project-URL: Homepage, https://bitbucket.org/barb/pybarb
Project-URL: Documentation, https://bitbucket.org/barb/pybarb/src/main/docs/
Project-URL: Issues, https://bitbucket.org/barb/pybarb/issues
Keywords: sdk,barb,api
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.32.5
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pandas>=3.0.1

# pybarb SDK - Documentation

This guide reflects the current SDK flow in `src/pybarb/main.py`.



## Installation

For local development:

```bash
!TODO: Add installation instructions, e.g. pip install -e . or pip install pybarb-sdk
```

---

## Credentials and Configuration

`Connection` reads credentials from `BARB_API_KEY` when `api_key` is not passed.

`BARB_API_KEY` must contain JSON text with your client credentials, for example:

```bash
export BARB_API_KEY='{"client_id":"your-client-id","client_secret":"your-client-secret"}'
```

Optional API root override:

```bash
export BARB_API_ROOT='https://barb-api.co.uk/api/v3/'
```

Logging level override (supports `.env` via `python-dotenv`):



`BARB_LOG_LEVEL` is also supported as an alias. If neither is set (or value is invalid), `INFO` is used.
`pybarb` does not auto-configure handlers on import; call `setup_logging()` explicitly when needed.

```python
from pybarb.utils.logging_config import setup_logging

setup_logging()
```

You can also pass credentials directly:

```python
from pybarb.connection.connection import Connection

conn = Connection(api_key={"client_id": "your-client-id", "client_secret": "your-client-secret"})
```

---

## Usage

This is the same high-level flow used in `main.py`:

```python
from pybarb.connection.connection import Connection
from pybarb.metadata.station import Station
from pybarb.utils.dataframe_utils import to_dataframe

conn = Connection()
conn.connect()

stations = Station(conn)
stations_data = stations.get_stations()
df = to_dataframe(stations_data)

print(df.head())
```

If you store credentials in a file, `main.py` also includes a `load_credentials` helper.

---

## Station Methods

`Station` currently exposes these methods:

- `get_stations()` -> returns the full station payload as `list[dict[str, Any]]`
- `list_stations(regex_filter: str | None = None)` -> returns station names
- `get_station_code(station_name: str)` -> returns a matched station code (`int | str`)

Example:

```python
from pybarb.connection.connection import Connection
from pybarb.metadata.station import Station

conn = Connection()
conn.connect()

station_client = Station(conn)
print(station_client.get_station_code("BBC1"))
print(station_client.list_stations(regex_filter="^BBC"))
```

---

## Error Handling

Current behavior:

- `Connection.connect()` raises `RuntimeError` for authentication/network/token failures.
- `Station` methods raise `ApiError` for API and payload validation failures.

```python
from pybarb.connection.connection import Connection
from pybarb.metadata.station import Station
from pybarb.utils import ApiError

try:
    conn = Connection()
    conn.connect()

    station_client = Station(conn)
    print(station_client.get_station_code("BBC1"))
except ApiError as e:
    print(f"Station API error: {e}")
except RuntimeError as e:
    print(f"Connection error: {e}")
```

---
