Metadata-Version: 2.4
Name: tcepepy
Version: 0.1.0
Summary: Python client for the Open Data API of the Pernambuco Court of Accounts (TCE-PE)
Project-URL: Homepage, https://github.com/StrategicProjects/tcepepy
Project-URL: Repository, https://github.com/StrategicProjects/tcepepy
Project-URL: Bug Reports, https://github.com/StrategicProjects/tcepepy/issues
Project-URL: API docs, https://sistemas.tcepe.tc.br/DadosAbertos/
Author-email: Andre Leite <leite@castlab.org>, Marcos Wasilew <marcos.wasilew@gmail.com>, Hugo Vasconcelos <hugo.vasconcelos@ufpe.br>, Carlos Amorin <carlos.agaf@ufpe.br>, Diogo Bezerra <diogo.bezerra@ufpe.br>
License: MIT License
        
        Copyright (c) 2025 tcepepy authors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: brazil,dados-abertos,government,open-data,pernambuco,tce-pe
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Requires-Dist: pandas>=1.5
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Requires-Dist: rich>=13.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: black>=24.0; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: rich
Requires-Dist: rich>=13.0; extra == 'rich'
Description-Content-Type: text/markdown

# tcepepy

Python client for the [TCE-PE](https://www.tce.pe.gov.br/) (Tribunal de Contas
do Estado de Pernambuco) **Open Data API**. It is the Python counterpart of the
R package [`tceper`](https://github.com/StrategicProjects/tceper).

`tcepepy` wraps **71 API endpoints** into friendly functions that accept
`snake_case` parameter names and return `pandas` DataFrames. A built-in catalog
lets you discover endpoints and inspect their parameters and output fields —
all offline, without leaving Python.

> ⚠️ **Geo-restriction.** The API host (`sistemas.tcepe.tc.br`) only accepts
> connections from **Brazilian IP addresses**. From outside Brazil, queries
> time out. The discovery helpers (`catalog()`, `params()`, `fields()`) work
> offline anywhere, as they read from the bundled catalog.

> ❗ **Language note.** Wrapper functions are named in English, but the
> underlying API is in Portuguese — so you pass *parameters* in Portuguese,
> e.g. `state_revenues(AnoReferencia=2025)`. See the
> [official endpoint list](https://sistemas.tcepe.tc.br/DadosAbertos/Exemplo!listar).

## Installation

```bash
pip install tcepepy            # core (httpx + pandas)
pip install "tcepepy[rich]"    # prettier console output
```

## Quick start

```python
import tcepepy as tce

# 1. Discover endpoints (offline)
tce.catalog()
tce.catalog(search="contrat")

# 2. Inspect parameters and output fields (offline)
tce.params("Contratos")
tce.fields("Contratos")

# 3. Query (needs a Brazilian IP) — snake_case or the original API names both work
tce.contracts(codigo_efisco_ug="510101")
tce.contracts(CodigoEfiscoUG="510101", ano_contrato="2025")
```

## Explore the API

```python
tce.catalog()
#       endpoint      group                title  url
# 0  ReceitasEstaduais  Receitas  Relação das Receitas Estaduais  ...

tce.params("Contratos")    # api_name, r_name, required, type, description
tce.fields("Contratos")    # name, r_name, type, description
```

Use `snake_case` (`r_name`) or the original API names — both are accepted.

## Cache

Every wrapper caches results in memory, keyed by endpoint + parameters
(default TTL: 1 hour).

```python
tce.contracts(codigo_efisco_ug="510101")                 # hits the API
tce.contracts(codigo_efisco_ug="510101")                 # cache hit (instant)
tce.contracts(codigo_efisco_ug="510101", cache=False)    # force fresh

tce.cache_info()    # inspect cached entries
tce.cache_clear()   # clear all
```

## Parameter validation

Parameters are validated against the catalog. Passing an unknown parameter
raises an error listing the allowed ones:

```python
tce.contracts(xyz="foo")
# tcepepy.catalog.UnknownParameterError: Unknown query parameter(s) for
# endpoint 'Contratos': xyz.
# Allowed parameters:
#   - unidade_gestora (UnidadeGestora)
#   - codigo_efisco_ug (CodigoEfiscoUG)
#   ...
```

## Configuration

```python
tce.config.verbose = True      # print the final API URL on every call
tce.config.progress = False    # silence status messages
tce.config.cache_ttl = 7200    # cache TTL in seconds
```

Or via environment variables: `TCEPEPY_VERBOSE`, `TCEPEPY_PROGRESS`,
`TCEPEPY_CACHE_TTL`.

## Direct access

To call any endpoint (including ones without a dedicated wrapper) using API
parameter names directly:

```python
tce.request("Contratos", CodigoEfiscoUG="510101", AnoContrato="2025")
```

## API limits

The API returns at most **100,000 records** per request; `tcepepy` warns when
this limit is hit. Use filters to narrow your query.

## License

MIT. This package is an unofficial client; the data belongs to TCE-PE.
