wirez-py 1.0.0__tar.gz

wirez_py-1.0.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: wirez-py
+Version: 1.0.0
+Summary: Remember and retrieve file paths by name — from any program, anywhere.
+Author: 
+License: MIT
+Project-URL: Homepage, https://github.com/kulbir/wires
+Keywords: files,path,registry,bookmark,wires
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Dynamic: requires-python
+
+# wires
+
+**Remember and retrieve file paths by name — from any program, anywhere.**
+
+```
+pip install wires
+```
+
+---
+
+## Usage
+
+```python
+import wires
+
+# Save / remember a file
+wires.save("my_config", "/path/to/config.json")
+wires.remember("my_config", "/path/to/config.json")  # same thing
+
+# Retrieve it later — from any program
+wires.get("my_config")     # → "/path/to/config.json"  (str)
+wires.recall("my_config")  # same thing
+wires.path("my_config")    # → pathlib.Path
+
+# See all saved files
+wires.list_all()  # → {"my_config": "/path/to/config.json", ...}
+
+# Remove
+wires.remove("my_config")
+```
+
+## How it works
+
+Wires stores all registrations in `~/.wires/registry.json`. Every program on the machine shares this registry, so a path saved in one script is instantly accessible in another.
+
+## License
+
+MIT

wirez_py-1.0.0/README.md

@@ -0,0 +1,38 @@
+# wires
+
+**Remember and retrieve file paths by name — from any program, anywhere.**
+
+```
+pip install wires
+```
+
+---
+
+## Usage
+
+```python
+import wires
+
+# Save / remember a file
+wires.save("my_config", "/path/to/config.json")
+wires.remember("my_config", "/path/to/config.json")  # same thing
+
+# Retrieve it later — from any program
+wires.get("my_config")     # → "/path/to/config.json"  (str)
+wires.recall("my_config")  # same thing
+wires.path("my_config")    # → pathlib.Path
+
+# See all saved files
+wires.list_all()  # → {"my_config": "/path/to/config.json", ...}
+
+# Remove
+wires.remove("my_config")
+```
+
+## How it works
+
+Wires stores all registrations in `~/.wires/registry.json`. Every program on the machine shares this registry, so a path saved in one script is instantly accessible in another.
+
+## License
+
+MIT

wirez_py-1.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wirez-py"
+version = "1.0.0"
+description = "Remember and retrieve file paths by name — from any program, anywhere."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["files", "path", "registry", "bookmark", "wires"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/kulbir/wires"

wirez_py-1.0.0/setup.cfg

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

wirez_py-1.0.0/setup.py

@@ -0,0 +1,10 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="wirez-py",
+    version="1.0.0",
+    description="Remember and retrieve file paths by name, across any program.",
+    author="",
+    python_requires=">=3.10",
+    packages=find_packages(),
+)

wirez_py-1.0.0/tests/test_wires.py

