pylemetry 1.1.4__tar.gz → 1.2.1__tar.gz

pylemetry-1.2.1/.github/actions/bump-version/action.yaml

@@ -0,0 +1,26 @@
+name: Bump version
+description: Bump the project version and create a pull request
+runs:
+  using: composite
+  steps:
+    - name: Bump Version
+      run: uv version --bump patch --bump alpha
+      shell: bash
+
+    - name: Get New Version Branch Name
+      id: bump_version
+      run: echo "branch_name=feature/bump_version_$(uv version --short)" >> $GITHUB_OUTPUT
+      shell: bash
+
+    - name: Commit Version Bump
+      uses: EndBug/add-and-commit@v11.1.1
+      with:
+        message: "Bump project version following release"
+        default_author: github_actions
+        new_branch: ${{ steps.bump_version.outputs.branch_name }}
+
+    - name: Raise Pull Request
+      run: gh pr create -B main -H ${{ steps.bump_version.outputs.branch_name }} --title "Update version to v$(uv version --short)" --body 'Created by GitHub Actions in the Release pipeline'
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{pylemetry-1.1.4 → pylemetry-1.2.1}/.github/actions/configure-uv/action.yaml

@@ -1,9 +1,10 @@
 name: Configure uv
+description: Configure uv for running within pipelines
 runs:
   using: composite
   steps:
     - name: Install uv
-      uses: astral-sh/setup-uv@v6
+      uses: astral-sh/setup-uv@v10.2.0
 
     - name: Install dependencies
       run: uv sync --locked --dev

{pylemetry-1.1.4 → pylemetry-1.2.1}/.github/workflows/ci.yaml

@@ -1,13 +1,9 @@
 name: Test, Build, and Publish
 
 on:
-  push:
-    branches:
-      - develop
   pull_request:
     branches:
       - main
-      - develop
 
 jobs:
   lint:
@@ -15,11 +11,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7.0.1
 
       - uses: ./.github/actions/configure-uv
 
-      - uses: astral-sh/ruff-action@v3
+      - uses: astral-sh/ruff-action@v4.1.0
 
       - name: Type Checks
         run: uv run mypy .
@@ -29,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7.0.1
 
       - uses: ./.github/actions/configure-uv
 
@@ -43,7 +39,7 @@ jobs:
     needs: [lint, test]
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7.0.1
 
       - uses: ./.github/actions/configure-uv
 

pylemetry-1.2.1/.github/workflows/release.yaml

@@ -0,0 +1,102 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: Run as a dry-run
+        type: boolean
+      bump-to-stable:
+        description: Bump the version to the next stable version
+        type: boolean
+        default: true
+      override-version:
+        description: Override the current version and set as the release version
+        type: string
+
+jobs:
+  lint:
+    name: Lint & Types
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - uses: ./.github/actions/configure-uv
+
+      - uses: astral-sh/ruff-action@v4.1.0
+
+      - name: Type Checks
+        run: uv run mypy .
+
+  test:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - uses: ./.github/actions/configure-uv
+
+      - name: Run tests with Tox
+        run: tox
+
+  publish:
+    name: Build & Publish
+    runs-on: ubuntu-latest
+    environment: release
+    needs: [lint, test]
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          ssh-key: ${{ secrets.DEPLOY_KEY }}
+
+      - uses: ./.github/actions/configure-uv
+
+      - name: Set release version
+        if: ${{ inputs.bump-to-stable || inputs.override-version != '' }}
+        run: |
+          if [[ $OVERRIDE_VERSION != '' ]]; then
+            uv version $OVERRIDE_VERSION;
+          elif $BUMP_TO_STABLE; then
+            uv version --bump stable
+          fi;
+        env:
+          BUMP_TO_STABLE: ${{ inputs.bump-to-stable }}
+          OVERRIDE_VERSION: ${{ inputs.override-version }}
+
+      - name: Get version from uv
+        id: version
+        run: echo "version=$(uv version --short)" >> $GITHUB_OUTPUT
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          PYPI_TOKEN: ${{ secrets.pypi_token }}
+          DRY_RUN: ${{ inputs.dry-run }}
+        run: |
+          if $DRY_RUN; then
+            uv publish --index pypi --dry-run --token $PYPI_TOKEN
+          else
+            uv publish --index pypi --token $PYPI_TOKEN
+          fi;
+
+      - name: GitHub Release
+        if: ${{ !inputs.dry-run }}
+        uses: ncipollo/release-action@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag: ${{ steps.version.outputs.version }}
+          name: ${{ steps.version.outputs.version }}
+          artifacts: "dist/pylemetry-*.tar.gz,dist/pylemetry-*.whl"
+
+      - name: Bump Version
+        if: ${{ !inputs.dry-run }}
+        uses: ./.github/actions/bump-version

