Metadata-Version: 2.4
Name: reliefweb
Version: 0.1.4
Summary: Python client library for the ReliefWeb API
Home-page: https://reliefweb.int/
Author: Titus Joyson
Author-email: tj.joyson@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ReliefWeb Python Library

A Python client library for the [ReliefWeb API](https://apidoc.reliefweb.int/).

## Installation

```bash
pip install .
```

## Supported Endpoints

- reports
- disasters
- jobs
- training
- sources
- countries
- blog
- books
- references

## Usage

```python
from reliefweb.client import ReliefWebClient
from reliefweb.fields import get_fields_for_type

# Initialize client
client = ReliefWebClient()

# Fetch reports
reports = client.get_reports(
    filters={"country": {"eq": "ETH"}},
    fields=["id", "date", "title"],
    sort=[{"date": "desc"}],
    limit=5,
    offset=0,
    presets=None
)
print("Reports:", reports)

# Fetch jobs
jobs = client.get_jobs(
    filters={"status": {"eq": "active"}},
    fields=["id", "title", "date"],
    sort=[{"date": "desc"}],
    limit=5
)
print("Jobs:", jobs)

# Fetch training
training = client.get_training(
    filters=None,
    fields=["id", "title", "date"],
    sort=[{"date": "desc"}],
    limit=5
)
print("Training:", training)

# Fetch blog
blog = client.get_blog(limit=5)
print("Blog:", blog)

# Fetch books
books = client.get_books(limit=5)
print("Books:", books)

# Fetch references
references = client.get_references(limit=5)
print("References:", references)

# Fetch disasters
disasters = client.get_disasters(limit=5, fields=get_fields_for_type("disasters"))
print("Disasters:", disasters)
```

### ReliefWebClient Methods

#### `get_reports(filters=None, fields=None, sort=None, limit=10, offset=0, presets=None)`
Fetch reports from ReliefWeb API.
- `filters` (dict, optional): Filtering parameters (e.g., `{ "country": { "eq": "ETH" } }`).
- `fields` (list, optional): Fields to include in results (e.g., `["id", "date", "title"]`).
- `sort` (list, optional): Sorting options (e.g., `[{"date": "desc"}]`).
- `limit` (int, optional): Number of results to return.
- `offset` (int, optional): Offset for pagination.
- `presets` (list, optional): Presets to apply (e.g., `["expat"]`).
- **Returns:** dict (API response)

#### `get_jobs(filters=None, fields=None, sort=None, limit=10, offset=0, presets=None)`
Fetch jobs from ReliefWeb API.
- Parameters and return value are the same as `get_reports`.

#### `get_training(filters=None, fields=None, sort=None, limit=10, offset=0, presets=None)`
Fetch training events from ReliefWeb API.
- Parameters and return value are the same as `get_reports`.

#### `get_blog(filters=None, fields=None, sort=None, limit=10, offset=0, presets=None)`
Fetch blog posts from ReliefWeb API.
- Parameters and return value are the same as `get_reports`.

#### `get_books(filters=None, fields=None, sort=None, limit=10, offset=0, presets=None)`
Fetch books from ReliefWeb API.
- Parameters and return value are the same as `get_reports`.

#### `get_references(filters=None, fields=None, sort=None, limit=10, offset=0, presets=None)`
Fetch references from ReliefWeb API.
- Parameters and return value are the same as `get_reports`.

#### `get_disasters(filters=None, fields=None, sort=None, limit=10, offset=0, presets=None)`
Fetch disasters from ReliefWeb API.
- Parameters and return value are the same as `get_reports`.

#### Constructor: `ReliefWebClient(api_key=None)`
Initialize the client. If you have an API key, pass it as `api_key`.

## Running Tests

To run the unit tests, use:

```bash
python -m unittest tests/test_client.py
```

## Development & Testing

For development and testing, install all dependencies with:

```bash
pip install -r requirements-dev.txt
```

This will install tools for building, publishing, linting, and testing in addition to the runtime requirements.

## Features
- Simple interface for ReliefWeb API endpoints
- Handles authentication and pagination

## License
MIT

## Maintainers & Contributors

To build and publish this package to PyPI:

1. Install development tools:
   ```bash
   pip install build twine
   ```
2. Build the package:
   ```bash
   python -m build
   ```
3. Check the package:
   ```bash
   python -m twine check dist/*
   ```
4. Publish to PyPI:
   ```bash
   python -m twine upload dist/*
   ```

> Note: Only `requests` is required for end users. Build and publish tools are only needed for maintainers.
