symref 0.1.0__py3-none-any.whl

symref/__init__.py

@@ -0,0 +1,14 @@
+from symref._ref import ref
+from symref._validate import SymrefError, validate_refs
+
+
+def clear_refs() -> None:
+    """
+    Clear the global ref registry.
+
+    Useful for test isolation when tests register their own refs.
+    """
+    ref._registry.clear()
+
+
+__all__ = ["SymrefError", "clear_refs", "ref", "validate_refs"]

symref/_ref.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import ClassVar, Self
+
+from symref._source import _capture_source
+
+
+class ref(str):  # noqa: N801
+    """
+    A ``str`` subclass that acts as a forward reference to a dotted import path.
+
+    Every ``ref`` instance is registered in a global registry so that all
+    references can later be validated in one shot via
+    :func:`~symref.validate_refs`.  Because ``ref`` inherits from ``str``,
+    frameworks that accept dotted-path strings (Celery, Django, etc.) can
+    consume it transparently.
+    """
+
+    __slots__ = ("_kind", "_source")
+
+    _registry: ClassVar[list[ref]] = []
+    _kind: str | None
+    _source: tuple[str, int]
+
+    def __new__(cls, value: str, *, kind: str | None = None) -> Self:
+        """
+        Create a new forward reference.
+
+        Args:
+            value: Fully-qualified dotted import path (e.g.
+                ``"myapp.tasks.send_email"``).
+            kind: Optional label used to filter validation (e.g.
+                ``"celery_task"``).
+
+        """
+        instance = super().__new__(cls, value)
+        instance._kind = kind
+        instance._source = _capture_source()
+        cls._registry.append(instance)
+        return instance
+
+    def __reduce__(self) -> tuple[type, tuple[str]]:
+        """Pickle as a plain ``str`` to avoid re-registering on unpickle."""
+        return (str, (str(self),))

symref/_source.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from types import FrameType
+
+_PACKAGE_DIR = Path(__file__).parent.resolve()
+
+
+def _capture_source() -> tuple[str, int]:
+    """Walk the call stack to find the first frame outside the symref package."""
+    frame: FrameType | None = sys._getframe(1)  # noqa: SLF001
+    while frame is not None:
+        filename = frame.f_code.co_filename
+        try:
+            frame_path = Path(filename).resolve()
+        except (OSError, ValueError):
+            frame = frame.f_back
+            continue
+        if not frame_path.is_relative_to(_PACKAGE_DIR):
+            return (filename, frame.f_lineno)
+        frame = frame.f_back
+    return ("<unknown>", 0)

symref/_validate.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import importlib
+import importlib.util
+
+from symref._ref import ref
+
+
+class SymrefError(Exception):
+    """
+    Raised when one or more :class:`~symref.ref` paths cannot be resolved.
+
+    Attributes:
+        broken: List of :class:`~symref.ref` instances that failed to resolve.
+
+    """
+
+    def __init__(self, broken: list[ref]) -> None:
+        self.broken = broken
+        lines = [
+            f"{len(broken)} broken reference(s):",
+            *[f'  - "{r}" (defined in {r._source[0]}:{r._source[1]})' for r in broken],
+        ]
+        super().__init__("\n".join(lines))
+
+
+def _resolve(path: str) -> bool:
+    if not path:
+        return False
+
+    # 1. Try as a full module path
+    try:
+        spec = importlib.util.find_spec(path)
+    except (ImportError, ValueError):
+        spec = None
+
+    if spec is not None:
+        return True
+
+    # 2. Split on last dot — try parent as module, last part as attribute
+    if "." not in path:
+        return False
+
+    parent, _, attr = path.rpartition(".")
+    try:
+        parent_spec = importlib.util.find_spec(parent)
+    except (ImportError, ValueError):
+        parent_spec = None
+
+    if parent_spec is None:
+        return False
+
+    module = importlib.import_module(parent)
+    return hasattr(module, attr)
+
+
+def validate_refs(kind: str | None = None) -> None:
+    """
+    Validate that every registered :class:`~symref.ref` resolves.
+
+    Iterates over all refs in the global registry (optionally filtered by
+    *kind*) and checks that each dotted path points to a real module or
+    attribute.
+
+    Args:
+        kind: If given, only refs whose *kind* matches this value are checked.
+
+    Raises:
+        SymrefError: If any refs cannot be resolved.
+
+    """
+    targets = [r for r in ref._registry if kind is None or r._kind == kind]
+    broken = [r for r in targets if not _resolve(r)]
+    if broken:
+        raise SymrefError(broken)

symref-0.1.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: symref
+Version: 0.1.0
+Summary: Forward-referencing Python objects by dotted import path with refactor safety
+Project-URL: Repository, https://github.com/jpuglielli/symref
+Author: Josh Puglielli
+License-Expression: MIT
+License-File: LICENSE
+Keywords: celery,django,forward-reference,import-path,refactoring
+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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# symref
+
+Refactor-safe forward references for Python dotted import paths.
+
+Many frameworks (Celery, Django, etc.) accept dotted string paths as configuration. These strings are invisible to refactoring tools and IDEs -- renaming a module silently breaks them. `symref` wraps these paths in a `str` subclass that registers them for later validation, catching broken references in tests instead of production.
+
+## Installation
+
+```bash
+pip install symref
+```
+
+Requires Python 3.12+. No runtime dependencies.
+
+## Usage
+
+```python
+from symref import ref
+
+app.conf.task_routes = {
+    ref("myapp.tasks.send_email", kind="celery_task"): {"queue": "email"},
+    ref("myapp.tasks.process_order", kind="celery_task"): {"queue": "orders"},
+}
+```
+
+`ref()` returns a plain `str` -- frameworks see no difference. But each call is recorded in a global registry with its source location.
+
+### Validate in tests
+
+```python
+from symref import validate_refs
+
+def test_all_refs_resolve():
+    validate_refs()
+
+def test_celery_task_refs():
+    validate_refs(kind="celery_task")
+```
+
+If any path can't be resolved, `validate_refs()` raises `SymrefError` with all broken references and their source locations:
+
+```
+symref.SymrefError: 2 broken reference(s):
+  - "myapp.tasks.send_email" (defined in config/celery.py:8)
+  - "myapp.tasks.process_order" (defined in config/celery.py:9)
+```
+
+## API
+
+### `ref(path, *, kind=None)`
+
+Creates a forward reference. Returns a `str` subclass instance.
+
+- **`path`** -- fully qualified dotted import path (module or attribute)
+- **`kind`** *(optional)* -- arbitrary label for filtering validation (e.g. `"celery_task"`, `"django_app"`)
+
+### `validate_refs(kind=None)`
+
+Checks that every registered ref resolves to a real module or attribute. Raises `SymrefError` if any are broken. Pass `kind` to validate only refs with that label.
+
+### `SymrefError`
+
+Raised when one or more refs can't be resolved. The `.broken` attribute contains the list of broken `ref` instances.
+
+## How it works
+
+- `ref()` is a `str` subclass -- zero overhead after construction
+- Each `ref()` call appends to `ref._registry` and captures the caller's file/line via `sys._getframe()`
+- `validate_refs()` uses `importlib.util.find_spec()` to check modules. When verifying attributes, it imports the parent module via `importlib.import_module()` -- this may execute module-level code as a side effect
+- No imports happen at `ref()` construction time -- validation is fully deferred
+
+## Documentation
+
+Build and preview the docs locally:
+
+```bash
+uv run mkdocs serve
+```
+
+Then open <http://127.0.0.1:8000>.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and PR guidelines.
+
+## License
+
+MIT

symref-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+symref/__init__.py,sha256=hE2N7ZDkicd8zLy4vebUE5y_aQvW4VdsaGw9ZpBhcDA,322
+symref/_ref.py,sha256=SJGPi5sqxE_bd0bgenTiNtvjkX4VDrF_hItPg29jHDI,1391
+symref/_source.py,sha256=uOHIDfluaeC9eD9tA8uMdMe0iYHf02o0grTgOftJejg,780
+symref/_validate.py,sha256=SNw0iAg1LK6eXVec56pNcA4FqFwzOpRaqHihNIcxvWs,1940
+symref/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+symref-0.1.0.dist-info/METADATA,sha256=_Ng4-PHuJE9J0lcDy3fgNm65bDnsn9W1nlvVHbSSfh4,3437
+symref-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+symref-0.1.0.dist-info/licenses/LICENSE,sha256=5ol71F6e9XFKST5WrGqmNSC2hQZRwDFQw77cWcrH4d4,1071
+symref-0.1.0.dist-info/RECORD,,

symref-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

symref-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Josh Puglielli
+
+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.