aiobirdnetgo 0.1.0__tar.gz

aiobirdnetgo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hamish West
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiobirdnetgo-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: aiobirdnetgo
+Version: 0.1.0
+Summary: Asynchronous Python client for the BirdNET-Go REST and SSE API
+Author-email: Hamish West <hamish@hamishwest.xyz>
+License: MIT
+Project-URL: Homepage, https://github.com/tphakala/birdnet-go
+Project-URL: Repository, https://github.com/tphakala/aiobirdnetgo
+Project-URL: Bug Tracker, https://github.com/tphakala/aiobirdnetgo/issues
+Keywords: birdnet,birdnet-go,homeassistant,audio,ai,birds
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: mypy>=1.9.0; extra == "dev"
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Dynamic: license-file
+
+# aiobirdnetgo
+
+[![PyPI version](https://img.shields.io/pypi/v/aiobirdnetgo.svg)](https://pypi.org/project/aiobirdnetgo/)
+[![Python versions](https://img.shields.io/pypi/pyversions/aiobirdnetgo.svg)](https://pypi.org/project/aiobirdnetgo/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Asynchronous Python client library for the [BirdNET-Go](https://github.com/tphakala/birdnet-go) REST API and real-time Server-Sent Events (SSE) streaming.
+
+Designed primarily for integration with **Home Assistant Core** and other Python asyncio applications.
+
+---
+
+## Features
+
+- ⚡ **Asynchronous:** Built entirely on top of `aiohttp` and `asyncio`.
+- 🔍 **Type-Safe:** Frozen dataclasses with full typing support (`py.typed`).
+- 🐦 **Real-Time Detection Streaming:** Built-in SSE listener with automatic reconnection and heartbeat handling.
+- 📊 **Dashboard KPIs & Analytics:** Fetch daily species summaries, lifetime statistics, and detection streaks.
+- 🎙️ **Multi-Source Audio:** Discovers and maps audio devices and RTSP stream sources.
+- 🎛️ **Engine Control:** Restart analysis engine or reload classifier models remotely.
+
+---
+
+## Installation
+
+```bash
+pip install aiobirdnetgo
+```
+
+---
+
+## Quickstart
+
+### Basic API Usage & KPIs
+
+```python
+import asyncio
+from aiobirdnetgo import BirdNetGoClient
+
+
+async def main():
+    async with BirdNetGoClient(host="192.168.1.50", port=8080) as client:
+        # Check connectivity
+        if await client.ping():
+            print("Connected to BirdNET-Go!")
+
+        # Get system health
+        health = await client.get_health()
+        print(f"Version: {health.version}, Status: {health.status}")
+
+        # Get dashboard headline KPIs
+        kpis = await client.get_kpis()
+        print(f"Today's detections: {kpis.today_detections}")
+        print(f"Lifetime species count: {kpis.lifetime_species}")
+        print(f"Current streak: {kpis.detection_streak.days} days")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+### Real-Time Detection Streaming (SSE)
+
+```python
+import asyncio
+from aiobirdnetgo import BirdNetGoClient
+
+
+async def main():
+    async with BirdNetGoClient(host="192.168.1.50", port=8080) as client:
+        print("Listening for live bird detections...")
+
+        stream = client.stream_detections()
+        async for detection in stream:
+            print(f"🐦 Detected: {detection.common_name} ({detection.scientific_name})")
+            print(f"   Confidence: {detection.confidence * 100:.1f}%")
+            print(f"   Source: {detection.source_name or detection.source_id}")
+            if detection.bird_image:
+                print(f"   Photo: {client.get_species_image_url(detection.scientific_name)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+### Managing Audio Sources & Recent Detections
+
+```python
+import asyncio
+from aiobirdnetgo import BirdNetGoClient
+
+
+async def main():
+    async with BirdNetGoClient(host="192.168.1.50", port=8080) as client:
+        # List audio sources (sound cards & RTSP streams)
+        sources = await client.get_audio_sources()
+        for source in sources:
+            print(f"Source: {source.name} (ID: {source.id}, State: {source.state})")
+
+        # Fetch recent detections
+        detections = await client.get_recent_detections(limit=10)
+        for det in detections:
+            print(f"{det.time} - {det.common_name} ({det.confidence * 100:.0f}%)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## Development & Testing
+
+```bash
+# Clone the repository
+git clone https://github.com/tphakala/aiobirdnetgo.git
+cd aiobirdnetgo
+
+# Install dependencies and dev tools
+pip install -e ".[dev]"
+
+# Run linter and type checker
+ruff check .
+mypy src tests
+
+# Run unit tests with coverage
+pytest
+```

aiobirdnetgo-0.1.0/README.md

@@ -0,0 +1,132 @@
+# aiobirdnetgo
+
+[![PyPI version](https://img.shields.io/pypi/v/aiobirdnetgo.svg)](https://pypi.org/project/aiobirdnetgo/)
+[![Python versions](https://img.shields.io/pypi/pyversions/aiobirdnetgo.svg)](https://pypi.org/project/aiobirdnetgo/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Asynchronous Python client library for the [BirdNET-Go](https://github.com/tphakala/birdnet-go) REST API and real-time Server-Sent Events (SSE) streaming.
+
+Designed primarily for integration with **Home Assistant Core** and other Python asyncio applications.
+
+---
+
+## Features
+
+- ⚡ **Asynchronous:** Built entirely on top of `aiohttp` and `asyncio`.
+- 🔍 **Type-Safe:** Frozen dataclasses with full typing support (`py.typed`).
+- 🐦 **Real-Time Detection Streaming:** Built-in SSE listener with automatic reconnection and heartbeat handling.
+- 📊 **Dashboard KPIs & Analytics:** Fetch daily species summaries, lifetime statistics, and detection streaks.
+- 🎙️ **Multi-Source Audio:** Discovers and maps audio devices and RTSP stream sources.
+- 🎛️ **Engine Control:** Restart analysis engine or reload classifier models remotely.
+
+---
+
+## Installation
+
+```bash
+pip install aiobirdnetgo
+```
+
+---
+
+## Quickstart
+
+### Basic API Usage & KPIs
+
+```python
+import asyncio
+from aiobirdnetgo import BirdNetGoClient
+
+
+async def main():
+    async with BirdNetGoClient(host="192.168.1.50", port=8080) as client:
+        # Check connectivity
+        if await client.ping():
+            print("Connected to BirdNET-Go!")
+
+        # Get system health
+        health = await client.get_health()
+        print(f"Version: {health.version}, Status: {health.status}")
+
+        # Get dashboard headline KPIs
+        kpis = await client.get_kpis()
+        print(f"Today's detections: {kpis.today_detections}")
+        print(f"Lifetime species count: {kpis.lifetime_species}")
+        print(f"Current streak: {kpis.detection_streak.days} days")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+### Real-Time Detection Streaming (SSE)
+
+```python
+import asyncio
+from aiobirdnetgo import BirdNetGoClient
+
+
+async def main():
+    async with BirdNetGoClient(host="192.168.1.50", port=8080) as client:
+        print("Listening for live bird detections...")
+
+        stream = client.stream_detections()
+        async for detection in stream:
+            print(f"🐦 Detected: {detection.common_name} ({detection.scientific_name})")
+            print(f"   Confidence: {detection.confidence * 100:.1f}%")
+            print(f"   Source: {detection.source_name or detection.source_id}")
+            if detection.bird_image:
+                print(f"   Photo: {client.get_species_image_url(detection.scientific_name)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+### Managing Audio Sources & Recent Detections
+
+```python
+import asyncio
+from aiobirdnetgo import BirdNetGoClient
+
+
+async def main():
+    async with BirdNetGoClient(host="192.168.1.50", port=8080) as client:
+        # List audio sources (sound cards & RTSP streams)
+        sources = await client.get_audio_sources()
+        for source in sources:
+            print(f"Source: {source.name} (ID: {source.id}, State: {source.state})")
+
+        # Fetch recent detections
+        detections = await client.get_recent_detections(limit=10)
+        for det in detections:
+            print(f"{det.time} - {det.common_name} ({det.confidence * 100:.0f}%)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## Development & Testing
+
+```bash
+# Clone the repository
+git clone https://github.com/tphakala/aiobirdnetgo.git
+cd aiobirdnetgo
+
+# Install dependencies and dev tools
+pip install -e ".[dev]"
+
+# Run linter and type checker
+ruff check .
+mypy src tests
+
+# Run unit tests with coverage
+pytest
+```

aiobirdnetgo-0.1.0/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aiobirdnetgo"
+version = "0.1.0"
+description = "Asynchronous Python client for the BirdNET-Go REST and SSE API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [
+    { name = "Hamish West", email = "hamish@hamishwest.xyz" },
+]
+keywords = ["birdnet", "birdnet-go", "homeassistant", "audio", "ai", "birds"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiohttp>=3.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.1.0",
+    "mypy>=1.9.0",
+    "ruff>=0.3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/tphakala/birdnet-go"
+Repository = "https://github.com/tphakala/aiobirdnetgo"
+"Bug Tracker" = "https://github.com/tphakala/aiobirdnetgo/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aiobirdnetgo = ["py.typed"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "--cov=aiobirdnetgo --cov-report=term-missing"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "ASYNC", # flake8-async
+    "T20", # flake8-print
+    "SIM", # flake8-simplify
+    "RUF", # ruff-specific rules
+]
+ignore = []
+
+[tool.ruff.lint.isort]
+known-first-party = ["aiobirdnetgo"]

aiobirdnetgo-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aiobirdnetgo-0.1.0/src/aiobirdnetgo/__init__.py

@@ -0,0 +1,83 @@
+"""Asynchronous Python client for BirdNET-Go."""
+
+from __future__ import annotations
+
+from .client import BirdNetGoClient
+from .const import (
+    DEFAULT_PORT,
+    DEFAULT_RECONNECT_INTERVAL,
+    DEFAULT_SSE_TIMEOUT,
+    DEFAULT_TIMEOUT,
+    MAX_RECONNECT_INTERVAL,
+    SSE_EVENT_AUDIO_LEVEL,
+    SSE_EVENT_CONNECTED,
+    SSE_EVENT_DETECTION,
+    SSE_EVENT_HEARTBEAT,
+    SSE_EVENT_PENDING,
+)
+from .exceptions import (
+    BirdNetGoAuthenticationError,
+    BirdNetGoConnectionError,
+    BirdNetGoError,
+    BirdNetGoNotFoundError,
+    BirdNetGoResponseError,
+    BirdNetGoTimeoutError,
+)
+from .models import (
+    AudioLevelEvent,
+    AudioLevelItem,
+    AudioSource,
+    BestDayInfo,
+    BirdImageInfo,
+    DashboardKPIs,
+    DatabaseHealth,
+    Detection,
+    HealthResponse,
+    PingResponse,
+    SpeciesDailySummary,
+    SpeciesSummary,
+    StreakInfo,
+    SystemInfo,
+    WeatherInfo,
+)
+from .stream import AudioLevelStream, DetectionStream, SSEMessage
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_PORT",
+    "DEFAULT_RECONNECT_INTERVAL",
+    "DEFAULT_SSE_TIMEOUT",
+    "DEFAULT_TIMEOUT",
+    "MAX_RECONNECT_INTERVAL",
+    "SSE_EVENT_AUDIO_LEVEL",
+    "SSE_EVENT_CONNECTED",
+    "SSE_EVENT_DETECTION",
+    "SSE_EVENT_HEARTBEAT",
+    "SSE_EVENT_PENDING",
+    "AudioLevelEvent",
+    "AudioLevelItem",
+    "AudioLevelStream",
+    "AudioSource",
+    "BestDayInfo",
+    "BirdImageInfo",
+    "BirdNetGoAuthenticationError",
+    "BirdNetGoClient",
+    "BirdNetGoConnectionError",
+    "BirdNetGoError",
+    "BirdNetGoNotFoundError",
+    "BirdNetGoResponseError",
+    "BirdNetGoTimeoutError",
+    "DashboardKPIs",
+    "DatabaseHealth",
+    "Detection",
+    "DetectionStream",
+    "HealthResponse",
+    "PingResponse",
+    "SSEMessage",
+    "SpeciesDailySummary",
+    "SpeciesSummary",
+    "StreakInfo",
+    "SystemInfo",
+    "WeatherInfo",
+]