into-obj 0.1.0__tar.gz

into_obj-0.1.0/PKG-INFO

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: into-obj
+Version: 0.1.0
+Summary: Rust-style `Into` & `TryInto` conversions for Python
+Keywords: rust,rs,convertions,cast,type,into
+Author: Sequence
+Author-email: Sequence <3863887959@qq.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: rezult>=0.2.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# into-obj
+
+Rust-style `Into` & `TryInto` conversions for Python, with explicit,
+type-checked converter registries.
+
+```python
+from into_obj import Reg, into, register_into
+
+register_into(Celsius, Fahrenheit, lambda c: Fahrenheit(c.degrees * 9 / 5 + 32))
+
+into(Reg(Celsius(100)), Fahrenheit)  # 212.0
+```
+
+## Features
+
+- `into(from_, Target)` for infallible conversions and `try_into(from_, Target)`
+  for fallible ones that return `Result`.
+- Two conversion mechanisms:
+  - **Magic methods** — a type converts itself via `__into__` / `__try_into__`.
+  - **Converter registries** — converters keyed by `(source type, target type)`,
+    usable without touching the source type.
+- `Reg` wrapper makes registry-based conversions visible in the type signature,
+  so type checkers reject unregistered, non-converting sources.
+- MRO-aware dispatch: a converter registered for a base class also serves its
+  subclasses, and `object` works as a wildcard target.
+- Errors are explicit: `into` raises, `try_into` returns `Err`.
+
+## Requirements
+
+- Python 3.12+ (the package uses PEP 695 generics)
+- `rezult >= 0.2.0`
+
+## Installation
+
+```bash
+uv add into-obj
+# or
+pip install into-obj
+```
+
+## Quick start
+
+```python
+from rezult import Err, Ok
+
+from into_obj import Reg, into, register_into, register_try_into, try_into
+
+
+class Version:
+    def __init__(self, number: int) -> None:
+        self.number = number
+
+    def __into__(self, into: type[str]) -> str:
+        return f"v{self.number}"
+
+
+class Celsius:
+    def __init__(self, degrees: float) -> None:
+        self.degrees = degrees
+
+
+class Fahrenheit(float):
+    pass
+
+
+register_into(
+    Celsius,
+    Fahrenheit,
+    lambda celsius: Fahrenheit(celsius.degrees * 9 / 5 + 32),
+)
+
+register_try_into(
+    str,
+    int,
+    lambda text: Ok(int(text)) if text.isdigit() else Err(ValueError(text)),
+)
+
+assert into(Version(3), str) == "v3"
+assert into(Reg(Celsius(100)), Fahrenheit) == 212.0
+assert try_into(Reg("42"), int) == Ok(42)
+assert try_into(Reg("abc"), int).is_err()
+```
+
+## How it works
+
+Every call resolves a conversion by walking a fixed order. A magic method that
+raises `NotImplementedError` counts as missing, and resolution continues.
+
+| Call                  | Resolution order                                                                          |
+| --------------------- | ----------------------------------------------------------------------------------------- |
+| `into(x, T)`          | `x.__into__(T)`                                                                            |
+| `into(Reg(x), T)`     | `x.__into__(T)` → `INTO_CONVERTERS`                                                        |
+| `try_into(x, T)`      | `x.__try_into__(T)`                                                                        |
+| `try_into(Reg(x), T)` | `x.__try_into__(T)` → `TRY_INTO_CONVERTERS` → `x.__into__(T)` → `INTO_CONVERTERS`          |
+
+### Magic methods
+
+Implement `__into__` for infallible conversions, or `__try_into__` when the
+conversion can fail.
+
+```python
+from rezult import Err, Ok, Result
+
+
+class Port:
+    def __init__(self, text: str) -> None:
+        self.text = text
+
+    def __try_into__(self, into: type[int]) -> Result[int, str]:
+        if into is not int:
+            return Err("only int is supported")
+        if not self.text.isdigit():
+            return Err(f"invalid port: {self.text}")
+        return Ok(int(self.text))
+
+
+assert try_into(Port("8080"), int) == Ok(8080)
+assert try_into(Port("http"), int) == Err("invalid port: http")
+```
+
+`Into[T]` and `TryInto[T, E]` are protocols, so implementing the method is
+enough — no inheritance required.
+
+### Registered converters
+
+Register a converter when you cannot (or do not want to) change the source
+type. Wrap the source value in `Reg` to select the registry path.
+
+```python
+class Meters:
+    def __init__(self, value: float) -> None:
+        self.value = value
+
+
+class Kilometers:
+    def __init__(self, value: float) -> None:
+        self.value = value
+
+
+register_into(Meters, Kilometers, lambda meters: Kilometers(meters.value / 1000))
+
+assert into(Reg(Meters(1500)), Kilometers).value == 1.5
+```
+
+A fallible converter returns a `Result`. Returning a plain value is treated as
+`Ok(value)`, and raising an `Exception` becomes `Err(exception)`.
+
+```python
+register_try_into(
+    str,
+    int,
+    lambda text: Ok(int(text)) if text.isdigit() else Err(ValueError(text)),
+)
+
+assert try_into(Reg("7"), int) == Ok(7)
+assert isinstance(try_into(Reg("seven"), int), Err)
+```
+
+Converters can be removed again, which is useful in tests:
+
+```python
+from into_obj import unregister_into, unregister_try_into
+
+unregister_into(Meters, Kilometers)
+unregister_try_into(str, int)
+```
+
+### MRO-aware lookup
+
+Registry keys are `(source type, target type)`. Lookup walks the source MRO
+first, then the target MRO, so the nearest source class wins.
+
+```python
+class SubMeters(Meters):
+    pass
+
+
+register_into(Meters, Kilometers, lambda meters: Kilometers(meters.value / 1000))
+register_into(SubMeters, Kilometers, lambda meters: Kilometers(-1))
+
+into(Reg(Meters(2000)), Kilometers).value      # 2.0  (base converter)
+into(Reg(SubMeters(2000)), Kilometers).value   # -1   (nearest source wins)
+```
+
+Registering `object` as the target makes a converter apply to every target
+type:
+
+```python
+register_into(Meters, object, lambda meters: meters.value)
+
+into(Reg(Meters(3)), int)  # 3
+```
+
+## API reference
+
+### Functions
+
+| Function                                | Description                                                        |
+| --------------------------------------- | ------------------------------------------------------------------ |
+| `into(from_, target)`                   | Convert `from_` into `target`, raising on failure.                 |
+| `try_into(from_, target)`               | Convert `from_` into `target`, returning `Result[T, E]`.           |
+| `register_into(source, target, conv)`   | Register an infallible converter for `(source, target)`.           |
+| `register_try_into(source, target, conv)` | Register a fallible converter for `(source, target)`.            |
+| `unregister_into(source, target)`       | Remove the infallible converter for the pair, if any.              |
+| `unregister_try_into(source, target)`   | Remove the fallible converter for the pair, if any.                |
+
+`register_*` validates its arguments and raises `TypeError` if `source` or
+`target` is not a class, or if the converter is not callable.
+
+### Types
+
+| Name                     | Description                                                            |
+| ------------------------ | ---------------------------------------------------------------------- |
+| `Reg[T]`                 | Wrapper marking a value as converted by a registered converter.        |
+| `Into[T]`                | Protocol for types implementing `__into__`.                            |
+| `TryInto[T, E]`          | Protocol for types implementing `__try_into__`.                        |
+| `IntoSource[S, T]`       | `Into[T] \| Reg[S]` — accepted by `into`.                              |
+| `TryIntoSource[S, T, E]` | `TryInto[T, E] \| Reg[S]` — accepted by `try_into`.                    |
+| `Converter[T, U]`        | `Callable[[T], U]`.                                                    |
+| `TryConverter[T, U, E]`  | `Callable[[T], Result[U, E]]`.                                         |
+| `INTO_CONVERTERS`        | Registry used by `into`.                                               |
+| `TRY_INTO_CONVERTERS`    | Registry used by `try_into`.                                           |
+
+### Type signatures
+
+```python
+def into[S, T](from_: IntoSource[S, T], into: type[T]) -> T: ...
+def try_into[S, T, E](from_: TryIntoSource[S, T, E], into: type[T]) -> Result[T, E]: ...
+```
+
+`S` is the wrapped source type and `T` the target type, which is why `Reg` is
+parameterized separately: `into(Reg(Celsius(100)), Fahrenheit)` infers
+`S = Celsius` and `T = Fahrenheit`. Passing a registered source without `Reg`
+is rejected by type checkers.
+
+### Error handling
+
+- `into` raises `TypeError` when neither a magic method nor a converter is
+  available, and re-raises `NotImplementedError` from `__into__` in that case.
+- `try_into` never raises for conversion failures: exceptions from the
+  registry converter or the fallback path are returned as `Err`.
+
+## Notes
+
+- Registries are process-global dictionaries. Register converters once at
+  import time or application startup.
+- Registering the same `(source, target)` pair twice replaces the converter.
+- `Reg` is transparent at runtime: it is unwrapped before resolution, so a
+  magic method still takes precedence over a registered converter.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+Tests live in `tests/test_into.py` and isolate the global registries with an
+autouse fixture.
+
+## License
+MIT

