monsta 0.2.0__tar.gz → 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: monsta
3
- Version: 0.2.0
3
+ Version: 0.2.1
4
4
  Summary: Simple monitoring REST API for Python applications
5
5
  Author: Stefan Schönberger
6
6
  Author-email: Stefan Schönberger <stefan@sniner.dev>
@@ -221,7 +221,7 @@ The lock is reentrant, so you can call `state.to_dict()` from inside a
221
221
 
222
222
  | Field | Constructor | Methods | Serialized as |
223
223
  |---|---|---|---|
224
- | `SlidingWindow` | `SlidingWindow(window=60.0)` | `inc`, `set`, `reset`, `+=` | `float` – rate over the window |
224
+ | `SlidingWindow` | `SlidingWindow(window=60.0, buckets=60)` | `inc`, `set`, `reset`, `+=` | `float` – rate over the window |
225
225
  | `PeriodicSum` | `PeriodicSum(reset_at=time(0,0), tz=None)` | `inc`, `set`, `reset`, `+=` | `float` – count since last reset |
226
226
  | `EWMA` | `EWMA(alpha=0.1, preset=None)` | `update`, `reset` | `float \| None` – current estimate |
227
227
  | `RunningStats` | `RunningStats()` | `update`, `reset` | `{"n", "mean", "stddev", "min", "max"}` |
@@ -235,12 +235,18 @@ Method semantics are uniform across fields: `inc` increments a counter,
235
235
  There is no method that means "increment on counters but feed sample on
236
236
  samplers" – that ambiguity was a 0.1.x footgun and is gone.
237
237
 
238
- **`SlidingWindow(window)`** – rate counter. Returns how many hits accumulated
239
- in the last `window` seconds, with smooth interpolation at window boundaries.
240
- Use `state.x.inc()` (or `state.x += n`) to record events; both forms are
241
- atomic across threads. `state.x.set(value)` overwrites the current bucket
242
- (useful for syncing to an external counter). `state.x.reset()` clears both
243
- buckets.
238
+ **`SlidingWindow(window, *, buckets=60)`** – rate counter. Returns how many
239
+ hits were recorded in the last `window` seconds. The window is divided into
240
+ `buckets` buckets of `window / buckets` seconds each. A single event counts
241
+ fully for at least `window - window / buckets` seconds and then drops out
242
+ within one bucket, so in a graph it shows up as a rectangle of width `window`.
243
+ A steady rate gives a steady value. More buckets give sharper edges and cost
244
+ one float each. With `buckets=1` the value is a rough estimate: an event
245
+ counts fully only until the next bucket boundary and then fades out over a
246
+ whole `window`. Use `state.x.inc()` (or `state.x += n`) to record events; both
247
+ forms are atomic across threads. `state.x.set(value)` overwrites the current
248
+ bucket (useful for syncing to an external counter). `state.x.reset()` clears
249
+ all buckets.
244
250
 
245
251
  **`PeriodicSum(reset_at=time(0,0), tz=None)`** – calendar-aligned counter that
246
252
  accumulates events and snaps back to zero at a configurable wall-clock time
@@ -209,7 +209,7 @@ The lock is reentrant, so you can call `state.to_dict()` from inside a
209
209
 
210
210
  | Field | Constructor | Methods | Serialized as |
211
211
  |---|---|---|---|
212
- | `SlidingWindow` | `SlidingWindow(window=60.0)` | `inc`, `set`, `reset`, `+=` | `float` – rate over the window |
212
+ | `SlidingWindow` | `SlidingWindow(window=60.0, buckets=60)` | `inc`, `set`, `reset`, `+=` | `float` – rate over the window |
213
213
  | `PeriodicSum` | `PeriodicSum(reset_at=time(0,0), tz=None)` | `inc`, `set`, `reset`, `+=` | `float` – count since last reset |
214
214
  | `EWMA` | `EWMA(alpha=0.1, preset=None)` | `update`, `reset` | `float \| None` – current estimate |
215
215
  | `RunningStats` | `RunningStats()` | `update`, `reset` | `{"n", "mean", "stddev", "min", "max"}` |
@@ -223,12 +223,18 @@ Method semantics are uniform across fields: `inc` increments a counter,
223
223
  There is no method that means "increment on counters but feed sample on
224
224
  samplers" – that ambiguity was a 0.1.x footgun and is gone.
225
225
 
