Metadata-Version: 2.4
Name: gmr-reports-client
Version: 1.7.5
Summary: Official Python Client SDK for GMR Reports SaaS Gateway
Author-email: GMR Research <support@gmresearch.io>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/gmreserarch-io/gmr-reports
Project-URL: Documentation, https://github.com/gmreserarch-io/gmr-reports/blob/main/sdk/python/README.md
Project-URL: Issues, https://github.com/gmreserarch-io/gmr-reports/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# gmr-reports-client

Python client for the [GMR Reports](https://github.com/gmreserarch-io/gmr-reports)
document rendering API. Renders PDF and XLSX from JasperReports (`.jrxml`),
Eclipse BIRT and Crystal Reports templates.

Standard library only — no dependencies to audit, no transitive surface.

```bash
pip install gmr-reports-client
```

## Getting a key

Sign up at [gmrglobe.com](https://gmrglobe.com) for an API key. The Developer Free
tier covers development, testing and evaluation; production use needs a
subscription. You can try the API without signing up at
[sandbox.gmrglobe.com](https://sandbox.gmrglobe.com).

## Usage

Everything renders through one call. Which report and which format are both
arguments, so a new report type does not need a new method and asking for a
workbook instead of a PDF is one field.

```python
from gmr_reports import GmrReportsClient

client = GmrReportsClient(
    api_key="your-api-key",
    base_url="https://api.gmrglobe.com",
)

# A template you supply, with your own data
pdf = client.render(
    template_source=open("invoice.jrxml").read(),
    parameters={"INVOICE_NUMBER": "FAC-2026-1045"},
    data=[
        {"code": "MAT-001", "description": "Cemento Sol", "quantity": 500,
         "unitPrice": 8.0, "total": 4000.0},
    ],
)
open("invoice.pdf", "wb").write(pdf)
```

Name exactly one source:

| Argument | What it is |
|---|---|
| `report_type` | a built-in type: `"invoice"`, `"statement"`, `"aging"` |
| `template_name` | a template you saved for your tenant |
| `template_source` | the template itself, compiled for this one call |

Naming two raises `ValueError` before anything leaves the process.

### The same report, either format

```python
pdf  = client.render(report_type="statement")
xlsx = client.render(report_type="statement", output_format="xlsx")
```

`output_format` is `"pdf"` or `"xlsx"` and works for all three sources.

### What this deployment offers

```python
client.list_report_types()
# {"types": [{"type": "invoice", "title": "Factura", ...}, ...]}
```

### Other template dialects

```python
pdf = client.render(template_source=birt_content, template_format="birt")
pdf = client.render(template_source=crystal_content, template_format="crystal")
```

### Templates stored server-side

```python
client.upload_external_template("monthly-statement", jrxml_content)
client.get_template_status("monthly-statement")
pdf = client.render(template_name="monthly-statement", data=rows)
```

### Deprecated

`get_invoice_pdf()`, `get_invoice_excel()`, `render_dynamic_pdf()`,
`render_birt_pdf()` and `render_crystal_pdf()` still work and now delegate to
`render()`. They emit a `DeprecationWarning` naming their replacement. The
invoice is one report type among several, and the output format is an argument
rather than a different method.

### Consumption

```python
usage = client.get_tenant_usage("your-tenant-id")
# {"monthlyUsed": 412, "monthlyQuota": 100000, ...}
```

## Rate limits and retries

The client retries on HTTP 429 up to `max_retries` times, honouring the
`Retry-After` header:

```python
client = GmrReportsClient(api_key="...", base_url="...", max_retries=5)
```

Every other non-2xx response raises `RuntimeError` carrying the status code and
the server's message, so a failure tells you what the API said rather than just
that something went wrong. Exhausting the retries on 429 means your plan's
monthly quota is spent, not that the service is down — those are different
problems and the message distinguishes them.

## Licence

This client is licensed under the **Apache License 2.0** and you may use, modify
and redistribute it freely, including in open-source projects.

The GMR Reports rendering engine it talks to is commercial software under its own
[licence agreement](https://github.com/gmreserarch-io/gmr-reports/blob/main/LICENSE).
Installing this client grants you no rights in the engine.

Copyright (c) 2026 GMResearch-US LLC. GMR REPORTS is a trademark of
GMResearch-US LLC.