@@ -0,0 +1,183 @@
+"""
+wires test suite
+Run with: pytest tests/ -v
+"""
+
+import pytest
+import tempfile
+import os
+from pathlib import Path
+
+import wires
+from wires import registry, debug as dbg
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
+@pytest.fixture(autouse=True)
+def isolated_registry(tmp_path, monkeypatch):
+    """Redirect the registry to a temp dir so tests never touch ~/.wires"""
+    reg_dir = tmp_path / ".wires"
+    reg_file = reg_dir / "registry.json"
+    monkeypatch.setattr(registry, "_REGISTRY_DIR", reg_dir)
+    monkeypatch.setattr(registry, "_REGISTRY_FILE", reg_file)
+    yield reg_file
+
+
+@pytest.fixture
+def real_file(tmp_path):
+    """A real file on disk to use in tests."""
+    f = tmp_path / "real.txt"
+    f.write_text("hello")
+    return str(f)
+
+
+@pytest.fixture
+def fake_path():
+    return "/nonexistent/path/file.txt"
+
+
+# ── save / remember ───────────────────────────────────────────────────────────
+
+class TestSave:
+    def test_save_stores_path(self, real_file):
+        wires.save("myfile", real_file)
+        assert wires.get("myfile") == str(Path(real_file).resolve())
+
+    def test_remember_is_alias_for_save(self, real_file):
+        wires.remember("alias", real_file)
+        assert wires.get("alias") == str(Path(real_file).resolve())
+
+    def test_save_overwrites_existing(self, real_file, tmp_path):
+        second = tmp_path / "second.txt"
+        second.write_text("world")
+        wires.save("key", real_file)
+        wires.save("key", str(second))
+        assert wires.get("key") == str(second.resolve())
+
+    def test_save_resolves_relative_path(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        f = tmp_path / "rel.txt"
+        f.write_text("x")
+        wires.save("rel", "rel.txt")
+        result = wires.get("rel")
+        assert Path(result).is_absolute()
+
+    def test_save_nonexistent_file_still_works(self, fake_path):
+        # should not raise — just warn
+        wires.save("ghost", fake_path)
+        assert "ghost" in wires.list_all()
+
+
+# ── get / recall ──────────────────────────────────────────────────────────────
+
+class TestGet:
+    def test_get_returns_string(self, real_file):
+        wires.save("f", real_file)
+        result = wires.get("f")
+        assert isinstance(result, str)
+
+    def test_recall_is_alias_for_get(self, real_file):
+        wires.save("f", real_file)
+        assert wires.recall("f") == wires.get("f")
+
+    def test_get_missing_raises_key_error(self):
+        with pytest.raises(KeyError, match="nothere"):
+            wires.get("nothere")
+
+    def test_path_returns_path_object(self, real_file):
+        wires.save("f", real_file)
+        result = wires.path("f")
+        assert isinstance(result, Path)
+
+    def test_path_missing_raises_key_error(self):
+        with pytest.raises(KeyError):
+            wires.path("missing")
+
+
+# ── remove ────────────────────────────────────────────────────────────────────
+
+class TestRemove:
+    def test_remove_deletes_entry(self, real_file):
+        wires.save("x", real_file)
+        wires.remove("x")
+        assert "x" not in wires.list_all()
+
+    def test_remove_missing_raises_key_error(self):
+        with pytest.raises(KeyError):
+            wires.remove("doesnotexist")
+
+    def test_remove_then_get_raises(self, real_file):
+        wires.save("x", real_file)
+        wires.remove("x")
+        with pytest.raises(KeyError):
+            wires.get("x")
+
+
+# ── list_all ──────────────────────────────────────────────────────────────────
+
+class TestListAll:
+    def test_empty_registry(self):
+        assert wires.list_all() == {}
+
+    def test_lists_multiple_entries(self, real_file, tmp_path):
+        b = tmp_path / "b.txt"
+        b.write_text("b")
+        wires.save("a", real_file)
+        wires.save("b", str(b))
+        result = wires.list_all()
+        assert "a" in result
+        assert "b" in result
+
+    def test_list_all_is_copy(self, real_file):
+        wires.save("k", real_file)
+        result = wires.list_all()
+        result["injected"] = "evil"
+        assert "injected" not in wires.list_all()
+
+
+# ── debug system ──────────────────────────────────────────────────────────────
+
+class TestDebug:
+    def test_debug_log_outputs_to_stderr(self, capsys, real_file):
+        wires.enable_debug(True)
+        wires.save("d", real_file)
+        captured = capsys.readouterr()
+        assert "[wires debug]" in captured.err or "[wires ok]" in captured.err
+        wires.enable_debug(False)
+
+    def test_debug_off_produces_no_output(self, capsys, real_file):
+        wires.enable_debug(False)
+        wires.save("silent", real_file)
+        wires.get("silent")
+        captured = capsys.readouterr()
+        assert "[wires debug]" not in captured.err
+
+    def test_warn_on_overwrite(self, capsys, real_file):
+        wires.enable_warnings(True)
+        wires.save("w", real_file)
+        wires.save("w", real_file)
+        captured = capsys.readouterr()
+        assert "[wires warn]" in captured.err
+
+    def test_warn_on_missing_file(self, capsys, fake_path):
+        wires.enable_warnings(True)
+        wires.save("ghost", fake_path)
+        captured = capsys.readouterr()
+        assert "[wires warn]" in captured.err
+
+    def test_warn_stale_path_in_list_all(self, capsys, real_file, tmp_path):
+        wires.enable_warnings(True)
+        wires.save("stale", real_file)
+        # delete the file after saving
+        Path(real_file).unlink()
+        wires.list_all()
+        captured = capsys.readouterr()
+        assert "[wires warn]" in captured.err
+
+    def test_disable_warnings(self, capsys, fake_path):
+        wires.enable_warnings(False)
+        wires.save("q", fake_path)
+        captured = capsys.readouterr()
+        assert "[wires warn]" not in captured.err
+        wires.enable_warnings(True)

wirez_py-1.0.0/wires/__init__.py

@@ -0,0 +1,37 @@
+"""
+wires — remember and retrieve file paths by name.
+"""
+
+from .registry import save, remember, get, recall, remove, list_all, path
+from .debug import enable_debug, enable_warnings
+
+__all__ = [
+    "save", "remember",
+    "get", "recall",
+    "remove", "list_all", "path",
+    "enable_debug", "enable_warnings",
+]
+
+print(r"""
+         _____                    _____                    _____                    _____                    _____
+        /\    \                  /\    \                  /\    \                  /\    \                  /\    \
+       /::\____\                /::\    \                /::\    \                /::\    \                /::\    \
+      /:::/    /                \:::\    \              /::::\    \              /::::\    \              /::::\    \
+     /:::/   _/___               \:::\    \            /::::::\    \            /::::::\    \            /::::::\    \
+    /:::/   /\    \               \:::\    \          /:::/\:::\    \          /:::/\:::\    \          /:::/\:::\    \
+   /:::/   /::\____\               \:::\    \        /:::/__\:::\    \        /:::/__\:::\    \        /:::/__\:::\    \
+  /:::/   /:::/    /               /::::\    \      /::::\   \:::\    \      /::::\   \:::\    \       \:::\   \:::\    \
+ /:::/   /:::/   _/___    ____    /::::::\    \    /::::::\   \:::\    \    /::::::\   \:::\    \    ___\:::\   \:::\    \
+/:::/___/:::/   /\    \  /\   \  /:::/\:::\    \  /:::/\:::\   \:::\____\  /:::/\:::\   \:::\    \  /\   \:::\   \:::\    \
+|:::|   /:::/   /::\____\/::\   \/:::/  \:::\____\/:::/  \:::\   \:::|    |/:::/__\:::\   \:::\____\/::\   \:::\   \:::\____\
+|:::|__/:::/   /:::/    /\:::\  /:::/    \::/    /\::/   |::::\  /:::|____|\:::\   \:::\   \::/    /\:::\   \:::\   \::/    /
+ \:::\/:::/   /:::/    /  \:::\/:::/    / \/____/  \/____|:::::\/:::/    /  \:::\   \:::\   \/____/  \:::\   \:::\   \/____/
+  \::::::/   /:::/    /    \::::::/    /                 |:::::::::/    /    \:::\   \:::\    \       \:::\   \:::\    \
+   \::::/___/:::/    /      \::::/____/                  |::|\::::/    /      \:::\   \:::\____\       \:::\   \:::\____\
+    \:::\__/:::/    /        \:::\    \                  |::| \::/____/        \:::\   \::/    /        \:::\  /:::/    /
+     \::::::::/    /          \:::\    \                 |::|  ~|               \:::\   \/____/          \:::\/:::/    /
+      \::::::/    /            \:::\    \                |::|   |                \:::\    \               \::::::/    /
+       \::::/    /              \:::\____\               \::|   |                 \:::\____\               \::::/    /
+        \::/____/                \::/    /                \:|   |                  \::/    /                \::/    /
+         ~~                       \/____/                  \|___|                   \/____/                  \/____/
+""")

wirez_py-1.0.0/wires/debug.py

@@ -0,0 +1,47 @@
+import os
+import sys
+
+_debug_enabled = False
+_warn_enabled = True
+
+RESET  = "\033[0m"
+YELLOW = "\033[93m"
+RED    = "\033[91m"
+CYAN   = "\033[96m"
+GREEN  = "\033[92m"
+BOLD   = "\033[1m"
+
+_SUPPORTS_COLOR = hasattr(sys.stdout, "isatty") and sys.stdout.isatty()
+
+
+def _color(code: str, text: str) -> str:
+    return f"{code}{text}{RESET}" if _SUPPORTS_COLOR else text
+
+
+def enable_debug(on: bool = True) -> None:
+    global _debug_enabled
+    _debug_enabled = on
+
+
+def enable_warnings(on: bool = True) -> None:
+    global _warn_enabled
+    _warn_enabled = on
+
+
+def log(msg: str) -> None:
+    if _debug_enabled:
+        print(_color(CYAN, f"[wires debug] {msg}"), file=sys.stderr)
+
+
+def warn(msg: str) -> None:
+    if _warn_enabled:
+        print(_color(YELLOW, f"[wires warn]  {msg}"), file=sys.stderr)
+
+
+def error(msg: str) -> None:
+    print(_color(RED, f"[wires error] {msg}"), file=sys.stderr)
+
+
+def ok(msg: str) -> None:
+    if _debug_enabled:
+        print(_color(GREEN, f"[wires ok]    {msg}"), file=sys.stderr)

wirez_py-1.0.0/wires/registry.py

@@ -0,0 +1,94 @@
+import json
+import os
+from pathlib import Path
+from . import debug as _dbg
+
+_REGISTRY_DIR = Path.home() / ".wires"
+_REGISTRY_FILE = _REGISTRY_DIR / "registry.json"
+
+
+def _load() -> dict:
+    if not _REGISTRY_FILE.exists():
+        _dbg.log(f"Registry not found at {_REGISTRY_FILE}, starting empty")
+        return {}
+    with open(_REGISTRY_FILE, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    _dbg.log(f"Loaded registry ({len(data)} entries)")
+    return data
+
+
+def _dump(data: dict) -> None:
+    _REGISTRY_DIR.mkdir(parents=True, exist_ok=True)
+    with open(_REGISTRY_FILE, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+    _dbg.log(f"Registry saved to {_REGISTRY_FILE}")
+
+
+def save(name: str, file_path: str | os.PathLike) -> None:
+    """Register a file path under a name."""
+    resolved = str(Path(file_path).resolve())
+
+    data = _load()
+
+    if name in data:
+        _dbg.warn(f"'{name}' already exists ({data[name]}) — overwriting with {resolved}")
+    else:
+        _dbg.log(f"Registering new wire: '{name}' → {resolved}")
+
+    if not Path(resolved).exists():
+        _dbg.warn(f"The file '{resolved}' does not exist on disk — saving path anyway")
+
+    data[name] = resolved
+    _dump(data)
+    _dbg.ok(f"Saved '{name}'")
+
+
+# alias
+remember = save
+
+
+def get(name: str) -> str:
+    """Return the path string registered under name."""
+    data = _load()
+    if name not in data:
+        _dbg.error(f"No wire named '{name}' — available: {list(data.keys())}")
+        raise KeyError(f"No wire named '{name}'")
+
+    result = data[name]
+    _dbg.log(f"Retrieved '{name}' → {result}")
+
+    if not Path(result).exists():
+        _dbg.warn(f"Wire '{name}' points to '{result}' which no longer exists on disk")
+
+    return result
+
+
+# alias
+recall = get
+
+
+def path(name: str) -> Path:
+    """Return the registered path as a pathlib.Path."""
+    return Path(get(name))
+
+
+def remove(name: str) -> None:
+    """Unregister a name."""
+    data = _load()
+    if name not in data:
+        _dbg.error(f"Cannot remove '{name}' — not found. Available: {list(data.keys())}")
+        raise KeyError(f"No wire named '{name}'")
+    old = data.pop(name)
+    _dump(data)
+    _dbg.ok(f"Removed '{name}' (was → {old})")
+
+
+def list_all() -> dict[str, str]:
+    """Return a copy of all registered name→path mappings."""
+    data = _load()
+    _dbg.log(f"Listing all wires: {list(data.keys())}")
+    # warn about any stale paths
+    for name, p in data.items():
+        if not Path(p).exists():
+            _dbg.warn(f"Stale wire: '{name}' → '{p}' (file not found)")
+    return dict(data)

wirez_py-1.0.0/wirez_py.egg-info/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: wirez-py
+Version: 1.0.0
+Summary: Remember and retrieve file paths by name — from any program, anywhere.
+Author: 
+License: MIT
+Project-URL: Homepage, https://github.com/kulbir/wires
+Keywords: files,path,registry,bookmark,wires
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Dynamic: requires-python
+
+# wires
+
+**Remember and retrieve file paths by name — from any program, anywhere.**
+
+```
+pip install wires
+```
+
+---
+
+## Usage
+
+```python
+import wires
+
+# Save / remember a file
+wires.save("my_config", "/path/to/config.json")
+wires.remember("my_config", "/path/to/config.json")  # same thing
+
+# Retrieve it later — from any program
+wires.get("my_config")     # → "/path/to/config.json"  (str)
+wires.recall("my_config")  # same thing
+wires.path("my_config")    # → pathlib.Path
+
+# See all saved files
+wires.list_all()  # → {"my_config": "/path/to/config.json", ...}
+
+# Remove
+wires.remove("my_config")
+```
+
+## How it works
+
+Wires stores all registrations in `~/.wires/registry.json`. Every program on the machine shares this registry, so a path saved in one script is instantly accessible in another.
+
+## License
+
+MIT

wirez_py-1.0.0/wirez_py.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+setup.py
+tests/test_wires.py
+wires/__init__.py
+wires/debug.py
+wires/registry.py
+wirez_py.egg-info/PKG-INFO
+wirez_py.egg-info/SOURCES.txt
+wirez_py.egg-info/dependency_links.txt
+wirez_py.egg-info/top_level.txt

wirez_py-1.0.0/wirez_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

wirez_py-1.0.0/wirez_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+wires