Metadata-Version: 2.4
Name: jp-diet-search
Version: 0.2.0
Summary: Python client & CLI for the National Diet Library Minutes Search API (国会会議録検索システム)
Project-URL: Homepage, https://kokkai.ndl.go.jp/
Project-URL: Documentation, https://jp-diet-search.readthedocs.io/
Project-URL: Repository, https://github.com/yeiichi/jp-diet-search
Project-URL: Issues, https://github.com/yeiichi/jp-diet-search/issues
Project-URL: Source, https://github.com/yeiichi/jp-diet-search
Author-email: Eiichi Yamamoto <info@yeiichi.com>
License-Expression: MIT
License-File: LICENSE
Keywords: API,Diet,Japan,Kokkai,National Diet Library,minutes,parliament,search
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.7.0
Requires-Dist: requests>=2.31.0
Provides-Extra: docs
Requires-Dist: furo>=2024.8.6; extra == 'docs'
Requires-Dist: sphinx<10,>=8; extra == 'docs'
Description-Content-Type: text/markdown

# jp-diet-search

[![PyPI](https://img.shields.io/pypi/v/jp-diet-search.svg)](https://pypi.org/project/jp-diet-search/)
[![Python](https://img.shields.io/pypi/pyversions/jp-diet-search.svg)](https://pypi.org/project/jp-diet-search/)
[![License](https://img.shields.io/pypi/l/jp-diet-search.svg)](LICENSE)


Python client for the National Diet Library **Kokkai Kaigiroku Kensaku System**
(国会会議録検索システム).

This package provides:

- A **plain-vanilla Object API** for programmatic access
- Robust error handling and safe pagination
- No heavy dependencies or hidden magic

---

## Features

### Python Object API

- Explicit endpoint objects:
  - `client.meeting_list`
  - `client.meeting`
  - `client.speech`
- Typed query objects (`MeetingListQuery`, `MeetingQuery`, `SpeechQuery`)
- Automatic pagination with optional total caps
- Optional on-disk caching

---

## Installation

For development:

```bash
uv sync --group dev
```

For normal use (after PyPI release):

```bash
pip install jp-diet-search
```

---

## Development Workflow

```bash
uv sync --group dev        # Install development dependencies
uv run python -m compileall src
uv run --group dev pytest
```

---

## Python API (Object API)

### Basic usage

```python
from jp_diet_search import DietClient
from jp_diet_search.queries import SpeechQuery

client = DietClient(cache_dir=".cache")

query = SpeechQuery(
    any="科学技術",
    maximum_records=100,
)

result = client.speech.search(query, limit_total=5)

print(result["numberOfRecords"])
for record in result.get("records", []):
    print(record.get("speaker"), record.get("date"))
```

### Endpoint overview

```python
client.meeting_list.search(MeetingListQuery(...))
client.meeting.search(MeetingQuery(...))
client.speech.search(SpeechQuery(...))
```

Returned values are **raw JSON dictionaries** aggregated across pages.

---

## Project Structure

```
jp-diet-search/
  src/
    jp_diet_search/
      __init__.py
      client.py
      core.py
      endpoints.py
      queries.py
      cli.py
      exceptions.py
      models.py   # reserved (currently unused)
  tests/
  README.md
  pyproject.toml
  Makefile
```

---

## Design Notes

- The public API avoids `**kwargs` bags in favor of explicit query objects.
- Internal HTTP and pagination logic lives in a dedicated core layer.
- `models.py` is intentionally unused for now; responses are returned as raw JSON.
- Console scripts are the primary execution model (no `python -m` required).

---

## License

MIT License.