226
- **`SlidingWindow(window)`** – rate counter. Returns how many hits accumulated
227
- in the last `window` seconds, with smooth interpolation at window boundaries.
228
- Use `state.x.inc()` (or `state.x += n`) to record events; both forms are
229
- atomic across threads. `state.x.set(value)` overwrites the current bucket
230
- (useful for syncing to an external counter). `state.x.reset()` clears both
231
- buckets.
226
+ **`SlidingWindow(window, *, buckets=60)`** – rate counter. Returns how many
227
+ hits were recorded in the last `window` seconds. The window is divided into
228
+ `buckets` buckets of `window / buckets` seconds each. A single event counts
229
+ fully for at least `window - window / buckets` seconds and then drops out
230
+ within one bucket, so in a graph it shows up as a rectangle of width `window`.
231
+ A steady rate gives a steady value. More buckets give sharper edges and cost
232
+ one float each. With `buckets=1` the value is a rough estimate: an event
233
+ counts fully only until the next bucket boundary and then fades out over a
234
+ whole `window`. Use `state.x.inc()` (or `state.x += n`) to record events; both
235
+ forms are atomic across threads. `state.x.set(value)` overwrites the current
236
+ bucket (useful for syncing to an external counter). `state.x.reset()` clears
237
+ all buckets.
232
238
 
233
239
  **`PeriodicSum(reset_at=time(0,0), tz=None)`** – calendar-aligned counter that
234
240
  accumulates events and snaps back to zero at a configurable wall-clock time
@@ -0,0 +1,43 @@
1
+ [project]
2
+ name = "monsta"
3
+ version = "0.2.1"
4
+ description = "Simple monitoring REST API for Python applications"
5
+ readme = "README.md"
6
+ requires-python = ">=3.10"
7
+ dependencies = [
8
+ "fastapi>=0.133.1",
9
+ "pydantic>=2.12.5",
10
+ "uvicorn>=0.41.0",
11
+ ]
12
+
13
+ [[project.authors]]
14
+ name = "Stefan Schönberger"
15
+ email = "stefan@sniner.dev"
16
+
17
+ [build-system]
18
+ requires = ["uv_build>=0.10.6,<0.11.0"]
19
+ build-backend = "uv_build"
20
+
21
+ [dependency-groups]
22
+ dev = [
23
+ "basedpyright>=1.38.2",
24
+ "pytest>=9.0.2",
25
+ "ruff>=0.15.3",
26
+ ]
27
+
28
+ [tool.pytest.ini_options]
29
+ addopts = "-ra -q"
30
+ testpaths = ["tests"]
31
+
32
+ [tool.pyright]
33
+ typeCheckingMode = "standard"
34
+ useLibraryCodeForTypes = true
35
+ venvPath = "."
36
+ venv = ".venv"
37
+
38
+ [tool.ruff]
39
+ line-length = 96
40
+ ignore = ["E402"]
41
+
42
+ [tool.ruff.lint.per-file-ignores]
43
+ "__init__.py" = ["F401"]
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "monsta"
3
- version = "0.2.0"
3
+ version = "0.2.1"
4
4
  description = "Simple monitoring REST API for Python applications"
5
5
  readme = "README.md"
6
6
  authors = [
@@ -0,0 +1,86 @@
1
+ from __future__ import annotations
2
+
3
+ import threading
4
+ import time
5
+
6
+ from .base import Field
7
+
8
+
9
+ class SlidingWindow(Field):
10
+ """Counter over the last ``window`` seconds, useful for rates.
11
+
12
+ The window is divided into ``buckets`` buckets of ``window / buckets``
13
+ seconds each. ``serialize()`` returns the sum of the buckets that cover
14
+ the last ``window`` seconds. The oldest bucket is weighted by the part
15
+ of it that is still inside the window, so a steady rate gives a steady
16
+ value. A single event counts fully for at least ``window - window /
17
+ buckets`` seconds and then drops to zero within one bucket.
18
+
19
+ More buckets make the edges sharper at the cost of one float per
20
+ bucket. ``buckets=1`` gives a coarse estimate: an event counts fully
21
+ only until the next bucket boundary and then fades out over a whole
22
+ ``window``.
23
+
24
+ API:
25
+ - ``inc(amount=1.0)`` — atomically add ``amount`` to the current bucket
26
+ - ``state.x += n`` — alias for ``inc(n)``, also atomic
27
+ - ``set(value)`` — overwrite the current bucket (e.g. external sync)
28
+ - ``reset()`` — clear all buckets
29
+ """
30
+
31
+ def __init__(self, window: float = 60.0, *, buckets: int = 60) -> None:
32
+ if window <= 0:
33
+ raise ValueError(f"window must be positive, got {window}")
34
+ if buckets < 1:
35
+ raise ValueError(f"buckets must be at least 1, got {buckets}")
36
+ self.window = window
37
+ self.buckets = buckets
38
+ self._width = window / buckets
39
+ self._lock = threading.Lock()
40
+ # One bucket more than ``buckets``: the oldest one is partly outside
41
+ # the window and still contributes with its remaining fraction.
42
+ self._slots: list[float] = [0.0] * (buckets + 1)
43
+ self._last_idx: int = int(time.monotonic() // self._width)
44
+
45
+ def _sync(self, now: float) -> int:
46
+ idx = int(now // self._width)
47
+ elapsed = idx - self._last_idx
48
+ if elapsed > 0:
49
+ n = len(self._slots)
50
+ for i in range(self._last_idx + 1, self._last_idx + 1 + min(elapsed, n)):
51
+ self._slots[i % n] = 0.0
52
+ self._last_idx = idx
53
+ return idx
54
+
55
+ def inc(self, amount: float = 1.0) -> None:
56
+ with self._lock:
57
+ idx = self._sync(time.monotonic())
58
+ self._slots[idx % len(self._slots)] += float(amount)
59
+
60
+ def set(self, value: float) -> None:
61
+ with self._lock:
62
+ idx = self._sync(time.monotonic())
63
+ self._slots[idx % len(self._slots)] = float(value)
64
+
65
+ def reset(self) -> None:
66
+ with self._lock:
67
+ self._slots = [0.0] * (self.buckets + 1)
68
+ self._last_idx = int(time.monotonic() // self._width)
69
+
70
+ def __iadd__(self, amount: float) -> SlidingWindow:
71
+ self.inc(amount)
72
+ # Returning self is critical: AppState.__setattr__ then sees a
73
+ # Field-to-Field rebind (same instance) and lets it through.
74
+ return self
75
+
76
+ def serialize(self) -> float:
77
+ with self._lock:
78
+ now = time.monotonic()
79
+ idx = self._sync(now)
80
+ # _sync has cleared everything older than ``buckets`` buckets, so
81
+ # the ring holds exactly the current bucket and the ``buckets``
82
+ # before it. The oldest of them sits at idx - buckets, which is
83
+ # idx + 1 modulo the ring size.
84
+ oldest = self._slots[(idx + 1) % len(self._slots)]
85
+ elapsed = (now % self._width) / self._width
86
+ return sum(self._slots) - oldest * elapsed
@@ -1,67 +0,0 @@
1
- from __future__ import annotations
2
-
3
- import threading
4
- import time
5
-
6
- from .base import Field
7
-
8
-
9
- class SlidingWindow(Field):
10
- """Counter that averages a sliding interval, useful for rates.
11
-
12
- Returns the number of hits accumulated over the last ``window``
13
- seconds, with smooth interpolation across bucket boundaries. The
14
- counter has two adjacent buckets internally; ``serialize()`` mixes
15
- them by the elapsed fraction of the current bucket.
16
-
17
- API:
18
- - ``inc(amount=1.0)`` — atomically add ``amount`` to the current bucket
19
- - ``state.x += n`` — alias for ``inc(n)``, also atomic
20
- - ``set(value)`` — overwrite the current bucket (e.g. external sync)
21
- - ``reset()`` — clear both buckets
22
- """
23
-
24
- def __init__(self, window: float = 60.0) -> None:
25
- if window <= 0:
26
- raise ValueError(f"window must be positive, got {window}")
27
- self.window = window
28
- self._lock = threading.Lock()
29
- self._prev: float = 0.0
30
- self._curr: float = 0.0
31
- self._last_idx: int = int(time.monotonic() // window)
32
-
33
- def _sync(self, now: float) -> None:
34
- idx = int(now // self.window)
35
- if idx > self._last_idx:
36
- self._prev = self._curr if idx == self._last_idx + 1 else 0.0
37
- self._curr = 0.0
38
- self._last_idx = idx
39
-
40
- def inc(self, amount: float = 1.0) -> None:
41
- with self._lock:
42
- self._sync(time.monotonic())
43
- self._curr += float(amount)
44
-
45
- def set(self, value: float) -> None:
46
- with self._lock:
47
- self._sync(time.monotonic())
48
- self._curr = float(value)
49
-
50
- def reset(self) -> None:
51
- with self._lock:
52
- self._prev = 0.0
53
- self._curr = 0.0
54
- self._last_idx = int(time.monotonic() // self.window)
55
-
56
- def __iadd__(self, amount: float) -> SlidingWindow:
57
- self.inc(amount)
58
- # Returning self is critical: AppState.__setattr__ then sees a
59
- # Field-to-Field rebind (same instance) and lets it through.
60
- return self
61
-
62
- def serialize(self) -> float:
63
- with self._lock:
64
- now = time.monotonic()
65
- self._sync(now)
66
- weight = max(0.0, min(1.0, (self.window - now % self.window) / self.window))
67
- return (self._prev * weight) + self._curr
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes