Metadata-Version: 2.4
Name: socialhome-client
Version: 2026.5.11
Summary: Async HTTP + WebSocket client for Social Home, used by the Home Assistant integration.
Project-URL: Homepage, https://github.com/social-home-io/socialhome-client
Project-URL: Repository, https://github.com/social-home-io/socialhome-client
Project-URL: Issues, https://github.com/social-home-io/socialhome-client/issues
Author-email: Pascal Vizeli <pascal.vizeli@nabucasa.com>
License: Mozilla Public License 2.0
License-File: LICENSE
Keywords: client,home-assistant,social-home
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: aiohttp>=3.9
Provides-Extra: dev
Requires-Dist: aioresponses>=0.7; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# socialhome-client

Async HTTP + WebSocket client for [Social Home](https://github.com/social-home-io/core),
published to PyPI as `socialhome-client` and consumed by the
[Home Assistant integration](https://github.com/social-home-io/ha-integration).

Never imports from `social_home` (core). Safe to install inside Home
Assistant Core, which runs on Python 3.13.

## Install

```sh
pip install socialhome-client
```

## Use

The client groups methods under feature resources — e.g. `c.me.get()`,
`c.shopping.add(...)`, `c.bot.create(...)` — rather than a flat surface.

```python
import asyncio

from socialhome_client import SocialHomeClient, SocialHomeWsManager


async def main() -> None:
    async with SocialHomeClient("http://homeassistant.local:8099", token="…") as sh:
        me = await sh.me.get()
        print(me.display_name)

        await sh.shopping.add("milk")
        events = await sh.calendar.list_events("cal-1", "2026-05-01", "2026-06-01")
        print(f"{len(events)} events this month")

        ws = SocialHomeWsManager(sh)
        await ws.connect()
        ws.register(
            ["post_created"],
            lambda frame: asyncio.sleep(0, print(frame)),
        )


asyncio.run(main())
```

### Bots

Home Assistant automations can post into a space feed through the
bot-bridge. Each bot has its own Bearer token (shown once on create)
and posts render with the bot's icon + name instead of a generic
"Home Assistant" avatar.

```python
# Admin turns on bot posting for the space, then registers a household bot.
await sh.space.update(space_id, bot_enabled=True)
bot = await sh.bot.create(
    space_id, scope="space", slug="doorbell",
    name="Doorbell", icon="🔔",
)

# Persist bot.token somewhere safe — the backend will not show it again.
await sh.bot.post(
    space_id, bot.token,
    title="Ring", message="Front door",
)
```

## Develop

```sh
pip install -e .[dev]
pre-commit install
pytest
```

## Documentation

- [`docs/principles.md`](docs/principles.md) — design principles
  (standalone of core, async everywhere, typed responses).
- [`docs/architecture.md`](docs/architecture.md) — HTTP client +
  feature resources, WebSocket manager, models, exceptions.
- [`docs/testing.md`](docs/testing.md) — test strategy, 85 %
  coverage gate, `aioresponses` + fake-WS patterns.
- [`CLAUDE.md`](CLAUDE.md), [`AGENTS.md`](AGENTS.md) — guidance for
  AI assistants working in this repo.

## License

[Mozilla Public License 2.0](LICENSE).