{pylemetry-1.1.4 → pylemetry-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pylemetry
-Version: 1.1.4
+Version: 1.2.1
 Summary: A Python metrics library
 Project-URL: Homepage, https://pypi.org/project/pylemetry/
 Project-URL: Repository, https://github.com/amurphy4/pylemetry
@@ -44,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
@@ -60,13 +60,11 @@ from pylemetry.decorators import count
 
 
 @count()
-def some_method() -> None:
-    ...
+def some_method() -> None: ...
 
 
 @count("named_counter")
-def another_method() -> None:
-    ...
+def another_method() -> None: ...
 
 
 def main() -> None:
@@ -93,9 +91,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
@@ -127,7 +125,7 @@ from pylemetry.meters import Timer
 
 
 def some_method() -> None:
-    timer = Timer()
+    timer = Timer("example")
 
     for _ in range(100):
         with timer.time():
@@ -145,20 +143,18 @@ from pylemetry.decorators import time
 
 
 @time()
-def some_method() -> None:
-    ...
+def some_method() -> None: ...
 
 
 @time("named_timer")
-def another_method() -> None:
-    ...
+def another_method() -> None: ...
 
 
 def main() -> None:
     for _ in range(100):
         some_method()
         another_method()
-        
+
     timer = registry.get_timer("some_method")
     timer.get_count()  # 100
     timer.get_value()  # Sum total execution time of the some_method function
@@ -173,6 +169,53 @@ 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.
@@ -183,13 +226,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.
@@ -200,9 +243,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
@@ -226,6 +269,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.4 → pylemetry-1.2.1}/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
@@ -37,13 +37,11 @@ from pylemetry.decorators import count
 
 
 @count()
-def some_method() -> None:
-    ...
+def some_method() -> None: ...
 
 
 @count("named_counter")
-def another_method() -> None:
-    ...
+def another_method() -> None: ...
 
 
 def main() -> None:
@@ -70,9 +68,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 +102,7 @@ from pylemetry.meters import Timer
 
 
 def some_method() -> None:
-    timer = Timer()
+    timer = Timer("example")
 
     for _ in range(100):
         with timer.time():
@@ -122,20 +120,18 @@ from pylemetry.decorators import time
 
 
 @time()
-def some_method() -> None:
-    ...
+def some_method() -> None: ...
 
 
 @time("named_timer")
-def another_method() -> None:
-    ...
+def another_method() -> None: ...
 
 
 def main() -> None:
     for _ in range(100):
         some_method()
         another_method()
-        
+
     timer = registry.get_timer("some_method")
     timer.get_count()  # 100
     timer.get_value()  # Sum total execution time of the some_method function
@@ -150,6 +146,53 @@ 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 +203,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 +220,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 +246,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.4 → pylemetry-1.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pylemetry"
-version = "1.1.4"
+version = "1.2.1"
 description = "A Python metrics library"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -60,7 +60,7 @@ explicit_package_bases = true
 line-length = 120
 
 [tool.ruff.lint]
-select = ["E", "F", "B"]
+select = ["ARG", "B", "E", "F", "I", "N", "RUF", "TID", "UP", "W"]
 
 [tool.pytest.ini_options]
 addopts = "--cov=pylemetry --cov-report=html"

{pylemetry-1.1.4 → pylemetry-1.2.1}/src/pylemetry/decorators/__init__.py

@@ -1,5 +1,4 @@
 from .count import count
 from .time import time
 
-
 __all__ = ["count", "time"]

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

@@ -0,0 +1,78 @@
+import re
+from collections.abc import Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+from pylemetry import registry
+from pylemetry.meters import Counter
+
+P = ParamSpec("P")
+R = TypeVar("R", covariant=True)
+
+
+def count(
+    name: str | None = None, tags: dict[str, str | int | float] | None = 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, 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