gadget-timer 0.1.0__tar.gz

gadget_timer-0.1.0/LICENSE

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

gadget_timer-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: gadget-timer
+Version: 0.1.0
+Summary: Tiny timing helper for printing elapsed times with call-site context
+Author: Sam Maddrell-Mander
+License: MIT
+Project-URL: Homepage, https://github.com/s-maddrellmander/gadget
+Project-URL: Repository, https://github.com/s-maddrellmander/gadget
+Project-URL: Issues, https://github.com/s-maddrellmander/gadget/issues
+Keywords: timing,debugging,profiling,logging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# gadget
+
+[![Tests](https://github.com/s-maddrellmander/gadget/actions/workflows/tests.yml/badge.svg)](https://github.com/s-maddrellmander/gadget/actions/workflows/tests.yml)
+
+A tiny helper for quick timing/debug prints with file and line context.
+
+## Install
+
+### From a local checkout
+
+```bash
+pip install .
+```
+
+### Directly from GitHub
+
+```bash
+pip install "git+https://github.com/s-maddrellmander/gadget.git"
+```
+
+### Editable install (for development)
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+### Functional API
+
+```python
+from gadget import gadget, gadget_reset, gadget_config
+
+gadget("start")
+# ... some code ...
+gadget("after step")
+
+gadget("phase 1", group="build")
+gadget("phase 2", group="build")
+gadget_reset("build")
+
+gadget_config(verbose=False)  # disable output globally
+```
+
+### Class-based API
+
+```python
+from gadget import Gadget
+
+timer = Gadget(verbose=True)
+timer("start")
+# ... some code ...
+timer("step", group="build")
+timer.reset("build")
+timer.reset()  # reset all groups
+```
+
+## Install from PyPI
+
+```bash
+pip install gadget-timer
+```
+
+## Notes
+
+- Package name on PyPI is `gadget-timer`.
+- Import path is still `gadget`.
+- For Git installs, the repository URL is:
+
+  ```bash
+  pip install "git+https://github.com/s-maddrellmander/gadget.git"
+  ```

gadget_timer-0.1.0/README.md

@@ -0,0 +1,72 @@
+# gadget
+
+[![Tests](https://github.com/s-maddrellmander/gadget/actions/workflows/tests.yml/badge.svg)](https://github.com/s-maddrellmander/gadget/actions/workflows/tests.yml)
+
+A tiny helper for quick timing/debug prints with file and line context.
+
+## Install
+
+### From a local checkout
+
+```bash
+pip install .
+```
+
+### Directly from GitHub
+
+```bash
+pip install "git+https://github.com/s-maddrellmander/gadget.git"
+```
+
+### Editable install (for development)
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+### Functional API
+
+```python
+from gadget import gadget, gadget_reset, gadget_config
+
+gadget("start")
+# ... some code ...
+gadget("after step")
+
+gadget("phase 1", group="build")
+gadget("phase 2", group="build")
+gadget_reset("build")
+
+gadget_config(verbose=False)  # disable output globally
+```
+
+### Class-based API
+
+```python
+from gadget import Gadget
+
+timer = Gadget(verbose=True)
+timer("start")
+# ... some code ...
+timer("step", group="build")
+timer.reset("build")
+timer.reset()  # reset all groups
+```
+
+## Install from PyPI
+
+```bash
+pip install gadget-timer
+```
+
+## Notes
+
+- Package name on PyPI is `gadget-timer`.
+- Import path is still `gadget`.
+- For Git installs, the repository URL is:
+
+  ```bash
+  pip install "git+https://github.com/s-maddrellmander/gadget.git"
+  ```

gadget_timer-0.1.0/gadget.py

@@ -0,0 +1,103 @@
+import inspect
+import time
+import sys
+import os
+import shutil
+import re
+
+__version__ = "0.1.0"
+
+class Gadget:
+    def __init__(self, verbose=True):
+        self.verbose = verbose
+        self.t0 = None
+        self.group_times = {}
+    
+    def __call__(self, s='', group=None, _caller_frame=None):
+        """Make the instance callable like a function."""
+        if not self.verbose:
+            return
+            
+        current_time = time.time()
+        if self.t0 is None:
+            self.t0 = current_time
+        elapsed = current_time - self.t0
+        self.t0 = time.time()
+
+        # Use provided caller frame or get it from stack
+        if _caller_frame is None:
+            caller_frame = inspect.currentframe().f_back
+        else:
+            caller_frame = _caller_frame
+        frame_info = inspect.getframeinfo(caller_frame)
+
+        line_number = frame_info.lineno
+
+        try:
+            with open(frame_info.filename, 'r') as f:
+                lines = f.readlines()
+                line_content = lines[line_number - 2].rstrip()
+        except:
+            line_content = ""
+
+        green_color = "\033[32m"
+        reset_color = "\033[0m"
+        
+        # Shorten the file path - make it relative to cwd or just use filename
+        try:
+            short_path = os.path.relpath(frame_info.filename)
+        except:
+            short_path = os.path.basename(frame_info.filename)
+        
+        # Clickable file path for VS Code
+        file_link = f"{short_path}:{line_number}"
+        
+        # Handle group tracking
+        group_info = ""
+        if group:
+            if group not in self.group_times:
+                self.group_times[group] = 0.0
+            self.group_times[group] += elapsed
+            group_info = f" [{group}: {elapsed:.6f}s (total: {self.group_times[group]:.6f}s)]"
+        
+        # Build the left side of the output
+        left_output = f"{green_color}[line={line_number}] {elapsed:.6f}s {line_content}{reset_color} {s}{group_info}"
+        
+        # Get terminal width and right-align the file link
+        terminal_width = shutil.get_terminal_size().columns
+        # Strip ANSI codes for accurate length calculation
+        left_output_plain = re.sub(r'\033\[[0-9;]+m', '', left_output)
+        left_length = len(left_output_plain)
+        
+        # Calculate padding needed
+        file_link_display = f"→ {file_link}"
+        padding_needed = terminal_width - left_length - len(file_link_display) - 1
+        padding = " " * max(1, padding_needed)  # At least one space
+        
+        output = f"{left_output}{padding}{file_link_display}"
+        print(output)
+    
+    def reset(self, group=None):
+        """Reset group timer(s). If group is None, reset all groups."""
+        if group is None:
+            self.group_times = {}
+        elif group in self.group_times:
+            del self.group_times[group]
+
+# Create a default instance for convenience
+_default_gadget = Gadget()
+
+# Convenience functions that use the default instance
+def gadget(s='', group=None):
+    """Convenience function using default Gadget instance."""
+    caller_frame = inspect.currentframe().f_back
+    _default_gadget(s, group, _caller_frame=caller_frame)
+
+def gadget_reset(group=None):
+    """Convenience function using default Gadget instance."""
+    _default_gadget.reset(group)
+
+def gadget_config(verbose=True):
+    """Configure the default Gadget instance."""
+    global _default_gadget
+    _default_gadget = Gadget(verbose=verbose)

gadget_timer-0.1.0/gadget_timer.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: gadget-timer
+Version: 0.1.0
+Summary: Tiny timing helper for printing elapsed times with call-site context
+Author: Sam Maddrell-Mander
+License: MIT
+Project-URL: Homepage, https://github.com/s-maddrellmander/gadget
+Project-URL: Repository, https://github.com/s-maddrellmander/gadget
+Project-URL: Issues, https://github.com/s-maddrellmander/gadget/issues
+Keywords: timing,debugging,profiling,logging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# gadget
+
+[![Tests](https://github.com/s-maddrellmander/gadget/actions/workflows/tests.yml/badge.svg)](https://github.com/s-maddrellmander/gadget/actions/workflows/tests.yml)
+
+A tiny helper for quick timing/debug prints with file and line context.
+
+## Install
+
+### From a local checkout
+
+```bash
+pip install .
+```
+
+### Directly from GitHub
+
+```bash
+pip install "git+https://github.com/s-maddrellmander/gadget.git"
+```
+
+### Editable install (for development)
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+### Functional API
+
+```python
+from gadget import gadget, gadget_reset, gadget_config
+
+gadget("start")
+# ... some code ...
+gadget("after step")
+
+gadget("phase 1", group="build")
+gadget("phase 2", group="build")
+gadget_reset("build")
+
+gadget_config(verbose=False)  # disable output globally
+```
+
+### Class-based API
+
+```python
+from gadget import Gadget
+
+timer = Gadget(verbose=True)
+timer("start")
+# ... some code ...
+timer("step", group="build")
+timer.reset("build")
+timer.reset()  # reset all groups
+```
+
+## Install from PyPI
+
+```bash
+pip install gadget-timer
+```
+
+## Notes
+
+- Package name on PyPI is `gadget-timer`.
+- Import path is still `gadget`.
+- For Git installs, the repository URL is:
+
+  ```bash
+  pip install "git+https://github.com/s-maddrellmander/gadget.git"
+  ```

gadget_timer-0.1.0/gadget_timer.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+gadget.py
+pyproject.toml
+gadget_timer.egg-info/PKG-INFO
+gadget_timer.egg-info/SOURCES.txt
+gadget_timer.egg-info/dependency_links.txt
+gadget_timer.egg-info/requires.txt
+gadget_timer.egg-info/top_level.txt
+tests/test_gadget.py

gadget_timer-0.1.0/gadget_timer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gadget_timer-0.1.0/gadget_timer.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=8.0
+pytest-cov>=5.0

gadget_timer-0.1.0/gadget_timer.egg-info/top_level.txt

@@ -0,0 +1 @@
+gadget

gadget_timer-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gadget-timer"
+version = "0.1.0"
+description = "Tiny timing helper for printing elapsed times with call-site context"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+  { name = "Sam Maddrell-Mander" }
+]
+license = { text = "MIT" }
+keywords = ["timing", "debugging", "profiling", "logging"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12"
+]
+
+[project.urls]
+Homepage = "https://github.com/s-maddrellmander/gadget"
+Repository = "https://github.com/s-maddrellmander/gadget"
+Issues = "https://github.com/s-maddrellmander/gadget/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0"
+]
+
+[tool.setuptools]
+py-modules = ["gadget"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q --cov=gadget --cov-report=term-missing --cov-fail-under=100"
+
+[tool.coverage.run]
+branch = true
+source = ["gadget"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 100

gadget_timer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gadget_timer-0.1.0/tests/test_gadget.py

@@ -0,0 +1,128 @@
+from types import SimpleNamespace
+
+import gadget as gadget_module
+
+
+class DummySize:
+    columns = 120
+
+
+def test_gadget_call_updates_group_and_prints(monkeypatch, capsys):
+    g = gadget_module.Gadget(verbose=True)
+
+    times = iter([10.0, 10.5, 12.0, 12.2, 13.0, 14.0])
+    monkeypatch.setattr(gadget_module.time, "time", lambda: next(times))
+
+    monkeypatch.setattr(
+        gadget_module.inspect,
+        "getframeinfo",
+        lambda _frame: SimpleNamespace(lineno=2, filename="fake_file.py"),
+    )
+
+    class FakeFile:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            return False
+
+        def readlines(self):
+            return ["line1\n", "line2\n", "line3\n"]
+
+    monkeypatch.setattr("builtins.open", lambda *args, **kwargs: FakeFile())
+    monkeypatch.setattr(gadget_module.os.path, "relpath", lambda _p: "fake_file.py")
+    monkeypatch.setattr(gadget_module.shutil, "get_terminal_size", lambda: DummySize())
+
+    g("first", group="phase")
+    g("second", group="phase")
+    g("third", _caller_frame="explicit_frame")
+
+    out = capsys.readouterr().out
+    assert "first" in out
+    assert "second" in out
+    assert "third" in out
+    assert "[phase:" in out
+    assert g.group_times["phase"] == 1.5
+
+
+def test_gadget_call_handles_open_and_relpath_errors(monkeypatch, capsys):
+    g = gadget_module.Gadget(verbose=True)
+
+    times = iter([20.0, 20.25])
+    monkeypatch.setattr(gadget_module.time, "time", lambda: next(times))
+
+    monkeypatch.setattr(
+        gadget_module.inspect,
+        "currentframe",
+        lambda: SimpleNamespace(f_back="fake_frame"),
+    )
+    monkeypatch.setattr(
+        gadget_module.inspect,
+        "getframeinfo",
+        lambda _frame: SimpleNamespace(lineno=1, filename="/tmp/does-not-exist.py"),
+    )
+    monkeypatch.setattr("builtins.open", lambda *args, **kwargs: (_ for _ in ()).throw(OSError("boom")))
+    monkeypatch.setattr(
+        gadget_module.os.path,
+        "relpath",
+        lambda _p: (_ for _ in ()).throw(ValueError("bad path")),
+    )
+    monkeypatch.setattr(gadget_module.shutil, "get_terminal_size", lambda: DummySize())
+
+    g("hello")
+    out = capsys.readouterr().out
+    assert "hello" in out
+    assert "does-not-exist.py:1" in out
+
+
+def test_gadget_early_return_when_not_verbose(capsys):
+    g = gadget_module.Gadget(verbose=False)
+    g("silent")
+    assert capsys.readouterr().out == ""
+
+
+def test_reset_branches():
+    g = gadget_module.Gadget()
+    g.group_times = {"a": 1.0, "b": 2.0}
+
+    g.reset("a")
+    assert g.group_times == {"b": 2.0}
+
+    g.reset("missing")
+    assert g.group_times == {"b": 2.0}
+
+    g.reset()
+    assert g.group_times == {}
+
+
+def test_convenience_functions_and_config(monkeypatch):
+    calls = []
+
+    class StubDefault:
+        def __call__(self, s, group, _caller_frame=None):
+            calls.append(("call", s, group, _caller_frame))
+
+        def reset(self, group=None):
+            calls.append(("reset", group))
+
+    stub = StubDefault()
+    monkeypatch.setattr(gadget_module, "_default_gadget", stub)
+    monkeypatch.setattr(
+        gadget_module.inspect,
+        "currentframe",
+        lambda: SimpleNamespace(f_back="callsite_frame"),
+    )
+
+    gadget_module.gadget("msg", group="grp")
+    gadget_module.gadget_reset("grp")
+
+    assert calls[0] == ("call", "msg", "grp", "callsite_frame")
+    assert calls[1] == ("reset", "grp")
+
+    gadget_module.gadget_config(verbose=False)
+    assert isinstance(gadget_module._default_gadget, gadget_module.Gadget)
+    assert gadget_module._default_gadget.verbose is False
+
+
+def test_version_export():
+    assert gadget_module.__version__ == "0.1.0"