nuasense 0.1.0__tar.gz

nuasense-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/

nuasense-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 (2026-11-16)
+
+- `send_reading()`: one reading from any station you build (temperature, humidity, pressure, wind, rain total, solar or light), no API key, only the station token. Same upload and PASSKEY as the Node-RED, ioBroker and n8n packages.
+- `Client`: `first_look()` (frost tonight, watering today, spray window, plausibility), `stations()`, `catalog()`, `dataset()` / `rows()` for the farm and market datasets, `analysis()` for the ready-made analyses.
+- Standard library only; Python 3.9 or newer.

nuasense-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NuaSense <info@nuasense.com>
+
+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.

nuasense-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: nuasense
+Version: 0.1.0
+Summary: NuaSense for Python: frost, watering and spray advice from your weather station, sending readings from any station you build, and East African farm and market data.
+Project-URL: Homepage, https://nuasense.com
+Project-URL: Documentation, https://api.nuasense.com/index.md
+Project-URL: Source, https://github.com/nuasense/nuasense-python
+Project-URL: Issues, https://github.com/nuasense/nuasense-python/issues
+Project-URL: Changelog, https://github.com/nuasense/nuasense-python/blob/main/CHANGELOG.md
+Author-email: NuaSense <info@nuasense.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agriculture,east-africa,ecowitt,frost-warning,irrigation,kenya,market-data,raspberry-pi,weather-station
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# nuasense
+
+NuaSense for Python: what your weather station means for house, garden and farm. Frost tonight, how much to water today, the next calm and dry spray window, and a plausibility check of your sensor. Send readings from any station you build (a Raspberry Pi with a BME280, an ESP32, a rain gauge on a GPIO pin), and read East African farm and market data.
+
+```
+pip install nuasense
+```
+
+Standard library only, Python 3.9 or newer, so it runs on any Raspberry Pi.
+
+## Send readings from your own station
+
+In the console at [platform.nuasense.com](https://platform.nuasense.com): **External stations → Add a station**, pick *Home Assistant / weewx / Meteobridge / Node-RED*, and copy the token after `/station/` on the last screen. Sending needs no API key. The first three stations on an account are free.
+
+```python
+import nuasense
+
+nuasense.send_reading(
+    "kw7n-4hpd-x2vt",        # your station token
+    device_id="garden-pi",   # any stable name for this device
+    temperature=21.4,        # °C
+    humidity=63,             # %
+    pressure=1013.2,         # hPa
+    wind_speed=2.1,          # m/s (wind_unit="kmh" for km/h)
+    wind_direction=270,      # degrees
+    rain_total=12.2,         # mm, a counter that only grows
+    solar=412,               # W/m² (or lux=...)
+)
+```
+
+Every value is optional; send what your station measures.
+
+### Raspberry Pi with a BME280
+
+```python
+import time
+
+import board
+from adafruit_bme280 import basic as adafruit_bme280  # pip install adafruit-circuitpython-bme280
+
+import nuasense
+
+TOKEN = "kw7n-4hpd-x2vt"
+bme = adafruit_bme280.Adafruit_BME280_I2C(board.I2C())
+
+while True:
+    nuasense.send_reading(
+        TOKEN,
+        device_id="garden-pi",
+        temperature=bme.temperature,
+        humidity=bme.relative_humidity,
+        pressure=bme.pressure,
+    )
+    time.sleep(300)
+```
+
+## What your station means: frost, watering, spray window
+
+Reading needs an API key: in the console under **API Keys**, verify your phone (a code by SMS or WhatsApp), then create a key. It is shown once. Keep it in an environment variable, not in your code.
+
+```python
+import nuasense
+
+ns = nuasense.Client()   # reads NUASENSE_API_KEY
+
+for station in ns.stations()["stations"]:
+    print(station["station_id"], station["name"], station["last_seen_at"])
+
+look = ns.first_look("garden-west")      # a station_id from stations() or the console
+print(look["tonight"]["frost"], look["tonight"]["low_c"])   # e.g. "none", 7.8
+print(look["garden"]["watering"]["need_mm"]["lawn"])        # mm to water today
+```
+
+The watering need already subtracts the rain of the last 24 hours and the rain forecast for the next 24 hours, so on a day with rain coming it is 0.
+
+## Farm and market data
+
+```python
+ns = nuasense.Client()
+
+ns.catalog()   # every dataset, its fields and filters your key reaches
+
+prices = ns.rows("/market/prices", start="-14d", county="nakuru", commodity="maize")
+
+import pandas as pd       # optional
+df = pd.DataFrame(prices)
+
+ns.analysis("/fertilizer/rank", county="nakuru")   # where fertilizer is cheapest
+```
+
+`dataset()` returns the whole answer (rows plus what the call cost); `rows()` returns only the rows. Options: `start`, `end`, `limit`, `every` with `agg`, `fields`, `oldest_first`; filters as keyword arguments.
+
+Market data needs no station. The datasets cover Kenya, Tanzania, Uganda and Rwanda: county crop and input prices, satellite demand, food security, rainfall against normal.
+
+## Errors
+
+Every refusal raises `nuasense.NuaSenseError` with `.status`, `.body` and, on 429, `.retry_after`. The message says what to do: 401 a key, 402 credit, 403 scope or a station that is not yours, 429 wait.
+
+## Your data
+
+When you connect a station, NuaSense stores its readings and computes your forecast, spray windows and risks from them. The readings are used aggregated and anonymised to improve forecasts and models for everyone; they are never passed on individually without your opt-in. You can disconnect the station in the console at any time and have all its data deleted.
+
+## Links
+
+- Docs for developers and agents: https://api.nuasense.com/index.md
+- OpenAPI: https://api.nuasense.com/openapi.json
+- Console: https://platform.nuasense.com
+- Other packages: [Home Assistant](https://github.com/nuasense/homeassistant-nuasense), [Node-RED](https://github.com/nuasense/node-red-contrib-nuasense), [weewx](https://github.com/nuasense/weewx-nuasense), [n8n](https://github.com/nuasense/n8n-nodes-nuasense)
+- Issues: https://github.com/nuasense/nuasense-python/issues · info@nuasense.com
+
+## Development
+
+`python -m unittest discover -s tests` (with `PYTHONPATH=src`). Releases: bump `src/nuasense/_version.py` and `CHANGELOG.md`, push a tag `vX.Y.Z`; GitHub Actions tests, builds and publishes to PyPI by Trusted Publishing.
+
+## License
+
+MIT

nuasense-0.1.0/README.md

@@ -0,0 +1,117 @@
+# nuasense
+
+NuaSense for Python: what your weather station means for house, garden and farm. Frost tonight, how much to water today, the next calm and dry spray window, and a plausibility check of your sensor. Send readings from any station you build (a Raspberry Pi with a BME280, an ESP32, a rain gauge on a GPIO pin), and read East African farm and market data.
+
+```
+pip install nuasense
+```
+
+Standard library only, Python 3.9 or newer, so it runs on any Raspberry Pi.
+
+## Send readings from your own station
+
+In the console at [platform.nuasense.com](https://platform.nuasense.com): **External stations → Add a station**, pick *Home Assistant / weewx / Meteobridge / Node-RED*, and copy the token after `/station/` on the last screen. Sending needs no API key. The first three stations on an account are free.
+
+```python
+import nuasense
+
+nuasense.send_reading(
+    "kw7n-4hpd-x2vt",        # your station token
+    device_id="garden-pi",   # any stable name for this device
+    temperature=21.4,        # °C
+    humidity=63,             # %
+    pressure=1013.2,         # hPa
+    wind_speed=2.1,          # m/s (wind_unit="kmh" for km/h)
+    wind_direction=270,      # degrees
+    rain_total=12.2,         # mm, a counter that only grows
+    solar=412,               # W/m² (or lux=...)
+)
+```
+
+Every value is optional; send what your station measures.
+
+### Raspberry Pi with a BME280
+
+```python
+import time
+
+import board
+from adafruit_bme280 import basic as adafruit_bme280  # pip install adafruit-circuitpython-bme280
+
+import nuasense
+
+TOKEN = "kw7n-4hpd-x2vt"
+bme = adafruit_bme280.Adafruit_BME280_I2C(board.I2C())
+
+while True:
+    nuasense.send_reading(
+        TOKEN,
+        device_id="garden-pi",
+        temperature=bme.temperature,
+        humidity=bme.relative_humidity,
+        pressure=bme.pressure,
+    )
+    time.sleep(300)
+```
+
+## What your station means: frost, watering, spray window
+
+Reading needs an API key: in the console under **API Keys**, verify your phone (a code by SMS or WhatsApp), then create a key. It is shown once. Keep it in an environment variable, not in your code.
+
+```python
+import nuasense
+
+ns = nuasense.Client()   # reads NUASENSE_API_KEY
+
+for station in ns.stations()["stations"]:
+    print(station["station_id"], station["name"], station["last_seen_at"])
+
+look = ns.first_look("garden-west")      # a station_id from stations() or the console
+print(look["tonight"]["frost"], look["tonight"]["low_c"])   # e.g. "none", 7.8
+print(look["garden"]["watering"]["need_mm"]["lawn"])        # mm to water today
+```
+
+The watering need already subtracts the rain of the last 24 hours and the rain forecast for the next 24 hours, so on a day with rain coming it is 0.
+
+## Farm and market data
+
+```python
+ns = nuasense.Client()
+
+ns.catalog()   # every dataset, its fields and filters your key reaches
+
+prices = ns.rows("/market/prices", start="-14d", county="nakuru", commodity="maize")
+
+import pandas as pd       # optional
+df = pd.DataFrame(prices)
+
+ns.analysis("/fertilizer/rank", county="nakuru")   # where fertilizer is cheapest
+```
+
+`dataset()` returns the whole answer (rows plus what the call cost); `rows()` returns only the rows. Options: `start`, `end`, `limit`, `every` with `agg`, `fields`, `oldest_first`; filters as keyword arguments.
+
+Market data needs no station. The datasets cover Kenya, Tanzania, Uganda and Rwanda: county crop and input prices, satellite demand, food security, rainfall against normal.
+
+## Errors
+
+Every refusal raises `nuasense.NuaSenseError` with `.status`, `.body` and, on 429, `.retry_after`. The message says what to do: 401 a key, 402 credit, 403 scope or a station that is not yours, 429 wait.
+
+## Your data
+
+When you connect a station, NuaSense stores its readings and computes your forecast, spray windows and risks from them. The readings are used aggregated and anonymised to improve forecasts and models for everyone; they are never passed on individually without your opt-in. You can disconnect the station in the console at any time and have all its data deleted.
+
+## Links
+
+- Docs for developers and agents: https://api.nuasense.com/index.md
+- OpenAPI: https://api.nuasense.com/openapi.json
+- Console: https://platform.nuasense.com
+- Other packages: [Home Assistant](https://github.com/nuasense/homeassistant-nuasense), [Node-RED](https://github.com/nuasense/node-red-contrib-nuasense), [weewx](https://github.com/nuasense/weewx-nuasense), [n8n](https://github.com/nuasense/n8n-nodes-nuasense)
+- Issues: https://github.com/nuasense/nuasense-python/issues · info@nuasense.com
+
+## Development
+
+`python -m unittest discover -s tests` (with `PYTHONPATH=src`). Releases: bump `src/nuasense/_version.py` and `CHANGELOG.md`, push a tag `vX.Y.Z`; GitHub Actions tests, builds and publishes to PyPI by Trusted Publishing.
+
+## License
+
+MIT

nuasense-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nuasense"
+dynamic = ["version"]
+description = "NuaSense for Python: frost, watering and spray advice from your weather station, sending readings from any station you build, and East African farm and market data."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "NuaSense", email = "info@nuasense.com" }]
+keywords = [
+  "weather-station",
+  "raspberry-pi",
+  "frost-warning",
+  "irrigation",
+  "agriculture",
+  "ecowitt",
+  "east-africa",
+  "kenya",
+  "market-data",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Atmospheric Science",
+  "Topic :: Home Automation",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://nuasense.com"
+Documentation = "https://api.nuasense.com/index.md"
+Source = "https://github.com/nuasense/nuasense-python"
+Issues = "https://github.com/nuasense/nuasense-python/issues"
+Changelog = "https://github.com/nuasense/nuasense-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/nuasense/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nuasense"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/nuasense", "tests", "README.md", "CHANGELOG.md", "LICENSE"]

nuasense-0.1.0/src/nuasense/__init__.py

@@ -0,0 +1,18 @@
+"""NuaSense for Python: what your weather station means for house, garden and
+farm, a way to send any station you build to NuaSense, and East African farm
+and market data.
+
+    import nuasense
+
+    # Send a reading from your own station (no key, only the station token)
+    nuasense.send_reading("kw7n-4hpd-x2vt", temperature=21.4, humidity=63, rain_total=12.2)
+
+    # Read with an API key (or set NUASENSE_API_KEY)
+    ns = nuasense.Client()
+    ns.first_look("my-station-id")
+"""
+
+from ._version import __version__
+from .client import Client, NuaSenseError, send_reading
+
+__all__ = ["Client", "NuaSenseError", "send_reading", "__version__"]

nuasense-0.1.0/src/nuasense/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

nuasense-0.1.0/src/nuasense/client.py

@@ -0,0 +1,243 @@
+"""The NuaSense API from Python: standard library only, so it runs on any Raspberry Pi."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, Optional, Union
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, urlparse
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+from . import ecowitt
+from ._version import __version__
+from .ecowitt import Number, When
+
+API = "https://api.nuasense.com"
+API_HOST = "api.nuasense.com"
+DATA = API + "/api/nuasense/v1"
+ANALYSIS = API + "/api/partner/v1/market"
+KEY_ENV = "NUASENSE_API_KEY"
+TIMEOUT = 30
+
+# Tells NuaSense the call came from this package. Changes nothing in price or limits.
+CLIENT = "python/" + __version__
+USER_AGENT = "nuasense-python/" + __version__
+
+_HINTS = {
+    401: "Missing or invalid key. Create one at https://platform.nuasense.com under API Keys "
+    "and pass it as Client(api_key=...) or set NUASENSE_API_KEY.",
+    402: "This needs credit: history beyond the free 30 days, or prepaid credit spent.",
+    403: "The key lacks the scope, or the station is not yours or not approved for API exposure.",
+    429: "Rate or unit budget reached. Wait for Retry-After or ask with a smaller limit.",
+    451: "This dataset is withheld on licence grounds; no key unlocks it.",
+}
+
+
+class NuaSenseError(Exception):
+    """An answer NuaSense refused, with the HTTP status and the body it sent."""
+
+    def __init__(self, message: str, status: Optional[int] = None, body: Any = None,
+                 retry_after: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+        self.retry_after = retry_after
+
+
+def _body_message(body: Any) -> str:
+    if isinstance(body, dict):
+        for key in ("error", "message", "detail"):
+            value = body.get(key)
+            if isinstance(value, str) and value:
+                return value
+            if isinstance(value, dict) and isinstance(value.get("message"), str):
+                return value["message"]
+    if isinstance(body, str):
+        return body.strip()[:200]
+    return ""
+
+
+class _NoRedirect(HTTPRedirectHandler):
+    """Never follow a redirect: urllib would carry the Authorization header to
+    whatever host the redirect names, and could step down from https. A 3xx
+    comes back as an answer instead."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[override]
+        return None
+
+
+_opener = build_opener(_NoRedirect)
+
+
+def urlopen(req: Request, timeout: float = TIMEOUT):
+    return _opener.open(req, timeout=timeout)
+
+
+def _check_url(url: str) -> None:
+    parts = urlparse(url)
+    if parts.scheme != "https" or parts.hostname != API_HOST:
+        raise ValueError(f"nuasense only talks to {API}; refusing {parts.scheme}://{parts.hostname}")
+
+
+def _http(method: str, url: str, headers: Dict[str, str], data: Optional[bytes] = None,
+          timeout: float = TIMEOUT):
+    """(status, text, headers) for any answer, also 3xx/4xx/5xx. Only https://api.nuasense.com."""
+    _check_url(url)
+    req = Request(url, data=data, method=method, headers=headers)
+    try:
+        with urlopen(req, timeout=timeout) as res:
+            return res.status, res.read().decode("utf-8", "replace"), res.headers
+    except HTTPError as err:
+        try:
+            text = err.read().decode("utf-8", "replace") if err.fp is not None else ""
+        finally:
+            err.close()
+        return err.code, text, err.headers
+    except URLError as err:
+        raise NuaSenseError(f"Could not reach NuaSense: {err.reason}") from err
+
+
+def send_reading(
+    token: str,
+    *,
+    device_id: str = "python",
+    temperature: Optional[Number] = None,
+    humidity: Optional[Number] = None,
+    pressure: Optional[Number] = None,
+    wind_speed: Optional[Number] = None,
+    wind_unit: str = "ms",
+    wind_gusts: Optional[Number] = None,
+    wind_direction: Optional[Number] = None,
+    rain_total: Optional[Number] = None,
+    solar: Optional[Number] = None,
+    lux: Optional[Number] = None,
+    time: When = None,
+    timeout: float = TIMEOUT,
+) -> Dict[str, Any]:
+    """Send one reading from your own station. Needs no API key, only the station token.
+
+    Units: temperature °C, humidity %, pressure hPa, wind m/s (or km/h with
+    wind_unit="kmh"), wind_direction degrees, rain_total mm as a counter that
+    only grows, solar W/m² (or lux). The token is the part after /station/ on
+    the last screen of "Add a station" in the console.
+    """
+    url = ecowitt.upload_url(token)
+    fields = ecowitt.to_ecowitt_fields(
+        device_id=device_id, station_type=CLIENT.replace("/", "_"),
+        temperature=temperature, humidity=humidity, pressure=pressure,
+        wind_speed=wind_speed, wind_unit=wind_unit, wind_gusts=wind_gusts,
+        wind_direction=wind_direction, rain_total=rain_total, solar=solar, lux=lux, time=time,
+    )
+    if not ecowitt.has_values(fields):
+        raise ValueError("Add at least one value to the reading.")
+    status, text, _ = _http(
+        "POST", url,
+        {"Content-Type": "application/x-www-form-urlencoded", "X-NuaSense-Client": CLIENT,
+         "User-Agent": USER_AGENT},
+        ecowitt.encode_form(fields).encode("ascii"), timeout,
+    )
+    if status == 404:
+        raise NuaSenseError(
+            "NuaSense does not know this station token. Copy it again from the console, "
+            "or add the station first.", status, text)
+    if status >= 300:
+        raise NuaSenseError(f"NuaSense refused the reading ({status}): {text.strip()[:200]}", status, text)
+    return {"sent": True, "status": status, "answer": text.strip(), "fields": fields}
+
+
+Params = Dict[str, Union[str, int, float, bool, None]]
+
+
+class Client:
+    """Reads from NuaSense with an API key.
+
+    >>> import nuasense
+    >>> ns = nuasense.Client()            # key from NUASENSE_API_KEY
+    >>> ns.first_look("my-station-id")    # frost tonight, watering today, spray window
+    >>> ns.dataset("/market/prices", start="-14d", county="nakuru", commodity="maize")
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, timeout: float = TIMEOUT,
+                 client_name: Optional[str] = None) -> None:
+        self.api_key = (api_key or os.environ.get(KEY_ENV) or "").strip() or None
+        self.timeout = timeout
+        # Optional: name your tool or agent, e.g. "garden-pi"; shown in your usage, nothing else.
+        self.client_header = CLIENT + (f"; app={client_name}" if client_name else "")
+
+    def __repr__(self) -> str:
+        return f"Client(api_key={'set' if self.api_key else 'missing'})"
+
+    def get(self, url: str, params: Optional[Params] = None) -> Any:
+        """GET a URL under https://api.nuasense.com with the key; returns the parsed JSON.
+        Any other host is refused before the key leaves the machine."""
+        _check_url(url)
+        query = {k: ("true" if v is True else "false" if v is False else v)
+                 for k, v in (params or {}).items() if v is not None and v != ""}
+        if query:
+            url += ("&" if "?" in url else "?") + urlencode(query)
+        headers = {"Accept": "application/json", "X-NuaSense-Client": self.client_header,
+                   "User-Agent": USER_AGENT}
+        if self.api_key:
+            headers["Authorization"] = "Bearer " + self.api_key
+        status, text, res_headers = _http("GET", url, headers, None, self.timeout)
+        try:
+            body: Any = json.loads(text) if text else None
+        except ValueError:
+            body = text
+        if status >= 300:
+            said = _body_message(body)
+            hint = _HINTS.get(status, "")
+            message = f"NuaSense answered {status}" + (f": {said}" if said else "") + (f". {hint}" if hint else "")
+            retry = res_headers.get("Retry-After") if res_headers is not None else None
+            raise NuaSenseError(message, status, body, retry)
+        return body
+
+    # --- your stations -------------------------------------------------------
+
+    def stations(self) -> Any:
+        """The external stations on your account, with when each last sent."""
+        return self.get(DATA + "/ingest/stations")
+
+    def first_look(self, station_id: str) -> Any:
+        """Frost tonight, watering today (mm for lawn, vegetables, beds), the next
+        spray window and a plausibility check of the latest reading."""
+        return self.get(DATA + "/ingest/first-look", {"station_id": station_id})
+
+    # --- datasets and analyses ----------------------------------------------
+
+    def catalog(self) -> Any:
+        """The datasets, fields and filters your key reaches."""
+        return self.get(DATA + "/catalog")
+
+    def dataset(self, path: str, *, start: str = "-24h", limit: int = 50, end: Optional[str] = None,
+                every: Optional[str] = None, agg: Optional[str] = None, fields: Optional[str] = None,
+                oldest_first: bool = False, **filters: Union[str, int, float, None]) -> Any:
+        """Rows from one dataset, e.g. dataset("/market/prices", county="nakuru").
+
+        `path` is a catalog path such as "/market/prices" or "/farm/weather".
+        Filters go as keyword arguments. Returns the API's answer; the rows are
+        under "rows" (pandas: pd.DataFrame(answer["rows"])).
+        """
+        params: Params = {"start": start, "limit": limit, "end": end, "every": every,
+                          "agg": agg or ("mean" if every else None), "fields": fields,
+                          "order": "asc" if oldest_first else None}
+        params.update(filters)
+        return self.get(DATA + _path(path), params)
+
+    def rows(self, path: str, **kwargs: Any) -> list:
+        """Only the rows of dataset(...), as a list of dicts."""
+        answer = self.dataset(path, **kwargs)
+        rows = answer.get("rows") if isinstance(answer, dict) else None
+        return rows if isinstance(rows, list) else []
+
+    def analysis(self, path: str, **params: Union[str, int, float, None]) -> Any:
+        """One of the ready-made analyses, e.g. analysis("/fertilizer/rank", county="nakuru")."""
+        return self.get(ANALYSIS + _path(path), params)
+
+
+def _path(path: str) -> str:
+    p = str(path or "").strip()
+    if not p:
+        raise ValueError('Give a catalog path such as "/market/prices".')
+    return p if p.startswith("/") else "/" + p

nuasense-0.1.0/src/nuasense/ecowitt.py

@@ -0,0 +1,176 @@
+"""Metric readings in, an Ecowitt-format upload out.
+
+NuaSense's station receiver speaks what consumer consoles speak, and the
+Ecowitt format is the richest of them. So this module builds the same form a
+GW2000 console would send: imperial units, rain as a running counter, and a
+PASSKEY that names the device so the receiver can bind the station's path to
+it. Same numbers as the Node-RED, ioBroker and n8n packages, so one device
+keeps one PASSKEY whichever package sends for it.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from datetime import datetime, timezone
+from typing import Dict, Optional, Union
+from urllib.parse import quote
+
+INHG_PER_HPA = 1 / 33.8639
+MPH_PER_MS = 1 / 0.44704
+IN_PER_MM = 1 / 25.4
+# Daylight: 120 lux per W/m² of global radiation, the receiver's own factor
+# used the other way, so a script that only has lux lands on the same number.
+LUX_PER_WM2 = 120
+
+UPLOAD_BASE = "https://api.nuasense.com/station/"
+_TOKEN_RE = re.compile(r"^[a-z0-9-]{12,29}$")
+_META = ("PASSKEY", "stationtype", "dateutc")
+
+Number = Union[int, float]
+When = Union[str, datetime, None]
+
+
+def _num(value: object) -> Optional[float]:
+    if value is None or value == "" or isinstance(value, bool):
+        return None
+    try:
+        n = float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return None
+    return n if math.isfinite(n) else None
+
+
+def _fix(n: float, digits: int) -> str:
+    """Rounded to `digits`, trailing zeros dropped: 29.920 -> "29.92", 500.00 -> "500"."""
+    r = float(f"{n:.{digits}f}")
+    if r == 0:
+        return "0"
+    if r.is_integer():
+        return str(int(r))
+    return repr(r)
+
+
+def _round(n: float) -> int:
+    """JavaScript's Math.round: halves go up, not to even."""
+    return int(math.floor(n + 0.5))
+
+
+def date_utc(when: When = None) -> str:
+    """Ecowitt's `dateutc`: "YYYY-MM-DD HH:MM:SS" in UTC.
+
+    Accepts a datetime or an ISO 8601 string; a time without an offset is
+    local time. Anything unreadable becomes now.
+    """
+    t: Optional[datetime] = None
+    if isinstance(when, datetime):
+        t = when
+    elif isinstance(when, str) and when.strip():
+        text = when.strip()
+        if text.endswith(("Z", "z")):
+            text = text[:-1] + "+00:00"
+        try:
+            t = datetime.fromisoformat(text)
+        except ValueError:
+            t = None
+    if t is None:
+        t = datetime.now(timezone.utc)
+    return t.astimezone(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def passkey_for(device_id: str) -> str:
+    """A stable 32-hex PASSKEY from the device name.
+
+    Four FNV-1a passes with different offsets over the name's UTF-16 code
+    units, exactly like the JavaScript packages. Not a secret and not a
+    security measure; it only has to stay the same for the same device,
+    because the receiver binds a station's path to the first device that
+    uses it.
+    """
+    text = str(device_id or "python")
+    raw = text.encode("utf-16-le")
+    units = [raw[i] | (raw[i + 1] << 8) for i in range(0, len(raw), 2)]
+    out = ""
+    for seed in (0x811C9DC5, 0x01000193, 0x6C62272E, 0x9E3779B9):
+        h = seed
+        for unit in units:
+            h ^= unit
+            h = (h * 0x01000193) & 0xFFFFFFFF
+        out += f"{h:08x}"
+    return out.upper()
+
+
+def to_ecowitt_fields(
+    *,
+    device_id: str,
+    station_type: str,
+    temperature: Optional[Number] = None,
+    humidity: Optional[Number] = None,
+    pressure: Optional[Number] = None,
+    wind_speed: Optional[Number] = None,
+    wind_unit: str = "ms",
+    wind_gusts: Optional[Number] = None,
+    wind_direction: Optional[Number] = None,
+    rain_total: Optional[Number] = None,
+    solar: Optional[Number] = None,
+    lux: Optional[Number] = None,
+    time: When = None,
+) -> Dict[str, str]:
+    """The form fields, as strings, in the order a console sends them.
+
+    Units in: °C, %, hPa, m/s (or km/h with wind_unit="kmh"), degrees,
+    mm as a counter that only grows, W/m² (or lux).
+    """
+    fields: Dict[str, str] = {
+        "PASSKEY": passkey_for(device_id),
+        "stationtype": station_type,
+        "dateutc": date_utc(time),
+    }
+    t = _num(temperature)
+    if t is not None:
+        fields["tempf"] = _fix(t * 9 / 5 + 32, 2)
+    h = _num(humidity)
+    if h is not None:
+        fields["humidity"] = str(_round(h))
+    p = _num(pressure)
+    if p is not None:
+        fields["baromabsin"] = _fix(p * INHG_PER_HPA, 3)
+    to_ms = 1 / 3.6 if wind_unit == "kmh" else 1
+    ws = _num(wind_speed)
+    if ws is not None:
+        fields["windspeedmph"] = _fix(ws * to_ms * MPH_PER_MS, 2)
+    wg = _num(wind_gusts)
+    if wg is not None:
+        fields["windgustmph"] = _fix(wg * to_ms * MPH_PER_MS, 2)
+    wd = _num(wind_direction)
+    if wd is not None:
+        fields["winddir"] = str(_round(math.fmod(math.fmod(wd, 360) + 360, 360)))
+    rain = _num(rain_total)
+    if rain is not None:
+        fields["yearlyrainin"] = _fix(rain * IN_PER_MM, 3)
+    sol = _num(solar)
+    lx = _num(lux)
+    if sol is not None:
+        fields["solarradiation"] = _fix(sol, 2)
+    elif lx is not None:
+        fields["solarradiation"] = _fix(lx / LUX_PER_WM2, 2)
+    return fields
+
+
+def encode_form(fields: Dict[str, str]) -> str:
+    return "&".join(f"{quote(k, safe='')}={quote(v, safe='')}" for k, v in fields.items())
+
+
+def upload_url(token: str) -> str:
+    """The upload URL for a token as the console shows it, e.g. kw7n-4hpd-x2vt."""
+    tok = str(token or "").strip().lower()
+    if not _TOKEN_RE.match(tok):
+        raise ValueError(
+            'The station token looks wrong. Copy it from the last screen of "Add a station" in the console.'
+        )
+    return UPLOAD_BASE + tok
+
+
+def has_values(fields: Dict[str, str]) -> bool:
+    """True when at least one measured value is present."""
+    return any(k not in _META for k in fields)

nuasense-0.1.0/tests/test_client.py

@@ -0,0 +1,150 @@
+import io
+import json
+import os
+import unittest
+from unittest import mock
+from urllib.error import HTTPError, URLError
+from urllib.parse import parse_qs, urlparse
+
+import nuasense
+from nuasense import client as mod
+
+
+class FakeResponse(io.BytesIO):
+    def __init__(self, body, status=200, headers=None):
+        super().__init__(body.encode("utf-8"))
+        self.status = status
+        self.headers = headers or {}
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+
+def answering(*replies):
+    """Patch urlopen; each reply is (status, body) or an exception. Records the requests."""
+    calls = []
+    queue = list(replies)
+
+    def fake(req, timeout=None):
+        calls.append(req)
+        reply = queue.pop(0)
+        if isinstance(reply, Exception):
+            raise reply
+        status, body = reply
+        text = body if isinstance(body, str) else json.dumps(body)
+        if status >= 400:
+            raise HTTPError(req.full_url, status, "error", {"Retry-After": "30"}, io.BytesIO(text.encode()))
+        return FakeResponse(text, status)
+
+    return mock.patch.object(mod, "urlopen", side_effect=fake), calls
+
+
+def query(req):
+    return {k: v[0] for k, v in parse_qs(urlparse(req.full_url).query).items()}
+
+
+class SendReadingTest(unittest.TestCase):
+    def test_posts_the_ecowitt_form_without_a_key(self):
+        patch, calls = answering((200, "OK"))
+        with patch:
+            out = nuasense.send_reading("abcd-efgh-ijkl", device_id="shed", temperature=20, rain_total=1.5)
+        req = calls[0]
+        self.assertEqual(req.full_url, "https://api.nuasense.com/station/abcd-efgh-ijkl")
+        self.assertEqual(req.get_method(), "POST")
+        self.assertIsNone(req.get_header("Authorization"))
+        self.assertEqual(req.get_header("X-nuasense-client"), "python/" + nuasense.__version__)
+        form = parse_qs(req.data.decode())
+        self.assertEqual(form["tempf"], ["68"])
+        self.assertEqual(form["PASSKEY"], [nuasense.ecowitt.passkey_for("shed")])
+        self.assertEqual(form["stationtype"], ["python_" + nuasense.__version__])
+        self.assertTrue(out["sent"])
+
+    def test_unknown_token_is_explained(self):
+        patch, _ = answering((404, "not found"))
+        with patch, self.assertRaisesRegex(nuasense.NuaSenseError, "does not know this station token"):
+            nuasense.send_reading("abcd-efgh-ijkl", temperature=1)
+
+    def test_nothing_to_send_is_refused_before_any_call(self):
+        patch, calls = answering()
+        with patch, self.assertRaisesRegex(ValueError, "at least one value"):
+            nuasense.send_reading("abcd-efgh-ijkl")
+        self.assertEqual(calls, [])
+
+    def test_offline_is_a_nuasense_error(self):
+        patch, _ = answering(URLError("no route"))
+        with patch, self.assertRaisesRegex(nuasense.NuaSenseError, "Could not reach"):
+            nuasense.send_reading("abcd-efgh-ijkl", temperature=1)
+
+
+class ClientTest(unittest.TestCase):
+    def test_key_from_the_environment(self):
+        with mock.patch.dict(os.environ, {"NUASENSE_API_KEY": " nsk_test "}):
+            self.assertEqual(nuasense.Client().api_key, "nsk_test")
+        self.assertNotIn("nsk", repr(nuasense.Client("nsk_secret")))
+
+    def test_first_look(self):
+        patch, calls = answering((200, {"tonight": {"frost": "none"}}))
+        with patch:
+            out = nuasense.Client("k").first_look("st-1")
+        self.assertEqual(out["tonight"]["frost"], "none")
+        self.assertTrue(calls[0].full_url.startswith("https://api.nuasense.com/api/nuasense/v1/ingest/first-look?"))
+        self.assertEqual(query(calls[0]), {"station_id": "st-1"})
+        self.assertEqual(calls[0].get_header("Authorization"), "Bearer k")
+
+    def test_dataset_params_and_rows(self):
+        body = {"dataset": "market/prices", "rows": [{"price": 52}]}
+        patch, calls = answering((200, body), (200, body))
+        ns = nuasense.Client("k")
+        with patch:
+            ns.dataset("market/prices", start="-14d", every="1d", oldest_first=True, county="nakuru", end=None)
+            rows = ns.rows("/market/prices")
+        self.assertEqual(urlparse(calls[0].full_url).path, "/api/nuasense/v1/market/prices")
+        self.assertEqual(query(calls[0]), {"start": "-14d", "limit": "50", "every": "1d", "agg": "mean",
+                                           "order": "asc", "county": "nakuru"})
+        self.assertEqual(rows, [{"price": 52}])
+
+    def test_analysis_path(self):
+        patch, calls = answering((200, {"ok": True}))
+        with patch:
+            nuasense.Client("k").analysis("/fertilizer/rank", county="nakuru")
+        self.assertEqual(urlparse(calls[0].full_url).path, "/api/partner/v1/market/fertilizer/rank")
+
+    def test_refusal_carries_status_body_and_hint(self):
+        patch, _ = answering((429, {"error": "daily unit budget spent"}))
+        with patch, self.assertRaises(nuasense.NuaSenseError) as caught:
+            nuasense.Client("k").catalog()
+        err = caught.exception
+        self.assertEqual(err.status, 429)
+        self.assertEqual(err.retry_after, "30")
+        self.assertIn("daily unit budget spent", str(err))
+        self.assertIn("Retry-After", str(err))
+
+    def test_key_never_leaves_for_another_host(self):
+        patch, calls = answering()
+        ns = nuasense.Client("k")
+        with patch:
+            for url in ("https://evil.example/x", "http://api.nuasense.com/api/nuasense/v1/catalog",
+                        "https://api.nuasense.com.evil.example/x"):
+                with self.assertRaisesRegex(ValueError, "only talks to"):
+                    ns.get(url)
+        self.assertEqual(calls, [])
+
+    def test_redirects_are_answers_not_followed(self):
+        self.assertIsNone(mod._NoRedirect().redirect_request(None, None, 302, "Found", {}, "https://evil.example/"))
+        patch, _ = answering((301, ""))
+        with patch, self.assertRaises(nuasense.NuaSenseError) as caught:
+            nuasense.Client("k").catalog()
+        self.assertEqual(caught.exception.status, 301)
+
+    def test_missing_key_says_where_to_get_one(self):
+        patch, _ = answering((401, {"error": "missing key"}))
+        with mock.patch.dict(os.environ, {}, clear=True), patch, \
+                self.assertRaisesRegex(nuasense.NuaSenseError, "platform.nuasense.com"):
+            nuasense.Client().stations()
+
+
+if __name__ == "__main__":
+    unittest.main()

nuasense-0.1.0/tests/test_ecowitt.py

@@ -0,0 +1,94 @@
+import unittest
+from datetime import datetime, timezone
+
+from nuasense import ecowitt
+
+# Reference values produced by the JavaScript packages (n8n-nodes-nuasense 0.1.1,
+# lib ecowitt.js): one device must keep one PASSKEY whichever package sends.
+JS_PASSKEYS = {
+    "shed": "985FCC5F91BFEB59B5C3D0E404026E73",
+    "pi-garden": "31512E4C3FD643BA6868A5B58E0A41D0",
+    "Gärtchen": "42F9C46C3FAECFC243B71173B1F8D088",
+    "🌧": "D22F55545B1470AE66FD13E3825DBDE8",
+}
+
+JS_FIELDS = {
+    "PASSKEY": "985FCC5F91BFEB59B5C3D0E404026E73",
+    "stationtype": "python_0.1.0",
+    "dateutc": "2026-11-16 08:30:00",
+    "tempf": "70.52",
+    "humidity": "63",
+    "baromabsin": "29.92",
+    "windspeedmph": "6.21",
+    "windgustmph": "3.11",
+    "winddir": "270",
+    "yearlyrainin": "0.48",
+    "solarradiation": "500",
+}
+
+
+class PasskeyTest(unittest.TestCase):
+    def test_matches_the_javascript_packages(self):
+        for name, expected in JS_PASSKEYS.items():
+            self.assertEqual(ecowitt.passkey_for(name), expected, name)
+
+    def test_stable_and_distinct(self):
+        self.assertRegex(ecowitt.passkey_for("shed"), r"^[0-9A-F]{32}$")
+        self.assertNotEqual(ecowitt.passkey_for("shed"), ecowitt.passkey_for("roof"))
+
+
+class FieldsTest(unittest.TestCase):
+    def test_same_form_as_the_javascript_packages(self):
+        fields = ecowitt.to_ecowitt_fields(
+            device_id="shed", station_type="python_0.1.0",
+            temperature=21.4, humidity=63.4, pressure=1013.2,
+            wind_speed=10, wind_unit="kmh", wind_gusts=5, wind_direction=-90,
+            rain_total=12.2, lux=60000, time="2026-11-16T08:30:00Z",
+        )
+        self.assertEqual(list(fields.items()), list(JS_FIELDS.items()))
+
+    def test_solar_wins_over_lux_and_empty_values_are_left_out(self):
+        fields = ecowitt.to_ecowitt_fields(device_id="x", station_type="t", solar=412.345, lux=1,
+                                           humidity="", pressure=None, temperature=float("nan"))
+        self.assertEqual(fields["solarradiation"], "412.35")
+        for key in ("humidity", "baromabsin", "tempf"):
+            self.assertNotIn(key, fields)
+
+    def test_zero_is_a_value(self):
+        fields = ecowitt.to_ecowitt_fields(device_id="x", station_type="t", rain_total=0, temperature=-17.7778)
+        self.assertEqual(fields["yearlyrainin"], "0")
+        self.assertEqual(fields["tempf"], "0")
+        self.assertTrue(ecowitt.has_values(fields))
+
+    def test_half_rounds_up_like_javascript(self):
+        fields = ecowitt.to_ecowitt_fields(device_id="x", station_type="t", humidity=62.5, wind_direction=359.6)
+        self.assertEqual(fields["humidity"], "63")
+        self.assertEqual(fields["winddir"], "360")
+
+    def test_nothing_measured(self):
+        self.assertFalse(ecowitt.has_values(ecowitt.to_ecowitt_fields(device_id="x", station_type="t")))
+
+
+class TimeTest(unittest.TestCase):
+    def test_datetime_and_offsets(self):
+        self.assertEqual(ecowitt.date_utc(datetime(2026, 11, 16, 11, 30, tzinfo=timezone.utc)), "2026-11-16 11:30:00")
+        self.assertEqual(ecowitt.date_utc("2026-11-16T11:30:00+03:00"), "2026-11-16 08:30:00")
+
+    def test_unreadable_time_becomes_now(self):
+        self.assertRegex(ecowitt.date_utc("yesterday"), r"^\d{4}-\d\d-\d\d \d\d:\d\d:\d\d$")
+
+
+class UrlTest(unittest.TestCase):
+    def test_token(self):
+        self.assertEqual(ecowitt.upload_url("  KW7N-4hpd-x2vt "), "https://api.nuasense.com/station/kw7n-4hpd-x2vt")
+        for bad in ("", "short", "kw7n/4hpd/x2vt", "a" * 30):
+            with self.assertRaises(ValueError):
+                ecowitt.upload_url(bad)
+
+    def test_form(self):
+        self.assertEqual(ecowitt.encode_form({"dateutc": "2026-11-16 08:30:00", "a": "1"}),
+                         "dateutc=2026-11-16%2008%3A30%3A00&a=1")
+
+
+if __name__ == "__main__":
+    unittest.main()