pamoja-telemetry 0.1.18__tar.gz

pamoja_telemetry-0.1.18/.gitignore

@@ -0,0 +1,13 @@
+# Native extensions are built per platform, not committed.
+*.so
+*.pyd
+*.dylib
+
+# Build and packaging output.
+dist/
+wheels/
+target/
+
+# Local virtual environments.
+.venv/
+venv/

pamoja_telemetry-0.1.18/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Wiedman
+
+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.

pamoja_telemetry-0.1.18/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: pamoja-telemetry
+Version: 0.1.18
+Summary: Observability that ships only what is worth the bytes as link cost rises, while counting everything.
+Project-URL: Repository, https://github.com/molexxxx/pamoja
+Project-URL: Documentation, https://pamoja.molex.cloud/docs/guides/telemetry.html
+Author: molexxxx
+License: MIT
+License-File: LICENSE-MIT
+Keywords: iot,pamoja,robotics,telemetry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pamoja-native==0.1.18
+Description-Content-Type: text/markdown
+
+# pamoja-telemetry
+
+Observability that ships only what is worth the bytes as link cost rises, while counting everything. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/telemetry.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/telemetry.html)
+
+## Install
+
+```sh
+pip install pamoja-telemetry
+```
+
+```python
+from pamoja import telemetry
+```
+
+This pulls in `pamoja-native`, the compiled engine. `pip install pamoja` is the whole framework in one package.
+
+## Example
+
+The script the test suite runs, spliced here as it ran.
+
+From [`bindings/python/guides/telemetry.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/telemetry.py):
+
+```python
+from pamoja.telemetry import Event, Level, LinkCost, Reporter, link_cost_threshold
+
+# The node is willing to record everything, then finds out it is reporting over a metered
+# link, which puts the bar at INFO.
+reporter = Reporter(Level.TRACE)
+reporter.adapt_to(LinkCost.METERED)
+print(f"on a metered link, nothing below {reporter.threshold.value} is sent")
+
+# Routine detail stops going out. A reading and the warning that follows it still do, and
+# a shipped event comes back with the measurement that triggered it.
+tick = reporter.record(Event(Level.DEBUG, "loop.tick"))
+reading = reporter.record(Event(Level.INFO, "reading.ok", 4.8))
+print(f"loop.tick sent: {tick is not None}")
+print(f"reading.ok sent: {reading is not None}")
+warned = reporter.record(Event(Level.WARN, "battery.low", 0.18))
+print(f"sent      {warned.code} carrying {warned.value}")
+
+# The node falls back to satellite, which raises the bar to WARN. The same reading is no
+# longer worth its bytes; a failure still is.
+reporter.adapt_to(LinkCost.EXPENSIVE)
+dearer = reporter.record(Event(Level.INFO, "reading.ok", 4.9))
+lost = reporter.record(Event(Level.ERROR, "link.lost"))
+print(f"on satellite, reading.ok sent: {dearer is not None}")
+print(f"on satellite, link.lost sent: {lost is not None}")
+
+# Only the stream was thinned, not the counts, so every event is still accounted for and
+# the snapshot is what the node ships in place of them.
+counts = reporter.snapshot()
+print(f"of {reporter.total} events, {counts.emitted} went out and {counts.dropped} were counted only")
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-telemetry`](https://crates.io/crates/pamoja-telemetry) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_telemetry/index.html), [docs.rs](https://docs.rs/pamoja-telemetry), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-telemetry) |
+| TypeScript | [`@pamoja/telemetry`](https://www.npmjs.com/package/@pamoja/telemetry) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_telemetry.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-telemetry) |
+| Python | [`pamoja-telemetry`](https://pypi.org/project/pamoja-telemetry/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/telemetry.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-telemetry) |
+| C# | [`Pamoja.Telemetry`](https://www.nuget.org/packages/Pamoja.Telemetry) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Telemetry.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-telemetry) |
+
+## Documentation
+
+- [`pamoja.telemetry` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/telemetry.html), every class and function in this module.
+- [The Telemetry guide](https://pamoja.molex.cloud/docs/guides/telemetry.html), with the same example in Rust, TypeScript, and C#.
+- [Every capability](https://pamoja.molex.cloud/docs/), and the [install page](https://pamoja.molex.cloud/docs/install.html).
+
+## License
+
+MIT

pamoja_telemetry-0.1.18/README.md

@@ -0,0 +1,76 @@
+# pamoja-telemetry
+
+Observability that ships only what is worth the bytes as link cost rises, while counting everything. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/telemetry.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/telemetry.html)
+
+## Install
+
+```sh
+pip install pamoja-telemetry
+```
+
+```python
+from pamoja import telemetry
+```
+
+This pulls in `pamoja-native`, the compiled engine. `pip install pamoja` is the whole framework in one package.
+
+## Example
+
+The script the test suite runs, spliced here as it ran.
+
+From [`bindings/python/guides/telemetry.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/telemetry.py):
+
+```python
+from pamoja.telemetry import Event, Level, LinkCost, Reporter, link_cost_threshold
+
+# The node is willing to record everything, then finds out it is reporting over a metered
+# link, which puts the bar at INFO.
+reporter = Reporter(Level.TRACE)
+reporter.adapt_to(LinkCost.METERED)
+print(f"on a metered link, nothing below {reporter.threshold.value} is sent")
+
+# Routine detail stops going out. A reading and the warning that follows it still do, and
+# a shipped event comes back with the measurement that triggered it.
+tick = reporter.record(Event(Level.DEBUG, "loop.tick"))
+reading = reporter.record(Event(Level.INFO, "reading.ok", 4.8))
+print(f"loop.tick sent: {tick is not None}")
+print(f"reading.ok sent: {reading is not None}")
+warned = reporter.record(Event(Level.WARN, "battery.low", 0.18))
+print(f"sent      {warned.code} carrying {warned.value}")
+
+# The node falls back to satellite, which raises the bar to WARN. The same reading is no
+# longer worth its bytes; a failure still is.
+reporter.adapt_to(LinkCost.EXPENSIVE)
+dearer = reporter.record(Event(Level.INFO, "reading.ok", 4.9))
+lost = reporter.record(Event(Level.ERROR, "link.lost"))
+print(f"on satellite, reading.ok sent: {dearer is not None}")
+print(f"on satellite, link.lost sent: {lost is not None}")
+
+# Only the stream was thinned, not the counts, so every event is still accounted for and
+# the snapshot is what the node ships in place of them.
+counts = reporter.snapshot()
+print(f"of {reporter.total} events, {counts.emitted} went out and {counts.dropped} were counted only")
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-telemetry`](https://crates.io/crates/pamoja-telemetry) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_telemetry/index.html), [docs.rs](https://docs.rs/pamoja-telemetry), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-telemetry) |
+| TypeScript | [`@pamoja/telemetry`](https://www.npmjs.com/package/@pamoja/telemetry) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_telemetry.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-telemetry) |
+| Python | [`pamoja-telemetry`](https://pypi.org/project/pamoja-telemetry/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/telemetry.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-telemetry) |
+| C# | [`Pamoja.Telemetry`](https://www.nuget.org/packages/Pamoja.Telemetry) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Telemetry.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-telemetry) |
+
+## Documentation
+
+- [`pamoja.telemetry` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/telemetry.html), every class and function in this module.
+- [The Telemetry guide](https://pamoja.molex.cloud/docs/guides/telemetry.html), with the same example in Rust, TypeScript, and C#.
+- [Every capability](https://pamoja.molex.cloud/docs/), and the [install page](https://pamoja.molex.cloud/docs/install.html).
+
+## License
+
+MIT

pamoja_telemetry-0.1.18/pamoja/telemetry/__init__.py

@@ -0,0 +1,149 @@
+"""Idiomatic telemetry facade.
+
+A node that ships every event it produces will spend more on reporting than on
+the job it was installed to do, and on a satellite link that is money. A reporter
+ships what is worth its bytes, counts everything either way, and moves its own
+bar as the link gets more expensive, so the aggregate picture survives even when
+the detail cannot be sent.
+
+The generated binding decides on the level alone, since that is all the core
+reporter reads. The event a caller writes travels no further than this layer,
+which hands it straight back when it should be shipped.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+
+from pamoja._native import Reporter as _Reporter
+from pamoja._native import Snapshot
+from pamoja._native import link_cost_threshold as _link_cost_threshold
+
+__all__ = [
+    "Event",
+    "Level",
+    "LinkCost",
+    "Reporter",
+    "Snapshot",
+    "link_cost_threshold",
+]
+
+
+class Level(str, enum.Enum):
+    """How urgent an event is."""
+
+    #: Fine-grained detail, useful only when chasing a specific problem.
+    TRACE = "Trace"
+    #: Diagnostic detail for development.
+    DEBUG = "Debug"
+    #: A normal, noteworthy event.
+    INFO = "Info"
+    #: Something unexpected that the node recovered from.
+    WARN = "Warn"
+    #: A failure that needs attention.
+    ERROR = "Error"
+
+
+class LinkCost(str, enum.Enum):
+    """What the link back to the network currently costs."""
+
+    #: Bytes are effectively free, such as on wired power and ethernet.
+    FREE = "Free"
+    #: Bytes are paid for, such as on a cellular plan.
+    METERED = "Metered"
+    #: Bytes are scarce, such as on a satellite or long-range radio link.
+    EXPENSIVE = "Expensive"
+    #: Nothing can be shipped at all.
+    OFFLINE = "Offline"
+
+
+@dataclass(frozen=True)
+class Event:
+    """A structured telemetry event.
+
+    The code is a stable, short label such as ``battery.low`` rather than a
+    free-form message, so events stay small and group cleanly into counts.
+    """
+
+    #: How urgent the event is.
+    level: Level
+    #: A stable, short identifier for what happened.
+    code: str
+    #: An optional measurement, such as the charge that triggered it.
+    value: float | None = None
+
+
+def link_cost_threshold(cost: LinkCost) -> Level:
+    """Return the level a link cost calls for.
+
+    :param cost: What the link currently costs.
+    :returns: The lowest level still worth its bytes at that cost.
+    """
+    return Level(_link_cost_threshold(cost.value))
+
+
+class Reporter:
+    """Record events, ship the ones worth their bytes, and count them all."""
+
+    def __init__(self, threshold: Level = Level.INFO) -> None:
+        """Create a reporter that ships events at or above ``threshold``.
+
+        :param threshold: The lowest level to ship.
+        """
+        self._inner = _Reporter(threshold.value)
+
+    @property
+    def threshold(self) -> Level:
+        """The level this reporter is currently shipping from."""
+        return Level(self._inner.threshold)
+
+    @threshold.setter
+    def threshold(self, threshold: Level) -> None:
+        self._inner.threshold = threshold.value
+
+    @property
+    def total(self) -> int:
+        """How many events have been seen across every level."""
+        return self._inner.total
+
+    @property
+    def emitted(self) -> int:
+        """How many events passed the threshold and were shipped."""
+        return self._inner.emitted
+
+    @property
+    def dropped(self) -> int:
+        """How many events the threshold dropped."""
+        return self._inner.dropped
+
+    def adapt_to(self, cost: LinkCost) -> None:
+        """Move the threshold to match what the link now costs.
+
+        :param cost: What the link currently costs.
+        """
+        self._inner.adapt_to(cost.value)
+
+    def record(self, event: Event) -> Event | None:
+        """Record an event, returning it when it should be shipped.
+
+        :param event: The event that occurred.
+        :returns: The same event when it passed the threshold, or ``None`` when
+            it was counted and dropped.
+        """
+        return event if self._inner.record(event.level.value) else None
+
+    def count(self, level: Level) -> int:
+        """Return how many events have been seen at a level, shipped or not.
+
+        :param level: The level to count.
+        :returns: The number of events recorded at that level.
+        """
+        return self._inner.count(level.value)
+
+    def snapshot(self) -> Snapshot:
+        """Take a snapshot of the counters to ship in place of the stream.
+
+        :returns: The per-level counts and the shipped and dropped totals.
+        """
+        return self._inner.snapshot()

pamoja_telemetry-0.1.18/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pamoja-telemetry"
+version = "0.1.18"
+description = "Observability that ships only what is worth the bytes as link cost rises, while counting everything."
+readme = "README.md"
+license = { text = "MIT" }
+license-files = ["LICENSE-MIT"]
+requires-python = ">=3.10"
+authors = [{ name = "molexxxx" }]
+keywords = ["pamoja", "iot", "robotics", "telemetry"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pamoja-native==0.1.18",
+]
+
+[project.urls]
+Repository = "https://github.com/molexxxx/pamoja"
+Documentation = "https://pamoja.molex.cloud/docs/guides/telemetry.html"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pamoja"]