Metadata-Version: 2.5
Name: condepe
Version: 0.1.0
Summary: Access the open data of the Pernambuco Observatory (Condepe/Fidem) from Python
Project-URL: Homepage, https://strategicprojects.github.io/condepe-py/
Project-URL: Data, https://cf.pe.gov.br/observatorio
Project-URL: Repository, https://github.com/StrategicProjects/condepe-py
Project-URL: Issues, https://github.com/StrategicProjects/condepe-py/issues
Project-URL: Changelog, https://github.com/StrategicProjects/condepe-py/blob/main/NEWS.md
Author-email: André Leite <leite@castlab.org>, Marcos Wasiliew <marcos.wasiliew@gmail.com>, Hugo Vasconcelos <hugo.vasconcelos@ufpe.br>, Carlos Amorim <carlos.agaf@ufpe.br>, Diogo Bezerra <diogo.bezerra@ufpe.br>, Júlia Nascimento Barreto <juliabarreto@gd.seplag.pe.gov.br>
License: MIT License
        
        Copyright (c) 2026 condepe 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,Condepe/Fidem,Pernambuco,municipalities,open-data,pandas,statistics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: pandas>=1.3
Requires-Dist: platformdirs>=3
Requires-Dist: pyarrow>=10
Requires-Dist: requests>=2.25
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: responses>=0.23; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: matplotlib>=3.5; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Requires-Dist: responses>=0.23; extra == 'test'
Description-Content-Type: text/markdown

# condepe <img src="docs/assets/logo.svg" align="right" height="139" alt="condepe hex logo" />

Python access to the open data of the **Observatório de Pernambuco**, published by
[Condepe/Fidem](https://cf.pe.gov.br) (the Pernambuco State Agency for Planning and
Research): municipal series on population, economy, public finance, labour,
education, health, security, transport and environment for the 185
municipalities of Pernambuco, Brazil.

Every source is published in the same long format (one observation per row, 15
columns), so one set of functions covers all of them.

## Installation

```bash
pip install condepe
# development version:
pip install git+https://github.com/StrategicProjects/condepe-py
```

## Usage

```python
import condepe

# Sources available (one row each), with the catalogue version
cat = condepe.condepe_catalog()
cat.attrs["version"]

# Indicators of a source
condepe.condepe_indicators("sidra_populacao_estimada")

# A series: Recife (IBGE 2611606), 2020 onwards
condepe.condepe_series(
    "sidra_populacao_estimada",
    "Populacao residente estimada",
    code="2611606",
    years=range(2020, 2027),
)

# A whole source, and the municipality list
condepe.condepe_data("datasus_sinasc")
condepe.condepe_localities()
```

Column names are kept in Portuguese, as published, so results stay traceable to
the official files: `cd_municipio_ibge`, `nm_municipio`, `ano`, `mes`,
`indicador`, `indicador_base`, `valor`, `unidade`, `natureza`, `id_fonte`,
`eixo`, `tema`, `assunto`, `fonte_original`, `arquivo_origem`. Monthly series
carry the period in `indicador` (`"… [MM/YYYY]"`) and `mes`; `indicador_base` is
the label without it.

## Where the data come from

- **Canonical:** <https://cf.pe.gov.br/observatorio/dados/atual/>
- **Mirror (fallback):** the Hugging Face dataset
  [`mlkwy/observatorio-pernambuco`](https://huggingface.co/datasets/mlkwy/observatorio-pernambuco),
  with the same relative paths.

Files are cached on disk per catalogue version (`condepe_cache_dir()`) and
checked against the sha256 published in the catalogue. The catalogue itself is
trusted for 6 hours. Set `CONDEPE_URL`, `CONDEPE_MIRROR_URL` or
`CONDEPE_CACHE_DIR` to override the defaults.

Documentation: <https://strategicprojects.github.io/condepe-py/>.

## Citation and license

Data: Condepe/Fidem, *Observatório de Pernambuco — Base de Dados do Estado*,
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). The citation with the
version in use is in `condepe_catalog().attrs["citation"]`.

Code: MIT. To read or write *private* buckets on `s3.pe.gov.br` with an
access key, see [`s3pe`](https://github.com/StrategicProjects/s3pe); `condepe`
needs no key, since the Observatory open data are public. An R package with the same functions is
[`condepe` for R](https://github.com/StrategicProjects/condepe-r).
