Metadata-Version: 2.5
Name: povineq
Version: 0.1.0
Summary: Python wrapper for the World Bank PIP API
Project-URL: Homepage, https://github.com/PIP-Technical-Team/povineq
Project-URL: Documentation, https://pip-technical-team.github.io/povineq/
Project-URL: Repository, https://github.com/PIP-Technical-Team/povineq
Project-URL: Issues, https://github.com/PIP-Technical-Team/povineq/issues
Author-email: PIP Technical Team <pip@worldbank.org>
License: MIT License
        
        Copyright (c) 2026 PIP Technical Team
        
        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: inequality,pip,poverty,welfare,world bank
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Scientific/Engineering
Requires-Python: <3.14,>=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: loguru>=0.7
Requires-Dist: pandas>=2.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: pyarrow>=15.0
Requires-Dist: pydantic>=2.0
Provides-Extra: polars
Requires-Dist: polars>=1.0; extra == 'polars'
Description-Content-Type: text/markdown

# povineq

Python wrapper for the [World Bank PIP API](https://pip.worldbank.org/).
Mirrors the functionality of the [`pipr`](https://github.com/worldbank/pipr) R package.

## Installation

Once the first release is published, install the package from PyPI:

```bash
pip install povineq
# with optional polars support
pip install "povineq[polars]"
```

The package supports Python 3.10 through 3.13. For development snapshots,
install directly from GitHub:

```bash
pip install git+https://github.com/PIP-Technical-Team/povineq.git
pip install "povineq[polars] @ git+https://github.com/PIP-Technical-Team/povineq.git"
```

## Quick Start

```python
import povineq

# Poverty statistics for a single country
df = povineq.get_stats(country="AGO", year=2000)

# All countries, gap-filled
df = povineq.get_stats(fill_gaps=True)

# World Bank regional aggregates
df = povineq.get_wb()

# Country profiles
df = povineq.get_cp(country="IDN")
df = povineq.get_cp_ki(country="IDN")

# Auxiliary tables
tables = povineq.get_aux()          # list available tables
gdp    = povineq.get_aux("gdp")    # fetch a specific table
cpi    = povineq.get_cpi()         # convenience wrapper

# API info
print(povineq.check_api())
print(povineq.get_versions())
```

## API Reference

| Function | Description |
|---|---|
| `get_stats()` | Poverty and inequality statistics |
| `get_wb()` | World Bank regional/global aggregates |
| `get_agg()` | Custom aggregates (FCV, etc.) |
| `get_cp()` | Country profile download |
| `get_cp_ki()` | Country profile key indicators |
| `get_aux(table)` | Auxiliary data tables |
| `get_countries()`, `get_regions()`, … | Per-table convenience wrappers |
| `check_api()` | API health check |
| `get_versions()` | Available data versions |
| `delete_cache()` | Clear the local cache directory |

## Development

```bash
git clone https://github.com/PIP-Technical-Team/povineq
cd povineq
env -u UV_INDEX -u UV_INDEX_URL -u UV_EXTRA_INDEX_URL UV_DEFAULT_INDEX=https://pypi.org/simple uv sync --locked --group dev
env -u UV_INDEX -u UV_INDEX_URL -u UV_EXTRA_INDEX_URL UV_DEFAULT_INDEX=https://pypi.org/simple uv run --locked pytest -m "not online"
```

Documentation and release tooling are uv dependency groups, not published
package extras. Use the locked public-PyPI commands below:

```bash
env -u UV_INDEX -u UV_INDEX_URL -u UV_EXTRA_INDEX_URL UV_DEFAULT_INDEX=https://pypi.org/simple uv sync --locked --no-default-groups --group docs
env -u UV_INDEX -u UV_INDEX_URL -u UV_EXTRA_INDEX_URL UV_DEFAULT_INDEX=https://pypi.org/simple uv sync --locked --no-default-groups --group release
```

## Release Process

Releases are tag-gated by `.github/workflows/publish.yml`. The validation job
requires the `vX.Y.Z` tag to match the version in `pyproject.toml`, builds and
checks the artifacts, and passes only those artifacts to the publish job.
Publishing uses PyPI trusted publishing through the self-service GitHub
environment `pypi`, which is restricted to protected `v*` tags. No PyPI token
is stored in the repository.

The PyPI trusted publisher must be registered with owner `PIP-Technical-Team`,
repository `povineq`, workflow `publish.yml`, and environment `pypi`.

## Data Source

World Bank [Poverty and Inequality Platform (PIP)](https://pip.worldbank.org/).
