Metadata-Version: 2.4
Name: jh-helpers
Version: 0.2.0
Summary: Typed, dependency-light helpers for Jacaranda Health applications
Project-URL: Homepage, https://github.com/Jacaranda-Health/jh-helpers
Project-URL: Repository, https://github.com/Jacaranda-Health/jh-helpers
Project-URL: Issues, https://github.com/Jacaranda-Health/jh-helpers/issues
Project-URL: Changelog, https://github.com/Jacaranda-Health/jh-helpers/blob/main/CHANGELOG.md
Author-email: JH Dev <dev@jacarandahealth.org>
License-Expression: MIT
License-File: LICENSE
Keywords: county-matching,jacaranda-health,messaging,pregnancy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jhlogger
Requires-Dist: nltk
Requires-Dist: pendulum
Description-Content-Type: text/markdown

# jh-helpers

`jh-helpers` is a small, typed Python library of pure Jacaranda Health helper
logic. It packages the scoped pregnancy, message, and county-matching behavior
previously maintained in application code.

## Requirements and installation

Python 3.11 or newer is supported.

```bash
uv add jh-helpers
# or
python -m pip install jh-helpers
```

For a source checkout, `uv` is the source of truth for dependencies:

```bash
uv sync --all-groups
make requirements  # regenerates requirements*.txt from uv.lock
```

Pip users can install generated runtime requirements with
`pip install -r requirements.txt`; the library itself is deliberately omitted
from both exported requirement files.

## Public API

```python
from jh_helpers import (
    CountyMatcher,
    calculate_pregnancy,
    estimate_groups,
    match_county,
    split_message_text,
)

pregnancy = calculate_pregnancy(
    {"anc_pnc_status": "ANC", "edd": "2026-11-01", "datetime": "2026-07-01"},
    use_message_date=True,
)
groups = estimate_groups(pregnancy_result=pregnancy)
chunks = split_message_text("Hello. How are you?", max_length=160)
county = CountyMatcher("022", country="Kenya").match_county()
same_county = match_county("mombasa", ["Mombasa County", "Nairobi"])
```

Domain-level APIs are available from `jh_helpers.pregnancy`,
`jh_helpers.messages`, and `jh_helpers.counties`.

## Behavior and compatibility

- Pregnancy calculations retain ANC/PNC input priority, partial date parsing,
  display formats, validation flags, and group-estimation behavior.
- Message field helpers return shallow copies where the source behavior did,
  and preserve arbitrary loose payload shapes.
- Splitting prefers sentence boundaries and lazily downloads NLTK's
  `punkt_tab` resource if unavailable. A single overlong word remains one
  overlong chunk by design.
- County matching supports Kenya's canonical data and codes. Ghana and `None`
  matchers are exposed but intentionally inactive. Canonical Kenya output uses
  `Homabay`, matching the source data.
- This library is intentionally not a `lib.*` compatibility package. Import
  it through `jh_helpers`.

See `docs/` for payload and matching details.

## Typing and logging

The package ships `py.typed` and annotations for public APIs. Runtime inputs
remain permissive for parity with the originating helpers.

Only the message splitter emits a best-effort event when it must acquire the
NLTK tokenizer resource. It uses the available `jhlogger` integration without
configuring handlers, sinks, levels, CloudWatch, Sentry, telemetry, or global
application context. Applications own all logging configuration.

## Development

```bash
make lint
make format-check
make type-check
make test
make build
```

## Publishing

Release preparation and PyPI/TestPyPI trusted-publishing setup are documented
in [`docs/publishing.md`](docs/publishing.md). The local distribution checks
are available with:

```bash
make dist-check
```
