Metadata-Version: 2.4
Name: pykenyalaw
Version: 0.1.0
Summary: A typed Python client for searching kenyalaw.org records
License: ISC
Project-URL: Homepage, https://github.com/MuhammadOmarMuhdhar/pykenyalaw
Project-URL: Source, https://github.com/MuhammadOmarMuhdhar/pykenyalaw
Project-URL: Issues, https://github.com/MuhammadOmarMuhdhar/pykenyalaw/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# pykenyalaw

A typed Python client for searching [kenyalaw.org](https://kenyalaw.org) - the official Kenya Law repository of judgments, legislation, gazettes, and bills.

[![API Alive Check](https://github.com/MuhammadOmarMuhdhar/pykenyalaw/actions/workflows/api-alive.yml/badge.svg)](https://github.com/MuhammadOmarMuhdhar/pykenyalaw/actions/workflows/api-alive.yml)
[![PyPI - Version](https://img.shields.io/pypi/v/pykenyalaw)](https://pypi.org/project/pykenyalaw/)
[![License: ISC](https://img.shields.io/pypi/l/pykenyalaw)](https://opensource.org/licenses/ISC)


### Requirements

- Python 3.10+

### Install

```bash
pip install pykenyalaw
```

### Quick start

```python
from pykenyalaw import Client, SearchRequest

client = Client()
for doc in client.search(SearchRequest(query="land")):
    print(doc.date, doc.title, doc.url)
```

### Features
- Streams results as it searches
- Typed, validated models
- Rich filtering
- Explicit error handling

### Usage

#### Filtering by a single value

```python
for doc in client.search(SearchRequest(query="land", court="Supreme Court")):
    print(doc.citation, doc.date)
```

#### Filtering by multiple values

Pass a list to match more than one value in a single search:

```python
from pykenyalaw import Client, SearchRequest

client = Client()
request = SearchRequest(
    query="election",
    court=["Court of Appeal", "High Court"],
    year=[2020, 2021],
)
for doc in client.search(request):
    print(doc.title, doc.url)
```

#### Reading document fields

```python
from pykenyalaw import Client, SearchRequest

client = Client()
for doc in client.search(SearchRequest(query="environment")):
    print(doc.title)
    print("  citation:", doc.citation)
    print("  judges:  ", ", ".join(doc.judges or []))
    print("  outcome: ", ", ".join(doc.outcome or []))
    print("  url:     ", doc.url)
```

#### Handling errors

```python
from pykenyalaw import Client, SearchRequest, QueryNoResultsError

client = Client()
try:
    for doc in client.search(SearchRequest(query="qqxkzqh9")):
        print(doc.title)
except QueryNoResultsError as exc:
    print("No results:", exc)
```

### API reference

#### `Client(timeout=15.0, max_pages=10)`

| Parameter | Description |
|-----------|-------------|
| `timeout` | Per-request timeout, in seconds. |
| `max_pages` | Maximum number of result pages to fetch per search. |

#### `SearchRequest`

| Field | Type | Description |
|-------|------|-------------|
| `query` | `str` | Search terms (required). |
| `court` | `str \| list[str]` | Court to restrict results to. |
| `doc_type` | `str \| list[str]` | Type of document (e.g. `legislation`). |
| `nature` | `str \| list[str]` | Nature of the document. |
| `year` | `int \| list[int]` | Year of the document. |
| `jurisdiction` | `str \| list[str]` | Jurisdiction. |
| `locality` | `str \| list[str]` | Locality. |
| `outcome` | `str \| list[str]` | Case outcome. |
| `page` | `int` | Starting page (default `1`). |

Multi-value filters are joined by the underlying API.

### Contributing

Contributions are welcome. To set up a local dev environment and run the tests:

```bash
git clone https://github.com/MuhammadOmarMuhdhar/pykenyalaw.git
cd pykenyalaw
pip install -e ".[dev]"
python -m pytest
```

Tests hit the live kenyalaw.org API, so they need network access and should pass without any setup. If they fail, the upstream API may have changed - a scheduled job ([`api-alive.yml`](.github/workflows/api-alive.yml)) runs them daily to catch that early.

Please open an issue or pull request to report bugs, feature ideas, or improvements at [the issue tracker](https://github.com/MuhammadOmarMuhdhar/pykenyalaw/issues).

## License

ISC — see https://opensource.org/licenses/ISC