into_obj-0.1.0/README.md

@@ -0,0 +1,262 @@
+# into-obj
+
+Rust-style `Into` & `TryInto` conversions for Python, with explicit,
+type-checked converter registries.
+
+```python
+from into_obj import Reg, into, register_into
+
+register_into(Celsius, Fahrenheit, lambda c: Fahrenheit(c.degrees * 9 / 5 + 32))
+
+into(Reg(Celsius(100)), Fahrenheit)  # 212.0
+```
+
+## Features
+
+- `into(from_, Target)` for infallible conversions and `try_into(from_, Target)`
+  for fallible ones that return `Result`.
+- Two conversion mechanisms:
+  - **Magic methods** — a type converts itself via `__into__` / `__try_into__`.
+  - **Converter registries** — converters keyed by `(source type, target type)`,
+    usable without touching the source type.
+- `Reg` wrapper makes registry-based conversions visible in the type signature,
+  so type checkers reject unregistered, non-converting sources.
+- MRO-aware dispatch: a converter registered for a base class also serves its
+  subclasses, and `object` works as a wildcard target.
+- Errors are explicit: `into` raises, `try_into` returns `Err`.
+
+## Requirements
+
+- Python 3.12+ (the package uses PEP 695 generics)
+- `rezult >= 0.2.0`
+
+## Installation
+
+```bash
+uv add into-obj
+# or
+pip install into-obj
+```
+
+## Quick start
+
+```python
+from rezult import Err, Ok
+
+from into_obj import Reg, into, register_into, register_try_into, try_into
+
+
+class Version:
+    def __init__(self, number: int) -> None:
+        self.number = number
+
+    def __into__(self, into: type[str]) -> str:
+        return f"v{self.number}"
+
+
+class Celsius:
+    def __init__(self, degrees: float) -> None:
+        self.degrees = degrees
+
+
+class Fahrenheit(float):
+    pass
+
+
+register_into(
+    Celsius,
+    Fahrenheit,
+    lambda celsius: Fahrenheit(celsius.degrees * 9 / 5 + 32),
+)
+
+register_try_into(
+    str,
+    int,
+    lambda text: Ok(int(text)) if text.isdigit() else Err(ValueError(text)),
+)
+
+assert into(Version(3), str) == "v3"
+assert into(Reg(Celsius(100)), Fahrenheit) == 212.0
+assert try_into(Reg("42"), int) == Ok(42)
+assert try_into(Reg("abc"), int).is_err()
+```
+
+## How it works
+
+Every call resolves a conversion by walking a fixed order. A magic method that
+raises `NotImplementedError` counts as missing, and resolution continues.
+
+| Call                  | Resolution order                                                                          |
+| --------------------- | ----------------------------------------------------------------------------------------- |
+| `into(x, T)`          | `x.__into__(T)`                                                                            |
+| `into(Reg(x), T)`     | `x.__into__(T)` → `INTO_CONVERTERS`                                                        |
+| `try_into(x, T)`      | `x.__try_into__(T)`                                                                        |
+| `try_into(Reg(x), T)` | `x.__try_into__(T)` → `TRY_INTO_CONVERTERS` → `x.__into__(T)` → `INTO_CONVERTERS`          |
+
+### Magic methods
+
+Implement `__into__` for infallible conversions, or `__try_into__` when the
+conversion can fail.
+
+```python
+from rezult import Err, Ok, Result
+
+
+class Port:
+    def __init__(self, text: str) -> None:
+        self.text = text
+
+    def __try_into__(self, into: type[int]) -> Result[int, str]:
+        if into is not int:
+            return Err("only int is supported")
+        if not self.text.isdigit():
+            return Err(f"invalid port: {self.text}")
+        return Ok(int(self.text))
+
+
+assert try_into(Port("8080"), int) == Ok(8080)
+assert try_into(Port("http"), int) == Err("invalid port: http")
+```
+
+`Into[T]` and `TryInto[T, E]` are protocols, so implementing the method is
+enough — no inheritance required.
+
+### Registered converters
+
+Register a converter when you cannot (or do not want to) change the source
+type. Wrap the source value in `Reg` to select the registry path.
+
+```python
+class Meters:
+    def __init__(self, value: float) -> None:
+        self.value = value
+
+
+class Kilometers:
+    def __init__(self, value: float) -> None:
+        self.value = value
+
+
+register_into(Meters, Kilometers, lambda meters: Kilometers(meters.value / 1000))
+
+assert into(Reg(Meters(1500)), Kilometers).value == 1.5
+```
+
+A fallible converter returns a `Result`. Returning a plain value is treated as
+`Ok(value)`, and raising an `Exception` becomes `Err(exception)`.
+
+```python
+register_try_into(
+    str,
+    int,
+    lambda text: Ok(int(text)) if text.isdigit() else Err(ValueError(text)),
+)
+
+assert try_into(Reg("7"), int) == Ok(7)
+assert isinstance(try_into(Reg("seven"), int), Err)
+```
+
+Converters can be removed again, which is useful in tests:
+
+```python
+from into_obj import unregister_into, unregister_try_into
+
+unregister_into(Meters, Kilometers)
+unregister_try_into(str, int)
+```
+
+### MRO-aware lookup
+
+Registry keys are `(source type, target type)`. Lookup walks the source MRO
+first, then the target MRO, so the nearest source class wins.
+
+```python
+class SubMeters(Meters):
+    pass
+
+
+register_into(Meters, Kilometers, lambda meters: Kilometers(meters.value / 1000))
+register_into(SubMeters, Kilometers, lambda meters: Kilometers(-1))
+
+into(Reg(Meters(2000)), Kilometers).value      # 2.0  (base converter)
+into(Reg(SubMeters(2000)), Kilometers).value   # -1   (nearest source wins)
+```
+
+Registering `object` as the target makes a converter apply to every target
+type:
+
+```python
+register_into(Meters, object, lambda meters: meters.value)
+
+into(Reg(Meters(3)), int)  # 3
+```
+
+## API reference
+
+### Functions
+
+| Function                                | Description                                                        |
+| --------------------------------------- | ------------------------------------------------------------------ |
+| `into(from_, target)`                   | Convert `from_` into `target`, raising on failure.                 |
+| `try_into(from_, target)`               | Convert `from_` into `target`, returning `Result[T, E]`.           |
+| `register_into(source, target, conv)`   | Register an infallible converter for `(source, target)`.           |
+| `register_try_into(source, target, conv)` | Register a fallible converter for `(source, target)`.            |
+| `unregister_into(source, target)`       | Remove the infallible converter for the pair, if any.              |
+| `unregister_try_into(source, target)`   | Remove the fallible converter for the pair, if any.                |
+
+`register_*` validates its arguments and raises `TypeError` if `source` or
+`target` is not a class, or if the converter is not callable.
+
+### Types
+
+| Name                     | Description                                                            |
+| ------------------------ | ---------------------------------------------------------------------- |
+| `Reg[T]`                 | Wrapper marking a value as converted by a registered converter.        |
+| `Into[T]`                | Protocol for types implementing `__into__`.                            |
+| `TryInto[T, E]`          | Protocol for types implementing `__try_into__`.                        |
+| `IntoSource[S, T]`       | `Into[T] \| Reg[S]` — accepted by `into`.                              |
+| `TryIntoSource[S, T, E]` | `TryInto[T, E] \| Reg[S]` — accepted by `try_into`.                    |
+| `Converter[T, U]`        | `Callable[[T], U]`.                                                    |
+| `TryConverter[T, U, E]`  | `Callable[[T], Result[U, E]]`.                                         |
+| `INTO_CONVERTERS`        | Registry used by `into`.                                               |
+| `TRY_INTO_CONVERTERS`    | Registry used by `try_into`.                                           |
+
+### Type signatures
+
+```python
+def into[S, T](from_: IntoSource[S, T], into: type[T]) -> T: ...
+def try_into[S, T, E](from_: TryIntoSource[S, T, E], into: type[T]) -> Result[T, E]: ...
+```
+
+`S` is the wrapped source type and `T` the target type, which is why `Reg` is
+parameterized separately: `into(Reg(Celsius(100)), Fahrenheit)` infers
+`S = Celsius` and `T = Fahrenheit`. Passing a registered source without `Reg`
+is rejected by type checkers.
+
+### Error handling
+
+- `into` raises `TypeError` when neither a magic method nor a converter is
+  available, and re-raises `NotImplementedError` from `__into__` in that case.
+- `try_into` never raises for conversion failures: exceptions from the
+  registry converter or the fallback path are returned as `Err`.
+
+## Notes
+
+- Registries are process-global dictionaries. Register converters once at
+  import time or application startup.
+- Registering the same `(source, target)` pair twice replaces the converter.
+- `Reg` is transparent at runtime: it is unwrapped before resolution, so a
+  magic method still takes precedence over a registered converter.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+Tests live in `tests/test_into.py` and isolate the global registries with an
+autouse fixture.
+
+## License
+MIT

