pylemetry 1.1.3__tar.gz → 1.2.0__tar.gz

{pylemetry-1.1.3 → pylemetry-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pylemetry
-Version: 1.1.3
+Version: 1.2.0
 Summary: A Python metrics library
 Project-URL: Homepage, https://pypi.org/project/pylemetry/
 Project-URL: Repository, https://github.com/amurphy4/pylemetry
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.15.0
 Description-Content-Type: text/markdown
 
 # Pylemetry
@@ -43,7 +44,7 @@ from pylemetry.meters import Counter
 
 
 def some_method() -> None:
-    counter = Counter()
+    counter = Counter("example")
 
     for _ in range(100):
         counter.add()  # counter += 1 is also supported
@@ -92,9 +93,9 @@ from pylemetry.meters import Gauge
 
 
 def some_method() -> None:
-    gauge = Gauge()
+    gauge = Gauge("sample_gauge")
     
-    registry.add_gauge("sample_gauge", gauge)
+    registry.add_gauge(gauge)
 ```
 
 The `Gauge` supports incrementing, decrementing, and setting a value directly
@@ -126,7 +127,7 @@ from pylemetry.meters import Timer
 
 
 def some_method() -> None:
-    timer = Timer()
+    timer = Timer("example")
 
     for _ in range(100):
         with timer.time():
@@ -172,6 +173,54 @@ def main() -> None:
 
 When using this meter via a decorator, the meter gets added to the global `registry`, with the method name it's decorating as the meter name. Alternatively, you can provide a name for the meter as a parameter to the decorator
 
+By default, timer meters will measure time in nanoseconds, this can be changed via the `unit` parameter using the `TimerUnits` enum in the utils module
+
+```python
+import time
+
+from pylemetry.meters import Timer
+from pylemetry.utils import TimerUnits
+
+
+timer_s = Timer("example_s", TimerUnits.SECONDS)
+timer_ms = Timer("example_ms", TimerUnits.MILLISECONDS)
+
+with timer_s.time():
+    time.sleep(1)
+    
+with timer_ms.time():
+    time.sleep(1)
+
+timer_s.get_mean_tick_time()  # 1
+timer_ms.get_mean_tick_time()  # 1000
+```
+
+## Tags
+
+When creating a meter you can assign a set of tags to it as key-value pairs. The value must be one of either `str`, `int`, or `float`.
+When using a decorator to create a meter, you can use a custom format for the value to extract values out of the method's args and kwargs
+
+In order to allow for multiple meters with the same name and different tags, the name in the registry gets mangled with the tags to produce a unique name,
+as a result when trying to get the meter from the registry you will need to provide both its name and its tags.
+
+```python
+from pylemetry import registry
+from pylemetry.decorators import time
+
+
+@time("example_timer", tags={"tag_1": "args[0]", "tag_2": "kwargs[param_2]", "tag_3": "some value"})
+def some_method(param_1: int, param_2: int) -> None:
+    ...
+
+
+def main() -> None:
+    for _ in range(100):
+        some_method(1, param_2=2)
+
+    timer = registry.get_timer("example_timer", {"tag_1": 1, "tag_2": 2, "tag_3": "some value"})
+    timer.get_tags()  # {"tag_1": 1, "tag_2": 2, "tag_3": "some value"}
+```
+
 ## The Registry
 
 Pylemetry maintains a global registry of meters, allowing you to share a meter across multiple files, or reference metrics from a central location.
@@ -182,13 +231,13 @@ from pylemetry import registry
 from pylemetry.meters import Counter, Gauge, Timer
 
 
-counter = Counter()
-gauge = Gauge()
-timer = Timer()
+counter = Counter("example")
+gauge = Gauge("example")
+timer = Timer("example")
 
-registry.add_counter("example", counter)
-registry.add_gauge("example", gauge)
-registry.add_timer("example", timer)
+registry.add_counter(counter)
+registry.add_gauge(gauge)
+registry.add_timer(timer)
 ```
 
 Each meter type has an `add_meter`, `get_meter` and `remove_meter` method to manage meters in the `registry`, each requiring a unique meter name.
@@ -199,9 +248,9 @@ from pylemetry import registry
 from pylemetry.meters import Counter, MeterType
 
 
-counter = Counter()
+counter = Counter("example")
 
-registry.add_meter("example", counter, MeterType.COUNTER)
+registry.add_meter(counter, MeterType.COUNTER)
 registry.get_meter("example", MeterType.COUNTER)
 registry.remove_meter("example", MeterType.COUNTER)
 registry.get_meter("example", MeterType.COUNTER)  # None
@@ -225,6 +274,7 @@ The message format allows for substitutions for metric values with the following
 | max              | Maximum value of the meter, equivalent to the `value` substitution for `Counter` and `Gauge` meters, `max_tick_time` for `Timer` meters       |
 | avg              | Mean average value of the meter, equivalent to the `value` substitution for `Counter` and `Gauge` meters, `mean_tick_time` for `Timer` meters |
 | type             | Type of the meter (`counter`, `gauge`, or `timer`)                                                                                            |
+| tags             | The tags associated with the meter                                                                                                            |
 
 As an example, a `Counter` meter named `sample_counter` with a value of 10
 ```python

{pylemetry-1.1.3 → pylemetry-1.2.0}/README.md

@@ -21,7 +21,7 @@ from pylemetry.meters import Counter
 
 
 def some_method() -> None:
-    counter = Counter()
+    counter = Counter("example")
 
     for _ in range(100):
         counter.add()  # counter += 1 is also supported
@@ -70,9 +70,9 @@ from pylemetry.meters import Gauge
 
 
 def some_method() -> None:
-    gauge = Gauge()
+    gauge = Gauge("sample_gauge")
     
-    registry.add_gauge("sample_gauge", gauge)
+    registry.add_gauge(gauge)
 ```
 
 The `Gauge` supports incrementing, decrementing, and setting a value directly
@@ -104,7 +104,7 @@ from pylemetry.meters import Timer
 
 
 def some_method() -> None:
-    timer = Timer()
+    timer = Timer("example")
 
     for _ in range(100):
         with timer.time():
@@ -150,6 +150,54 @@ def main() -> None:
 
 When using this meter via a decorator, the meter gets added to the global `registry`, with the method name it's decorating as the meter name. Alternatively, you can provide a name for the meter as a parameter to the decorator
 
+By default, timer meters will measure time in nanoseconds, this can be changed via the `unit` parameter using the `TimerUnits` enum in the utils module
+
+```python
+import time
+
+from pylemetry.meters import Timer
+from pylemetry.utils import TimerUnits
+
+
+timer_s = Timer("example_s", TimerUnits.SECONDS)
+timer_ms = Timer("example_ms", TimerUnits.MILLISECONDS)
+
+with timer_s.time():
+    time.sleep(1)
+    
+with timer_ms.time():
+    time.sleep(1)
+
+timer_s.get_mean_tick_time()  # 1
+timer_ms.get_mean_tick_time()  # 1000
+```
+
+## Tags
+
+When creating a meter you can assign a set of tags to it as key-value pairs. The value must be one of either `str`, `int`, or `float`.
+When using a decorator to create a meter, you can use a custom format for the value to extract values out of the method's args and kwargs
+
+In order to allow for multiple meters with the same name and different tags, the name in the registry gets mangled with the tags to produce a unique name,
+as a result when trying to get the meter from the registry you will need to provide both its name and its tags.
+
+```python
+from pylemetry import registry
+from pylemetry.decorators import time
+
+
+@time("example_timer", tags={"tag_1": "args[0]", "tag_2": "kwargs[param_2]", "tag_3": "some value"})
+def some_method(param_1: int, param_2: int) -> None:
+    ...
+
+
+def main() -> None:
+    for _ in range(100):
+        some_method(1, param_2=2)
+
+    timer = registry.get_timer("example_timer", {"tag_1": 1, "tag_2": 2, "tag_3": "some value"})
+    timer.get_tags()  # {"tag_1": 1, "tag_2": 2, "tag_3": "some value"}
+```
+
 ## The Registry
 
 Pylemetry maintains a global registry of meters, allowing you to share a meter across multiple files, or reference metrics from a central location.
@@ -160,13 +208,13 @@ from pylemetry import registry
 from pylemetry.meters import Counter, Gauge, Timer
 
 
-counter = Counter()
-gauge = Gauge()
-timer = Timer()
+counter = Counter("example")
+gauge = Gauge("example")
+timer = Timer("example")
 
-registry.add_counter("example", counter)
-registry.add_gauge("example", gauge)
-registry.add_timer("example", timer)
+registry.add_counter(counter)
+registry.add_gauge(gauge)
+registry.add_timer(timer)
 ```
 
 Each meter type has an `add_meter`, `get_meter` and `remove_meter` method to manage meters in the `registry`, each requiring a unique meter name.
@@ -177,9 +225,9 @@ from pylemetry import registry
 from pylemetry.meters import Counter, MeterType
 
 
-counter = Counter()
+counter = Counter("example")
 
-registry.add_meter("example", counter, MeterType.COUNTER)
+registry.add_meter(counter, MeterType.COUNTER)
 registry.get_meter("example", MeterType.COUNTER)
 registry.remove_meter("example", MeterType.COUNTER)
 registry.get_meter("example", MeterType.COUNTER)  # None
@@ -203,6 +251,7 @@ The message format allows for substitutions for metric values with the following
 | max              | Maximum value of the meter, equivalent to the `value` substitution for `Counter` and `Gauge` meters, `max_tick_time` for `Timer` meters       |
 | avg              | Mean average value of the meter, equivalent to the `value` substitution for `Counter` and `Gauge` meters, `mean_tick_time` for `Timer` meters |
 | type             | Type of the meter (`counter`, `gauge`, or `timer`)                                                                                            |
+| tags             | The tags associated with the meter                                                                                                            |
 
 As an example, a `Counter` meter named `sample_counter` with a value of 10
 ```python

{pylemetry-1.1.3 → pylemetry-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pylemetry"
-version = "1.1.3"
+version = "1.2.0"
 description = "A Python metrics library"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -25,7 +25,9 @@ classifiers = [
     "Programming Language :: Python :: 3.14",
 ]
 
-dependencies = []
+dependencies = [
+    "typing-extensions>=4.15.0",
+]
 
 [project.urls]
 Homepage = "https://pypi.org/project/pylemetry/"

pylemetry-1.2.0/src/pylemetry/decorators/count.py

@@ -0,0 +1,80 @@
+import re
+
+from typing import Callable, Optional, ParamSpec, TypeVar, Union
+
+from functools import wraps
+
+from pylemetry import registry
+from pylemetry.meters import Counter
+
+
+P = ParamSpec("P")
+R = TypeVar("R", covariant=True)
+
+
+def count(
+    name: Optional[str] = None, tags: Optional[dict[str, Union[str, int, float]]] = None
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """
+    Decorator to count the number of invocations of a given callable. Creates a Counter meter in the Registry
+    with either the provided name or the fully qualified name of the callable object as the metric name.
+
+    :param name: Name of the meter to create, if None the function name is used
+    :param tags: Optional key-value pairs of tags for this meter
+    :return: Result of the wrapped function
+    """
+
+    def decorator(f: Callable[P, R]) -> Callable[P, R]:
+        @wraps(f)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            counter_name = f.__qualname__ if name is None else name
+
+            _tags: dict[str, Union[str, int, float]] = {}
+
+            if tags:
+                for key, value in tags.items():
+                    args_match = re.search(r"^args\[[0-9]+]", str(value))
+                    kwargs_match = re.search(r"^kwargs\[[a-zA-Z0-9_]+]", str(value))
+
+                    if args_match:
+                        args_index = int(args_match.group().replace("args[", "").replace("]", ""))
+
+                        if args_index >= len(args):
+                            raise IndexError(f"args index {args_index} out of range, args has length {len(args)}")
+
+                        if not isinstance(args[args_index], (str, int, float)):
+                            raise ValueError(
+                                f"Only args of types (str | int | float) may be added as tags. "
+                                f"Got {args[args_index].__class__}"
+                            )
+
+                        _tags[key] = args[args_index]  # type: ignore
+                    elif kwargs_match:
+                        kwargs_key = kwargs_match.group().replace("kwargs[", "").replace("]", "")
+
+                        if kwargs_key not in kwargs:
+                            raise KeyError(f"Key '{kwargs_key}' not present in kwargs")
+
+                        if not isinstance(kwargs[kwargs_key], (str, int, float)):
+                            raise ValueError(
+                                f"Only kwargs of types (str | int | float) may be added as tags. "
+                                f"Got {kwargs[kwargs_key].__class__}"
+                            )
+
+                        _tags[key] = kwargs[kwargs_key]  # type: ignore
+                    else:
+                        _tags[key] = value
+
+            counter = registry.get_counter(counter_name, tags=_tags)
+
+            if not counter:
+                counter = Counter(name=counter_name, tags=_tags)
+                registry.add_counter(counter)
+
+            counter += 1
+
+            return f(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

pylemetry-1.2.0/src/pylemetry/decorators/time.py

@@ -0,0 +1,83 @@
+import re
+
+from typing import Callable, Optional, ParamSpec, TypeVar, Union
+
+from functools import wraps
+
+from pylemetry import registry
+from pylemetry.meters import Timer
+from pylemetry.utils import TimerUnits
+
+
+P = ParamSpec("P")
+R = TypeVar("R", covariant=True)
+
+
+def time(
+    name: Optional[str] = None,
+    unit: TimerUnits = TimerUnits.NANOSECONDS,
+    tags: Optional[dict[str, Union[str, int, float]]] = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """
+    Decorator to time the invocations of a given callable. Creates a Timer meter in the Registry with either the
+    provided name or the fully qualified name of the callable object as the metric name.
+
+    :param name: Name of the meter to create, if None the function name is used
+    :param unit: Unit of time to measure in
+    :param tags: Optional key-value pairs of tags for this meter
+    :return: Result of the wrapped function
+    """
+
+    def decorator(f: Callable[P, R]) -> Callable[P, R]:
+        @wraps(f)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            time_name = f.__qualname__ if name is None else name
+
+            _tags: dict[str, Union[str, int, float]] = {}
+
+            if tags:
+                for key, value in tags.items():
+                    args_match = re.search(r"^args\[[0-9]+]", str(value))
+                    kwargs_match = re.search(r"^kwargs\[[a-zA-Z0-9_]+]", str(value))
+
+                    if args_match:
+                        args_index = int(args_match.group().replace("args[", "").replace("]", ""))
+
+                        if args_index >= len(args):
+                            raise IndexError(f"args index {args_index} out of range, args has length {len(args)}")
+
+                        if not isinstance(args[args_index], (str, int, float)):
+                            raise ValueError(
+                                f"Only args of types (str | int | float) may be added as tags. "
+                                f"Got {args[args_index].__class__}"
+                            )
+
+                        _tags[key] = args[args_index]  # type: ignore
+                    elif kwargs_match:
+                        kwargs_key = kwargs_match.group().replace("kwargs[", "").replace("]", "")
+
+                        if kwargs_key not in kwargs:
+                            raise KeyError(f"Key '{kwargs_key}' not present in kwargs")
+
+                        if not isinstance(kwargs[kwargs_key], (str, int, float)):
+                            raise ValueError(
+                                f"Only kwargs of types (str | int | float) may be added as tags. "
+                                f"Got {kwargs[kwargs_key].__class__}"
+                            )
+
+                        _tags[key] = kwargs[kwargs_key]  # type: ignore
+                    else:
+                        _tags[key] = value
+
+            _timer = registry.get_timer(time_name, tags=_tags)
+
+            if not _timer:
+                _timer = Timer(time_name, unit=unit, tags=_tags)
+                registry.add_timer(_timer)
+
+            with _timer.time():
+                return f(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

{pylemetry-1.1.3 → pylemetry-1.2.0}/src/pylemetry/meters/counter.py

@@ -1,9 +1,11 @@
+from typing import Union, Optional
+
 from pylemetry.meters.meter import Meter, MeterType
 
 
 class Counter(Meter):
-    def __init__(self) -> None:
-        super().__init__(MeterType.COUNTER)
+    def __init__(self, name: str, tags: Optional[dict[str, Union[str, int, float]]] = None) -> None:
+        super().__init__(MeterType.COUNTER, name, tags)
 
     def add(self, value: int = 1) -> None:
         """

{pylemetry-1.1.3 → pylemetry-1.2.0}/src/pylemetry/meters/gauge.py

@@ -1,9 +1,11 @@
+from typing import Union, Optional
+
 from pylemetry.meters.meter import Meter, MeterType
 
 
 class Gauge(Meter):
-    def __init__(self) -> None:
-        super().__init__(MeterType.GAUGE)
+    def __init__(self, name: str, tags: Optional[dict[str, Union[str, int, float]]] = None) -> None:
+        super().__init__(MeterType.GAUGE, name, tags)
 
     def set_value(self, value: float):
         """

{pylemetry-1.1.3 → pylemetry-1.2.0}/src/pylemetry/meters/meter.py

@@ -1,5 +1,6 @@
 from enum import Enum
 from threading import Lock
+from typing import Union, Optional
 
 
 class MeterType(Enum):
@@ -9,11 +10,19 @@ class MeterType(Enum):
 
 
 class Meter:
-    def __init__(self, meter_type: MeterType) -> None:
+    def __init__(
+        self, meter_type: MeterType, name: str, tags: Optional[dict[str, Union[str, int, float]]] = None
+    ) -> None:
         self.lock = Lock()
         self.value = 0.0
         self.last_interval_value = 0.0
         self.meter_type = meter_type
+        self.name = name
+
+        if not tags:
+            tags = {}
+
+        self.__tags = tags
 
     def get_value(self, since_last_interval: bool = False) -> float:
         """
@@ -36,3 +45,6 @@ class Meter:
 
         with self.lock:
             self.last_interval_value = self.value
+
+    def get_tags(self) -> dict[str, Union[str, int, float]]:
+        return self.__tags

{pylemetry-1.1.3 → pylemetry-1.2.0}/src/pylemetry/meters/timer.py

@@ -1,15 +1,23 @@
-from typing import Generator
+from typing import Generator, Union, Optional
 
 import time
 
 from contextlib import contextmanager
 
 from pylemetry.meters.meter import Meter, MeterType
+from pylemetry.utils import TimerUnits
 
 
 class Timer(Meter):
-    def __init__(self) -> None:
-        super().__init__(MeterType.TIMER)
+    def __init__(
+        self,
+        name: str,
+        unit: TimerUnits = TimerUnits.NANOSECONDS,
+        tags: Optional[dict[str, Union[str, int, float]]] = None,
+    ) -> None:
+        super().__init__(MeterType.TIMER, name, tags)
+
+        self.unit = unit
 
         self.ticks: list[float] = []
 
@@ -29,14 +37,14 @@ class Timer(Meter):
         Context manager to time in seconds a code block and add the result to the internal ticks list
         """
 
-        start_time = time.perf_counter()
+        start_time = time.perf_counter_ns()
 
         try:
             yield
         finally:
-            end_time = time.perf_counter()
+            end_time = time.perf_counter_ns()
 
-            self.tick(end_time - start_time)
+            self.tick((end_time - start_time) / self.unit.conversion_from_ns())
 
     def get_value(self, since_last_interval: bool = False) -> int:
         """