Metadata-Version: 2.5
Name: acugis-report
Version: 0.1.0
Summary: AcuGIS Report Server Python SDK and CLI
Project-URL: Homepage, https://github.com/AcuGIS/acugis-jasper-report-server
Project-URL: Documentation, https://github.com/AcuGIS/acugis-jasper-report-server/blob/master/documentation/docs/developer/sdk/python.md
Project-URL: Repository, https://github.com/AcuGIS/acugis-jasper-report-server
Project-URL: Issues, https://github.com/AcuGIS/acugis-jasper-report-server/issues
Project-URL: Changelog, https://github.com/AcuGIS/acugis-jasper-report-server/blob/master/sdk/python/CHANGELOG.md
Author: AcuGIS
Maintainer: AcuGIS
License-Expression: MIT
License-File: LICENSE
Keywords: acugis,cli,jasper,reports,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
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: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# acugis-report — Python SDK

Official Python client and CLI for [AcuGIS Report Server](https://acugis.com).

Package: **acugis-report** · Import: **acugis_report** · Version: **0.1.0** · Python **3.10+**

API contract: [openapi.bundle.yaml](https://github.com/AcuGIS/acugis-jasper-report-server/blob/master/sdk/openapi.bundle.yaml)

Product docs: [Python SDK](https://github.com/AcuGIS/acugis-jasper-report-server/blob/master/documentation/docs/developer/sdk/python.md) · [CLI overview](https://github.com/AcuGIS/acugis-jasper-report-server/blob/master/documentation/docs/developer/cli/overview.md)

## Install

```bash
pip install acugis-report
acugis-report --help
```

```python
from acugis_report import ReportServer
```

To work on this repository:

```bash
cd sdk/python
pip install -e ".[dev]"
pytest
```

## Quick start

```python
from acugis_report import ReportServer

client = ReportServer("https://reports.example.com", token="jrs_…")

me = client.auth.me()
reports = client.reports.list()
pdf, content_type = client.reports.run("Invoice", format="pdf", params={"city": "NYC"})
client.reports.run_to_file("Invoice", "invoice.pdf", format="pdf")

tree = client.folders.tree()
client.resources.upload("logo.png", folder_id=0)
client.health.check()
client.explorer.query({"datasource": "main", "sql": "SELECT 1"})
client.map_reports.run("Parcels", geometry="…", srid=4326)
client.embedded_maps.debug("Parcels")
client.datasources.list()
```

Flat methods remain available for backward compatibility (`client.list_reports()`, `client.run_report(…)`, etc.).

### Environment

| Variable | Purpose |
|----------|---------|
| `ACUGIS_REPORT_URL` | Base URL (used by CLI profiles / docs) |
| `ACUGIS_REPORT_TOKEN` | Bearer token |

## Service namespaces

| Property | Coverage |
|----------|----------|
| `auth` | Me, login/logout, PAT list/create/delete/rotate |
| `reports` | List/get/publish/update/delete/config/thumbnail, parameter lookup, `run` / `run_to_file` |
| `folders` | Tree, browse, search, CRUD, move, permissions |
| `resources` | List, upload, download, replace, delete, images |
| `datasources` | List, create, delete, context (`get`/`update` reserved) |
| `map_reports` | Features, extent, columns, run |
| `embedded_maps` | Debug |
| `explorer` | Datasources, tables, metadata, query, export, spatial, views, dashboard, view permissions |
| `health` | `/health`, `/ready`, diagnostics, Jasper status, doctor |
| `users` / `groups` / `schedules` / `jobs` / `recipients` | Reserved → `NotImplementedByServerError` |

## Errors

Typed errors derive from `ReportServerError`:

- `AuthenticationError` (401)
- `PermissionError` (403)
- `ValidationError` (400 / 422)
- `NotFoundError` (404)
- `ServerError` (5xx)
- `NetworkError`
- `NotImplementedByServerError`

## CLI

```bash
acugis-report --help
```

See the [CLI reference](https://github.com/AcuGIS/acugis-jasper-report-server/blob/master/sdk/python/docs/cli.md) and the [CLI overview](https://github.com/AcuGIS/acugis-jasper-report-server/blob/master/documentation/docs/developer/cli/overview.md).

## Build & test

```bash
cd sdk/python
pip install -e ".[dev]"
pytest
python -m build
python -m twine check dist/*
```

## License

MIT — see [LICENSE](LICENSE).