into_obj-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "into-obj"
+version = "0.1.0"
+description = "Rust-style `Into` & `TryInto` conversions for Python"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = ["rezult>=0.2.0"]
+keywords = [
+    "rust",
+    "rs",
+    "convertions",
+    "cast",
+    "type",
+    "into",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Sequence"
+email = "3863887959@qq.com"
+
+[[tool.uv.index]]
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+default = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.2.0"]

into_obj-0.1.0/pyproject.toml.orig

@@ -0,0 +1,43 @@
+[project]
+name = "into-obj"
+version = "0.1.0"
+description = "Rust-style `Into` & `TryInto` conversions for Python"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Sequence", email = "3863887959@qq.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "rezult>=0.2.0",
+]
+
+keywords = ["rust", "rs", "convertions", "cast", "type", "into"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+    "Typing :: Typed"
+]
+
+[[tool.uv.index]]
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+default = true
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

into_obj-0.1.0/src/into_obj/__init__.py

@@ -0,0 +1,52 @@
+"""Rust-style conversions for Python, built on ``rezult``.
+
+The public API is re-exported from `into_obj.into`:
+
+- `into` / `try_into`: convert a value into a target type.
+- `Into` / `TryInto`: protocols implemented by self-converting types.
+- `Reg`: wrapper marking values converted by a registered converter.
+- `register_into` / `register_try_into`: register converters.
+- `unregister_into` / `unregister_try_into`: remove converters.
+- `INTO_CONVERTERS` / `TRY_INTO_CONVERTERS`: the converter registries.
+"""
+
+from .into import (
+    INTO_CONVERTERS,
+    TRY_INTO_CONVERTERS,
+    Converter,
+    Into,
+    IntoSource,
+    Reg,
+    TryConverter,
+    TryInto,
+    TryIntoSource,
+    into,
+    register_into,
+    register_try_into,
+    try_into,
+    unregister_into,
+    unregister_try_into,
+)
+
+__all__ = [
+    "INTO_CONVERTERS",
+    "TRY_INTO_CONVERTERS",
+    "Converter",
+    "Into",
+    "IntoSource",
+    "Reg",
+    "TryConverter",
+    "TryInto",
+    "TryIntoSource",
+    "into",
+    "register_into",
+    "register_try_into",
+    "try_into",
+    "unregister_into",
+    "unregister_try_into",
+]
+
+
+def main() -> None:
+    """Run the ``into-obj`` console script."""
+    print("Hello from into-obj!")

