symref 0.1.0__tar.gz

symref-0.1.0/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run ruff check:*)",
+      "Bash(uv run mypy:*)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv run:*)",
+      "WebSearch",
+      "WebFetch(domain:mkdocstrings.github.io)",
+      "WebFetch(domain:squidfund.github.io)",
+      "WebFetch(domain:squidfunk.github.io)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(uv sync:*)"
+    ]
+  }
+}

symref-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - run: uv run ruff check symref/ tests/
+      - run: uv run ruff format --check symref/ tests/
+      - run: uv run mypy symref/
+      - run: uv run pytest tests/ -v

symref-0.1.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

symref-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.1
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy symref/
+        language: system
+        types: [python]
+        pass_filenames: false

symref-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

symref-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to symref
+
+## Prerequisites
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/)
+
+## Setup
+
+```bash
+git clone https://github.com/jpuglielli/symref.git
+cd symref
+uv sync --group dev --group docs
+uv run pre-commit install
+```
+
+## Running tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+## Linting and type-checking
+
+```bash
+uv run ruff check symref/
+uv run mypy symref/
+```
+
+Pre-commit hooks run these automatically on each commit.
+
+## Building docs
+
+```bash
+uv run mkdocs serve
+```
+
+Then open <http://127.0.0.1:8000>.
+
+## PR workflow
+
+1. Create a feature branch from `main`.
+2. Make your changes and commit.
+3. Push the branch and open a pull request.
+4. Ensure CI passes before requesting review.

symref-0.1.0/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.

symref-0.1.0/Makefile

@@ -0,0 +1,27 @@
+.PHONY: install test lint typecheck format docs hooks
+
+install: ## Install dev and docs dependencies
+	uv sync --group dev --group docs
+
+hooks: ## Install pre-commit hooks
+	uv run pre-commit install
+
+test: ## Run tests
+	uv run pytest tests/ -v
+
+lint: ## Run ruff linter
+	uv run ruff check symref/
+
+typecheck: ## Run mypy
+	uv run mypy symref/
+
+format: ## Run ruff formatter
+	uv run ruff format symref/ tests/
+
+docs: ## Serve docs locally
+	uv run mkdocs serve
+
+check: lint typecheck test ## Run lint, typecheck, and tests
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'

symref-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,88 @@
+# 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/docs/api.md

@@ -0,0 +1,9 @@
+# API Reference
+
+::: symref.ref
+    options:
+      members: false
+
+::: symref.validate_refs
+
+::: symref.SymrefError

symref-0.1.0/docs/index.md

@@ -0,0 +1,64 @@
+# 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.
+
+## Quick start
+
+### Create refs
+
+```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)
+```
+
+## 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, and
+  imports the parent module only when verifying attributes
+- No imports happen at `ref()` construction time — validation is fully
+  deferred

symref-0.1.0/mkdocs.yml

@@ -0,0 +1,25 @@
+site_name: symref
+site_description: Refactor-safe forward references for Python dotted import paths.
+
+theme:
+  name: material
+  palette:
+    scheme: default
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [.]
+          options:
+            docstring_style: google
+            show_root_heading: true
+            show_source: true
+            merge_init_into_class: true
+            separate_signature: true
+            show_signature_annotations: true
+
+nav:
+  - Home: index.md
+  - API Reference: api.md

symref-0.1.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "symref"
+version = "0.1.0"
+description = "Forward-referencing Python objects by dotted import path with refactor safety"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{name = "Josh Puglielli"}]
+keywords = ["forward-reference", "import-path", "refactoring", "celery", "django"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/jpuglielli/symref"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pre-commit>=4.0",
+    "pytest>=8.0",
+    "ruff>=0.15.1",
+]
+docs = [
+    "mkdocs-material",
+    "mkdocstrings[python]",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["symref"]
+
+# Ruff 0.15.1
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # Missing docstrings
+    "D100", # Missing docstring in public module
+    "D101", # Missing docstring in public class
+    "D102", # Missing docstring in public method
+    "D103", # Missing docstring in public function
+    "D104", # Missing docstring in public package
+    "D105", # Missing docstring in magic method
+    "D106", # Missing docstring in public nested class
+    "D107", # Missing docstring in __init__
+
+    # D203 and D211 conflict — use D211 (no blank line before class docstring)
+    "D203",
+    # D212 and D213 conflict — use D213 (multi-line summary on second line)
+    "D212",
+
+    # COM812 and ISC001 conflict with the ruff formatter
+    "COM812",
+    "ISC001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",   # assert is fine in tests
+    "D",      # no docstring enforcement in tests
+    "SLF001", # tests access private members (_kind, _source, _registry)
+]
+"symref/__init__.py" = [
+    "SLF001", # clear_refs() accesses ref._registry
+]
+"symref/_validate.py" = [
+    "SLF001", # accesses r._source, r._kind
+]
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

symref-0.1.0/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-0.1.0/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-0.1.0/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-0.1.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/tests/conftest.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+import pytest
+
+from symref import clear_refs
+
+
+@pytest.fixture(autouse=True)
+def _clear_registry() -> None:
+    clear_refs()

