Metadata-Version: 2.5
Name: aveecare
Version: 0.1.0
Summary: Official Python library for the AveeCare API: patients, visits, caregivers and billing for home care agencies.
Project-URL: Homepage, https://www.aveecare.com/docs/api
Project-URL: Documentation, https://www.aveecare.com/docs/api
Project-URL: Repository, https://github.com/aveecare/aveecare-python
Project-URL: Issues, https://github.com/aveecare/aveecare-python/issues
Project-URL: Changelog, https://github.com/aveecare/aveecare-python/blob/main/CHANGELOG.md
Author: AveeCare
License-Expression: MIT
License-File: LICENSE
Keywords: EVV,HIPAA,api,aveecare,caregiver scheduling,healthcare API,home care,home care software,home health,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.23.0
Provides-Extra: dev
Requires-Dist: build>=1; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Description-Content-Type: text/markdown

# AveeCare Python Library

[![PyPI version](https://img.shields.io/pypi/v/aveecare.svg)](https://pypi.org/project/aveecare/)
[![Python versions](https://img.shields.io/pypi/pyversions/aveecare.svg)](https://pypi.org/project/aveecare/)
[![CI](https://github.com/aveecare/aveecare-python/actions/workflows/ci.yml/badge.svg)](https://github.com/aveecare/aveecare-python/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/aveecare/aveecare-python/blob/main/LICENSE)

The official Python library for the [AveeCare API](https://www.aveecare.com/docs/api).
Read and write your home care agency's patients, visits, invoices and more from your own
servers, with typed models, sync and async clients, automatic pagination, retries and
idempotency built in.

- Python 3.9+, one dependency ([httpx](https://www.python-httpx.org/))
- Sync `AveeCare` and async `AsyncAveeCare` clients
- Typed models (`py.typed`), typed errors, automatic retries and idempotency keys

## Install

```sh
pip install aveecare
```

## Quickstart

Create an API key in AveeCare, then:

```python
import os

from aveecare import AveeCare

client = AveeCare(api_key=os.environ["AVEECARE_API_KEY"])

page = client.patients.list(status="Active", limit=25)
for patient in page.data:
    print(patient.id, patient.first_name, patient.last_name)
```

## Authentication

Every request is authenticated with your secret API key, sent as
`Authorization: Bearer ak_<keyId>_<secret>`. Pass it as `api_key`, or set the
`AVEECARE_API_KEY` environment variable and call `AveeCare()`. Keys are
read-only or read and write; see
[Authentication](https://www.aveecare.com/docs/api/authentication).

Keep keys on your server. Never put an API key in browser or mobile code.

## Usage

```python
# Retrieve, create, update and delete
patient = client.patients.retrieve("pat_8f2k1m9x")
created = client.patients.create(first_name="Margaret", last_name="Alvarez")
updated = client.patients.update(created.id, scheduling_notes="Prefers morning visits", email=None)
client.patients.delete(created.id)

# Visits are listed by start-time window (at most 93 days)
visits = client.visits.list(start_from="2026-10-01T00:00:00Z", start_to="2026-10-08T00:00:00Z")

# The API key making the request
me = client.me.retrieve()
```

Attributes and arguments are snake_case (`first_name`, `created_at`); the
library maps them to the API's camelCase JSON. On updates, passing `None`
clears a field, and leaving an argument out leaves the field unchanged.
`patient.raw` holds the JSON exactly as the API returned it, and
`patient.to_dict()` converts a model back to API JSON.

### Async

```python
import asyncio

from aveecare import AsyncAveeCare


async def main() -> None:
    async with AsyncAveeCare() as client:
        page = await client.patients.list(limit=25)
        async for patient in client.patients.list(status="Active"):
            print(patient.id)


asyncio.run(main())
```

## Pagination

`list()` returns the first page. Iterating the page walks every item across
every page, fetching more as needed:

```python
for patient in client.patients.list(limit=100):
    print(patient.id)

# Or one page at a time
page = client.patients.list(limit=25)
while page.has_next_page():
    page = page.get_next_page()
```

## Errors

Every error is an `AveeCareError`. API errors carry `status`, `code`, `type`,
`message` and `request_id`:

```python
from aveecare import AveeCareError, NotFoundError

try:
    client.patients.retrieve("pat_missing")
except NotFoundError as err:
    print("No such patient", err.request_id)
except AveeCareError as err:
    print(err.status, err.code, err.message)
```

| Status | Class | Example codes |
|---|---|---|
| 400 | `InvalidRequestError` | `invalid_request`, `unknown_field` |
| 401 | `AuthenticationError` | `unauthorized` |
| 403 | `PermissionError` | `forbidden`, `insufficient_scope` |
| 404 | `NotFoundError` | `not_found` |
| 409 | `ConflictError` | `idempotency_conflict` |
| 429 | `RateLimitError` | `rate_limited` |
| other | `APIError` | `internal_error` |

Network failures raise `APIConnectionError`, and timeouts `APITimeoutError`.

## Retries, timeouts and idempotency

Rate-limited (429), server error (5xx) and network failures are retried twice
by default with jittered exponential backoff. When the API sends
`Retry-After`, the client waits that long.

Every `create` sends an `Idempotency-Key` (a random UUID), and the same key is
reused across retries, so a retried create never makes a duplicate. Pass your
own key to make a create safe to repeat across processes:

```python
client = AveeCare(max_retries=4, timeout=20.0)

client.patients.create(
    first_name="Margaret",
    last_name="Alvarez",
    idempotency_key="import-row-1042",
    timeout=5.0,
)
```

## Configuration

| Argument | Default | |
|---|---|---|
| `api_key` | `AVEECARE_API_KEY` | Your secret key |
| `base_url` | `AVEECARE_BASE_URL`, then `https://api.aveecare.com` | API origin |
| `timeout` | `60.0` | Seconds per attempt |
| `max_retries` | `2` | Retries for 429, 5xx and network errors |
| `default_headers` | none | Headers sent with every request |
| `http_client` | a new `httpx.Client` | Your own client (proxies, transports) |

Every request sends `User-Agent: aveecare-python/<version>`.

## Documentation

The full API reference, with every resource and field, is at
[www.aveecare.com/docs/api](https://www.aveecare.com/docs/api).
Building an integration to offer other agencies? See the
[AveeCare Partner Center](https://www.aveecare.com/partners).

## Other official SDKs

- [aveecare-node](https://github.com/aveecare/aveecare-node): Node.js and TypeScript
- [aveecare-python](https://github.com/aveecare/aveecare-python): Python
- [aveecare-rust](https://github.com/aveecare/aveecare-rust): Rust
- [aveecare-go](https://github.com/aveecare/aveecare-go): Go
- [aveecare-ruby](https://github.com/aveecare/aveecare-ruby): Ruby
- [aveecare-php](https://github.com/aveecare/aveecare-php): PHP
- [aveecare-java](https://github.com/aveecare/aveecare-java): Java and Kotlin
- [aveecare-dotnet](https://github.com/aveecare/aveecare-dotnet): .NET
- [aveecare-cli](https://github.com/aveecare/aveecare-cli): command line
- [aveecare-openapi](https://github.com/aveecare/aveecare-openapi): OpenAPI specification
- [aveecare-mcp](https://github.com/aveecare/aveecare-mcp): connect AI assistants
- [aveecare-examples](https://github.com/aveecare/aveecare-examples): sample apps

## License

MIT. See [LICENSE](https://github.com/aveecare/aveecare-python/blob/main/LICENSE).

---

Built by [AveeCare](https://www.aveecare.com) — home care software.
