valbridge 0.1.1__tar.gz

valbridge-0.1.1/.gitignore

@@ -0,0 +1,25 @@
+# Temporary compliance test harness files
+xschema-harness-*.py
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# Pytest cache
+.pytest_cache/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# uv
+.venv/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/

valbridge-0.1.1/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [0.1.1](https://github.com/vectorfy-co/valbridge/compare/py-client-v0.1.0...py-client-v0.1.1) (2026-04-07)
+
+### Features
+
+* import valbridge monorepo ([2a7ed24](https://github.com/vectorfy-co/valbridge/commit/2a7ed246c8cb87206d13860fe01155de24de1ae8))

valbridge-0.1.1/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: valbridge
+Version: 0.1.1
+Summary: Runtime client for valbridge-generated validators with type-safe schema lookup
+Project-URL: Homepage, https://github.com/vectorfy-co/valbridge
+Project-URL: Documentation, https://github.com/vectorfy-co/valbridge
+Project-URL: Repository, https://github.com/vectorfy-co/valbridge
+Project-URL: Issues, https://github.com/vectorfy-co/valbridge/issues
+Project-URL: Changelog, https://github.com/vectorfy-co/valbridge/blob/main/CHANGELOG.md
+Author: vectorfyco
+Maintainer: vectorfyco
+License: MIT
+Keywords: code-generation,json-schema,pydantic,runtime-client,schema,type-safety,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# valbridge
+
+Runtime client for valbridge-generated validators with type-safe schema lookup.
+
+## Installation
+
+```bash
+pip install valbridge
+```
+
+## Usage
+
+```python
+from valbridge import create_valbridge
+from _valbridge import schemas
+
+valbridge = create_valbridge(schemas)
+
+# Full key lookup
+user_validator = valbridge("user:Profile")
+
+# Validate data
+user_validator.validate_python({"name": "Alice", "email": "alice@example.com"})
+```

valbridge-0.1.1/README.md

@@ -0,0 +1,24 @@
+# valbridge
+
+Runtime client for valbridge-generated validators with type-safe schema lookup.
+
+## Installation
+
+```bash
+pip install valbridge
+```
+
+## Usage
+
+```python
+from valbridge import create_valbridge
+from _valbridge import schemas
+
+valbridge = create_valbridge(schemas)
+
+# Full key lookup
+user_validator = valbridge("user:Profile")
+
+# Validate data
+user_validator.validate_python({"name": "Alice", "email": "alice@example.com"})
+```

valbridge-0.1.1/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "valbridge"
+version = "0.1.1"
+description = "Runtime client for valbridge-generated validators with type-safe schema lookup"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "vectorfyco" }]
+maintainers = [{ name = "vectorfyco" }]
+keywords = [
+    "json-schema",
+    "validation",
+    "pydantic",
+    "code-generation",
+    "runtime-client",
+    "schema",
+    "type-safety",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/vectorfy-co/valbridge"
+Documentation = "https://github.com/vectorfy-co/valbridge"
+Repository = "https://github.com/vectorfy-co/valbridge"
+Issues = "https://github.com/vectorfy-co/valbridge/issues"
+Changelog = "https://github.com/vectorfy-co/valbridge/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/valbridge"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

valbridge-0.1.1/src/valbridge/__init__.py

@@ -0,0 +1,135 @@
+"""
+Runtime client for valbridge-generated validators.
+
+This module provides runtime schema lookup for validators generated by valbridge.
+The client wraps a dictionary of validators and provides a callable interface.
+
+Design decisions:
+
+1. NAMESPACE:ID FORMAT - Keys use "namespace:id" format (e.g., "user:Profile")
+   matching the Go CLI output. This provides:
+   - Namespacing to avoid collisions when multiple config files define schemas
+   - Clear provenance: namespace often maps to the config filename
+   - Consistency across TypeScript and Python (same format in both)
+
+2. NO DEFAULT NAMESPACE - Unlike the TypeScript client, Python doesn't support
+   declaration merging for type safety on shorthand lookups. Without type
+   benefits, shorthand adds API complexity without value. Full keys are clearer.
+
+3. DICTIONARY-BASED STORAGE - Schemas stored in a dict keyed by "namespace:id".
+   Generated code creates this dict statically. Runtime lookup is O(1).
+
+4. CALLABLE INTERFACE - Client is callable: valbridge("namespace:id")
+   This mimics function call semantics while allowing stateful configuration.
+
+5. USER-FRIENDLY ERRORS - ValbridgeError includes "Run `valbridge generate`" hint
+   because the most common error is forgetting to regenerate after schema changes.
+
+Usage:
+    from _valbridge import valbridge  # Generated by valbridge CLI
+
+    User = valbridge("user:User")  # Returns Pydantic model class
+    user = User.model_validate({"name": "Alice"})
+"""
+
+from typing import Any, Dict, Generic, Protocol, TypeVar
+
+__all__ = ["ValbridgeClient", "ValbridgeError", "create_valbridge"]
+
+T = TypeVar("T")
+T_co = TypeVar("T_co", covariant=True)
+
+
+class _SchemaLookup(Protocol[T_co]):
+    def __call__(self, key: str) -> T_co: ...
+
+
+class ValbridgeError(Exception):
+    """
+    Raised when a schema cannot be found.
+
+    Includes a hint to run `valbridge generate` since the most common cause
+    is forgetting to regenerate after adding/renaming schemas.
+    """
+
+    pass
+
+
+class ValbridgeClient(Generic[T]):
+    """
+    Type-safe client for looking up schemas by namespace:id.
+
+    Generic over T to allow typing the return value. In generated code,
+    T is typically a Union of all generated model types, providing IDE
+    autocompletion for the returned validator.
+
+    The class wraps a dictionary but provides a callable interface for
+    ergonomic usage: valbridge("namespace:id") instead of valbridge.get("namespace:id")
+    """
+
+    def __init__(self, schemas: Dict[str, T]) -> None:
+        """
+        Initialize the valbridge client.
+
+        Args:
+            schemas: Dictionary of schemas keyed by "namespace:id".
+                     Keys use colon separator matching CLI output format.
+        """
+        self._schemas = schemas
+
+    def __call__(self, key: str) -> T:
+        """
+        Look up a schema by key.
+
+        Args:
+            key: Schema key in "namespace:id" format (e.g., "user:Profile")
+                 The namespace is typically the config filename without extension.
+                 The id is the schema's declared identifier.
+
+        Returns:
+            The schema validator (e.g., Pydantic model class)
+
+        Raises:
+            ValbridgeError: If schema not found. Error message includes hint
+                          to run `valbridge generate` since stale code is common.
+        """
+        if key not in self._schemas:
+            msg = f"Unknown schema: {key}. Run `valbridge generate`."
+            raise ValbridgeError(msg)
+
+        return self._schemas[key]
+
+
+def create_valbridge(schemas: Dict[str, T]) -> _SchemaLookup[T]:
+    """
+    Create an valbridge client for looking up schemas by namespace:id.
+
+    This is the public factory function used by generated code. It returns
+    a callable that provides runtime schema lookup.
+
+    Why a factory function instead of direct ValbridgeClient instantiation?
+    - Cleaner generated code: `valbridge = create_valbridge(schemas)`
+    - Hides implementation detail (class vs function doesn't matter to user)
+    - Allows future changes to internal representation without breaking API
+
+    Args:
+        schemas: Dictionary of schemas keyed by "namespace:id".
+                 Generated code provides this dict with all validators.
+
+    Returns:
+        A ValbridgeClient instance. It's callable and takes a "namespace:id"
+        key, returning the validator. Raises ValbridgeError if the key is not found.
+
+    Example:
+        >>> from valbridge import create_valbridge
+        >>> schemas = {"user:Profile": ProfileModel, "config:TSConfig": TSConfigModel}
+        >>> valbridge = create_valbridge(schemas)
+        >>>
+        >>> # Look up by full namespace:id key
+        >>> Profile = valbridge("user:Profile")
+        >>>
+        >>> # Use the validator
+        >>> user = Profile.model_validate({"name": "Alice"})
+    """
+    client = ValbridgeClient(schemas)
+    return client

valbridge-0.1.1/tests/test_client.py

@@ -0,0 +1,101 @@
+"""Tests for valbridge."""
+
+import pytest
+from valbridge import ValbridgeError, create_valbridge
+
+
+class MockValidator:
+    """Mock validator for testing."""
+
+    def __init__(self, name: str):
+        self.name = name
+
+    def model_validate(self, data):
+        return data
+
+
+def test_full_key_lookup():
+    """Test looking up schemas with full namespace:id keys."""
+    schemas = {
+        "user:Profile": MockValidator("Profile"),
+        "another:TSConfig": MockValidator("TSConfig"),
+    }
+    valbridge = create_valbridge(schemas)
+
+    # Should find by full key
+    assert valbridge("user:Profile").name == "Profile"
+    assert valbridge("another:TSConfig").name == "TSConfig"
+
+
+def test_schema_not_found():
+    """Test error when schema doesn't exist."""
+    schemas = {
+        "user:Profile": MockValidator("Profile"),
+    }
+    valbridge = create_valbridge(schemas)
+
+    # Non-existent key
+    with pytest.raises(ValbridgeError) as exc_info:
+        valbridge("user:NonExistent")
+    assert "Unknown schema: user:NonExistent" in str(exc_info.value)
+
+
+def test_empty_schemas():
+    """Test client with empty schemas dict."""
+    valbridge = create_valbridge({})
+
+    with pytest.raises(ValbridgeError):
+        valbridge("anything")
+
+
+def test_type_inference():
+    """Test that client preserves type information."""
+    schemas = {
+        "user:Profile": MockValidator("Profile"),
+    }
+    valbridge = create_valbridge(schemas)
+
+    # Should return the exact validator instance
+    validator = valbridge("user:Profile")
+    assert isinstance(validator, MockValidator)
+    assert validator.name == "Profile"
+
+
+def test_nonexistent_namespace():
+    """Test error when namespace doesn't exist."""
+    schemas = {
+        "user:Profile": MockValidator("Profile"),
+        "another:Config": MockValidator("Config"),
+    }
+    valbridge = create_valbridge(schemas)
+
+    # Non-existent namespace should fail
+    with pytest.raises(ValbridgeError) as exc_info:
+        valbridge("nonexistent:Schema")
+    assert "Unknown schema: nonexistent:Schema" in str(exc_info.value)
+
+
+def test_client_is_callable():
+    """Test that returned client is callable."""
+    schemas = {"user:Profile": MockValidator("Profile")}
+    valbridge = create_valbridge(schemas)
+
+    # Should be callable
+    assert callable(valbridge)
+
+    # Should work like a function
+    result = valbridge("user:Profile")
+    assert result.name == "Profile"
+
+
+def test_multiple_clients():
+    """Test creating multiple independent clients."""
+    schemas1 = {"user:Profile": MockValidator("Profile1")}
+    schemas2 = {"user:Profile": MockValidator("Profile2")}
+
+    valbridge1 = create_valbridge(schemas1)
+    valbridge2 = create_valbridge(schemas2)
+
+    # Should be independent
+    assert valbridge1("user:Profile").name == "Profile1"
+    assert valbridge2("user:Profile").name == "Profile2"