symref-0.1.0/tests/test_ref.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from symref import ref
+
+
+def test_ref_is_str() -> None:
+    r = ref("os.path")
+    assert isinstance(r, str)
+
+
+def test_ref_equals_plain_str() -> None:
+    r = ref("os.path")
+    assert r == "os.path"
+    assert "os.path" == r  # noqa: SIM300 -- intentionally testing str.__eq__(ref)
+
+
+def test_ref_registered_in_registry() -> None:
+    r = ref("os.path")
+    assert r in ref._registry
+    assert len(ref._registry) == 1
+
+
+def test_kind_defaults_to_none() -> None:
+    r = ref("os.path")
+    assert r._kind is None
+
+
+def test_kind_stored_when_provided() -> None:
+    r = ref("os.path", kind="test_kind")
+    assert r._kind == "test_kind"
+
+
+def test_source_captured() -> None:
+    r = ref("os.path")
+    assert r._source[0].endswith("test_ref.py")
+    assert isinstance(r._source[1], int)
+    assert r._source[1] > 0
+
+
+def test_usable_as_dict_key() -> None:
+    r = ref("os.path")
+    d: dict[str, str] = {r: "value"}
+    assert d["os.path"] == "value"
+    assert d[r] == "value"
+
+
+def test_repr_matches_str() -> None:
+    r = ref("os.path")
+    assert repr(r) == repr("os.path")
+
+
+def test_hash_matches_str() -> None:
+    r = ref("os.path")
+    assert hash(r) == hash("os.path")
+
+
+def test_registry_clearing() -> None:
+    ref("os.path")
+    assert len(ref._registry) == 1
+    ref._registry.clear()
+    assert len(ref._registry) == 0

symref-0.1.0/tests/test_validate.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import pytest
+
+from symref import SymrefError, ref, validate_refs
+from symref._validate import _resolve
+
+# --- _resolve tests ---
+
+
+def test_resolve_valid_module() -> None:
+    assert _resolve("os") is True
+
+
+def test_resolve_valid_nested_module() -> None:
+    assert _resolve("os.path") is True
+
+
+def test_resolve_valid_attribute() -> None:
+    assert _resolve("os.path.join") is True
+
+
+def test_resolve_valid_package_module() -> None:
+    assert _resolve("symref._ref") is True
+
+
+def test_resolve_valid_package_attribute() -> None:
+    assert _resolve("symref._ref.ref") is True
+
+
+def test_resolve_valid_package_class_var() -> None:
+    assert _resolve("symref.SymrefError") is True
+
+
+def test_resolve_nonexistent_module() -> None:
+    assert _resolve("nonexistent.module.that.does.not.exist") is False
+
+
+def test_resolve_nonexistent_attribute() -> None:
+    assert _resolve("os.path.nonexistent_attr_xyz") is False
+
+
+def test_resolve_relative_path() -> None:
+    assert _resolve(".foo.bar") is False
+
+
+def test_resolve_double_relative_path() -> None:
+    assert _resolve("..foo") is False
+
+
+def test_resolve_whitespace_path() -> None:
+    assert _resolve("  ") is False
+
+
+def test_resolve_empty_string() -> None:
+    assert _resolve("") is False
+
+
+# --- validate_refs tests ---
+
+
+def test_validate_no_refs_passes() -> None:
+    validate_refs()
+
+
+def test_validate_valid_ref_passes() -> None:
+    ref("os.path")
+    validate_refs()
+
+
+def test_validate_broken_ref_raises() -> None:
+    ref("nonexistent.module.xyz")
+    with pytest.raises(SymrefError):
+        validate_refs()
+
+
+def test_validate_multiple_broken_refs() -> None:
+    ref("nonexistent.module.one")
+    ref("nonexistent.module.two")
+    with pytest.raises(SymrefError, match="2 broken reference"):
+        validate_refs()
+
+
+def test_validate_kind_filtering_passes() -> None:
+    ref("os.path", kind="good")
+    ref("nonexistent.module.xyz", kind="bad")
+    validate_refs(kind="good")
+
+
+def test_validate_kind_filtering_raises() -> None:
+    ref("os.path", kind="good")
+    ref("nonexistent.module.xyz", kind="bad")
+    with pytest.raises(SymrefError):
+        validate_refs(kind="bad")
+
+
+def test_error_message_includes_source() -> None:
+    ref("nonexistent.module.xyz")
+    with pytest.raises(SymrefError, match=r"test_validate\.py"):
+        validate_refs()
+
+
+def test_validate_valid_attribute_ref() -> None:
+    ref("symref.SymrefError")
+    validate_refs()
+
+
+def test_validate_invalid_attribute_ref() -> None:
+    ref("symref.NonexistentThing")
+    with pytest.raises(SymrefError):
+        validate_refs()
+
+
+def test_validate_mixed_valid_and_broken_refs() -> None:
+    ref("os.path")
+    ref("nonexistent.module.xyz")
+    ref("os")
+    with pytest.raises(SymrefError) as exc_info:
+        validate_refs()
+    assert len(exc_info.value.broken) == 1
+    assert str(exc_info.value.broken[0]) == "nonexistent.module.xyz"
+
+
+def test_symref_error_broken_attribute() -> None:
+    r = ref("nonexistent.module.xyz")
+    with pytest.raises(SymrefError) as exc_info:
+        validate_refs()
+    assert exc_info.value.broken == [r]
+    assert exc_info.value.broken[0] is r