into_obj-0.1.0/src/into_obj/into.py

@@ -0,0 +1,381 @@
+# pyright: reportUnnecessaryIsInstance = false
+"""Conversion helpers built on magic methods and registered converters.
+
+Two mechanisms are provided:
+
+1. Magic methods -- a type implements ``__into__`` (see `Into`) or
+   ``__try_into__`` (see `TryInto`) and converts itself.
+2. Converter registries -- infallible converters live in `INTO_CONVERTERS`
+   and fallible ones in `TRY_INTO_CONVERTERS`, keyed by
+   ``(source type, target type)``. Values converted this way must be wrapped
+   in `Reg`, which keeps the intent visible in the type signature.
+
+Resolution order:
+
+- `into` prefers ``__into__`` and falls back to `INTO_CONVERTERS`.
+- `try_into` prefers ``__try_into__``, then `TRY_INTO_CONVERTERS`, then the
+  same path as `into`.
+
+A magic method that raises ``NotImplementedError`` is treated as missing, so
+resolution continues in the registry.
+
+Example:
+    >>> register_into(int, str, lambda value: f"#{value}")
+    >>> into(Reg(42), str)
+    '#42'
+"""
+
+from collections.abc import Callable
+from typing import Any, Protocol, cast
+
+from rezult import Err, Ok, Result
+
+
+class Into[T](Protocol):
+    """Protocol for values that convert themselves into another type.
+
+    Implementing ``__into__`` lets a type be passed to `into` directly,
+    without a `Reg` wrapper and without registering a converter.
+    """
+
+    def __into__(self, into: type[T]) -> T:
+        """Convert this value into the given target type.
+
+        Args:
+            into: Target type of the conversion.
+
+        Returns:
+            The converted value.
+
+        Raises:
+            NotImplementedError: If this type cannot convert into the given
+                target type.
+        """
+        raise NotImplementedError
+
+
+class TryInto[T, E](Protocol):
+    """Protocol for values that fallibly convert themselves.
+
+    Implementing ``__try_into__`` lets a type be passed to `try_into`
+    directly, without a `Reg` wrapper and without registering a converter.
+    """
+
+    def __try_into__(self, into: type[T]) -> Result[T, E]:
+        """Try to convert this value into the given target type.
+
+        Args:
+            into: Target type of the conversion.
+
+        Returns:
+            ``Ok`` with the converted value, or ``Err`` describing why the
+            conversion failed.
+
+        Raises:
+            NotImplementedError: If this type cannot convert into the given
+                target type.
+        """
+        raise NotImplementedError
+
+
+class Reg[T]:
+    """Explicit marker for values converted by a registered converter.
+
+    `into` and `try_into` only accept registered-converter sources when they
+    are wrapped in ``Reg``, which makes the conversion path visible in the
+    type signature (``Into[T] | Reg[S]`` and ``TryInto[T, E] | Reg[S]``).
+
+    The wrapper is transparent at runtime: the value is unwrapped and
+    resolved normally, so an implemented magic method still wins over a
+    registered converter.
+
+    Attributes:
+        value: The wrapped source value.
+
+    Example:
+        >>> into(Reg(Meters(1500)), Kilometers)
+    """
+
+    __slots__ = ("value",)
+    __match_args__ = ("value",)
+
+    def __init__(self, value: T) -> None:
+        """Initialize the wrapper.
+
+        Args:
+            value: Source value to convert through a registered converter.
+        """
+        self.value: T = value
+
+    def __repr__(self) -> str:
+        """Return a debug representation such as ``Reg(42)``."""
+        return f"Reg({self.value!r})"
+
+
+#: Source accepted by `into`: a self-converting value or a `Reg` wrapper.
+type IntoSource[S, T] = Into[T] | Reg[S]
+
+#: Source accepted by `try_into`: a fallibly self-converting value or `Reg`.
+type TryIntoSource[S, T, E] = TryInto[T, E] | Reg[S]
+
+#: Infallible converter from ``T`` to ``U``.
+type Converter[T, U] = Callable[[T], U]
+
+#: Fallible converter from ``T`` to ``U``, reporting failures as ``Result``.
+type TryConverter[T, U, E] = Callable[[T], Result[U, E]]
+
+#: Registry used by `into`; keys are ``(source class, target class)``.
+INTO_CONVERTERS: dict[tuple[type, type], Converter[Any, Any]] = {}
+
+#: Registry used by `try_into`; keys are ``(source class, target class)``.
+TRY_INTO_CONVERTERS: dict[tuple[type, type], TryConverter[Any, Any, Any]] = {}
+
+
+def register_into[T, U](
+    source: type[T],
+    target: type[U],
+    converter: Converter[T, U],
+) -> None:
+    """Register an infallible converter for `into`.
+
+    Keys are matched through both MROs: the nearest source class wins, then
+    the nearest target class. Registering ``object`` as the target therefore
+    applies the converter to every target type. Registering an existing pair
+    replaces the previous converter.
+
+    Args:
+        source: Type of the value being converted.
+        target: Type produced by ``converter``.
+        converter: Callable receiving the source value and returning the
+            converted value.
+
+    Raises:
+        TypeError: If ``source`` or ``target`` is not a class, or if
+            ``converter`` is not callable.
+
+    Example:
+        >>> register_into(Meters, Kilometers, lambda m: Kilometers(m.value / 1000))
+        >>> into(Reg(Meters(1500)), Kilometers).value
+        1.5
+    """
+    _validate(source, target, converter)
+    INTO_CONVERTERS[source, target] = converter
+
+
+def register_try_into[T, U, E](
+    source: type[T],
+    target: type[U],
+    converter: TryConverter[T, U, E],
+) -> None:
+    """Register a fallible converter for `try_into`.
+
+    The converter should return a ``Result``; a plain value is wrapped in
+    ``Ok`` and a raised ``Exception`` becomes ``Err``. Matching follows the
+    same MRO rules as `register_into`.
+
+    Args:
+        source: Type of the value being converted.
+        target: Type produced by ``converter``.
+        converter: Callable receiving the source value and returning a
+            ``Result`` (or a plain value, which is wrapped in ``Ok``).
+
+    Raises:
+        TypeError: If ``source`` or ``target`` is not a class, or if
+            ``converter`` is not callable.
+
+    Example:
+        >>> register_try_into(
+        ...     str,
+        ...     int,
+        ...     lambda text: Ok(int(text)) if text.isdigit() else Err(ValueError(text)),
+        ... )
+        >>> try_into(Reg("42"), int)
+        Ok(42)
+    """
+    _validate(source, target, converter)
+    TRY_INTO_CONVERTERS[source, target] = converter
+
+
+def unregister_into(source: type, target: type) -> None:
+    """Remove the converter registered for ``source`` -> ``target``.
+
+    Does nothing when the pair is not registered.
+
+    Args:
+        source: Source type of the registration to remove.
+        target: Target type of the registration to remove.
+    """
+    INTO_CONVERTERS.pop((source, target), None)
+
+
+def unregister_try_into(source: type, target: type) -> None:
+    """Remove the try converter registered for ``source`` -> ``target``.
+
+    Does nothing when the pair is not registered.
+
+    Args:
+        source: Source type of the registration to remove.
+        target: Target type of the registration to remove.
+    """
+    TRY_INTO_CONVERTERS.pop((source, target), None)
+
+
+def into[S, T](from_: IntoSource[S, T], into: type[T]) -> T:
+    """Convert ``from_`` into the given target type.
+
+    Args:
+        from_: Value implementing `Into`, or a `Reg` wrapper around a value
+            whose converter is registered in `INTO_CONVERTERS`.
+        into: Target type of the conversion.
+
+    Returns:
+        The converted value.
+
+    Raises:
+        NotImplementedError: If ``__into__`` raises it and no converter is
+            registered for the pair.
+        TypeError: If the value has no ``__into__`` and no converter is
+            registered for the pair.
+
+    Example:
+        >>> into(Version(3), str)
+        'v3'
+        >>> into(Reg(Meters(1500)), Kilometers).value
+        1.5
+    """
+    return cast(T, _convert(_unwrap(from_), into))
+
+
+def try_into[S, T, E](from_: TryIntoSource[S, T, E], into: type[T]) -> Result[T, E]:
+    """Try to convert ``from_`` into the given target type.
+
+    Resolution order is ``__try_into__``, `TRY_INTO_CONVERTERS`, then the
+    infallible path used by `into` (``__into__`` and `INTO_CONVERTERS`).
+    Any exception raised along the way becomes ``Err``.
+
+    Args:
+        from_: Value implementing `TryInto`, or a `Reg` wrapper around a value
+            whose converter is registered in `TRY_INTO_CONVERTERS` or
+            `INTO_CONVERTERS`.
+        into: Target type of the conversion.
+
+    Returns:
+        ``Ok`` with the converted value, or ``Err`` describing why the
+        conversion failed.
+
+    Example:
+        >>> try_into(Reg("42"), int)
+        Ok(42)
+    """
+    value = _unwrap(from_)
+
+    magic = getattr(value, "__try_into__", None)
+    if magic is not None:
+        try:
+            return cast(Result[T, E], magic(into))
+        except NotImplementedError:
+            pass
+
+    converter = _lookup(TRY_INTO_CONVERTERS, value, into)
+    if converter is not None:
+        try:
+            result = converter(value)
+        except Exception as error:
+            return Err(cast(E, error))
+        if isinstance(result, Result):
+            return cast(Result[T, E], result)
+        return Ok(cast(T, result))
+
+    try:
+        return Ok(_convert(value, into))
+    except Exception as error:
+        return Err(cast(E, error))
+
+
+def _unwrap(from_: object) -> object:
+    """Return the value inside a `Reg` wrapper, or ``from_`` unchanged.
+
+    Args:
+        from_: Possibly wrapped source value.
+
+    Returns:
+        The unwrapped source value.
+    """
+    return from_.value if isinstance(from_, Reg) else from_  # type: ignore
+
+
+def _convert(from_: object, target: type) -> Any:
+    """Resolve and run an infallible conversion.
+
+    Args:
+        from_: Unwrapped source value.
+        target: Target type of the conversion.
+
+    Returns:
+        The converted value.
+
+    Raises:
+        NotImplementedError: If ``__into__`` raises it and no converter is
+            registered for the pair.
+        TypeError: If the value has no ``__into__`` and no converter is
+            registered for the pair.
+    """
+    magic = getattr(from_, "__into__", None)
+    if magic is not None:
+        try:
+            return magic(target)
+        except NotImplementedError:
+            converter = _lookup(INTO_CONVERTERS, from_, target)
+            if converter is None:
+                raise
+            return converter(from_)
+
+    converter = _lookup(INTO_CONVERTERS, from_, target)
+    if converter is None:
+        raise TypeError(
+            f"no conversion from {type(from_).__qualname__!r} "
+            f"to {getattr(target, '__qualname__', target)!r}"
+        )
+    return converter(from_)
+
+
+def _lookup[T](
+    registry: dict[tuple[type, type], T],
+    value: object,
+    target: type,
+) -> T | None:
+    """Find a converter by walking the source and target MROs.
+
+    Args:
+        registry: Registry to search.
+        value: Source value whose type starts the source lookup.
+        target: Target type that starts the target lookup.
+
+    Returns:
+        The first matching converter, or ``None`` when nothing matches.
+    """
+    target_mro = getattr(target, "__mro__", (target,))
+    for source_cls in type(value).__mro__:
+        for target_cls in target_mro:
+            converter = registry.get((source_cls, target_cls))
+            if converter is not None:
+                return converter
+    return None
+
+
+def _validate(source: type, target: type, converter: Callable[..., Any]) -> None:
+    """Validate the arguments of a registration helper.
+
+    Args:
+        source: Type of the value being converted.
+        target: Type produced by ``converter``.
+        converter: Callable performing the conversion.
+
+    Raises:
+        TypeError: If ``source`` or ``target`` is not a class, or if
+            ``converter`` is not callable.
+    """
+    if not isinstance(source, type) or not isinstance(target, type):
+        raise TypeError("source and target must be classes")
+    if not callable(converter):
+        raise TypeError("converter must be callable")