feat: Defining the unmarshal API.

pyproject.toml

@@ -116,7 +116,7 @@ extend-select = [
 
 [tool.ruff.lint.per-file-ignores]
 # Ignore `E402` (import violations) in all `__init__.py` files
-"__init__.py" = ["E402"]
+"__init__.py" = ["E402", "F403"]
 
 [tool.ruff.lint.isort]
 extra-standard-library = ["typing_extensions", "graphlib"]

src/typelib/unmarshal/__init__.py

@@ -0,0 +1,2 @@
+from typelib.unmarshal.factory import *
+from typelib.unmarshal.routines import *

src/typelib/unmarshal/factory.py

@@ -7,11 +7,31 @@
 
 T = tp.TypeVar("T")
 
+__all__ = (
+    "unmarshal",
+    "unmarshaller",
+    "DelayedUnmarshaller",
+    "NoOpUnmarshaller",
+)
+
+
+def unmarshal(typ: type[T] | refs.ForwardRef | str, value: tp.Any) -> T:
+    """Unmarshal :py:param:`value` into :py:param:`typ`."""
+    routine = unmarshaller(typ)
+    unmarshalled = routine(value)
+    return unmarshalled
+
 
 @compat.cache
 def unmarshaller(
     typ: type[T] | refs.ForwardRef | str,
 ) -> routines.AbstractUnmarshaller[T]:
+    """Get an un-marshaller routine for a given type.
+
+    Args:
+        typ: The type annotation to generate an unmarshaller for.
+             May be a type, a :py:class:`typing.ForwardRef`, or string reference.
+    """
     nodes = graph.static_order(typ)
     context: dict[type, routines.AbstractUnmarshaller] = {}
     if not nodes: