io-adapters 0.1.0__tar.gz

io_adapters-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.3
+Name: io-adapters
+Version: 0.1.0
+Summary: Add your description here
+Author: ed cuss
+Author-email: ed cuss <edcussmusic@gmail.com>
+Requires-Dist: attrs>=25.4.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# io-adapters
+### API Reference
+
+[io-adapters API docs](https://second-ed.github.io/io-adapters/)
+
+Testing use cases that involve I/O is inherently difficult because they depend on external state and side effects. However, combining Dependency Injection (DI) with the Repository pattern significantly reduces this complexity.
+
+By substituting real I/O implementations with fakes that simulate their behaviour, stateful interactions can be captured entirely in memory. This allows changes to the external world to be accumulated deterministically and the final state to be asserted directly, without relying on real filesystems, networks, or services.
+
+The result is faster, more reliable tests that focus on behaviour rather than infrastructure.
+
+However, creating these fakes can be time consuming and result in a maintenance burden that may not outweigh the benefit. 
+
+This is where `io-adapters` can help. Simply register each I/O function with one of the register decorators and the functionality will be added to the `RealAdapter` object, on top of that a stub will be added to the `FakeAdapter` object too so you can pass in either to your usecase and the functionality will work.
+
+# Repo map
+```
+├── .github
+│   └── workflows
+│       ├── ci_tests.yaml
+│       └── publish.yaml
+├── .pytest_cache
+│   └── README.md
+├── docs
+│   └── source
+│       └── conf.py
+├── src
+│   └── io_adapters
+│       ├── __init__.py
+│       ├── _adapters.py
+│       ├── _container.py
+│       ├── _io_funcs.py
+│       └── _registries.py
+├── tests
+│   ├── __init__.py
+│   ├── test_adapters.py
+│   ├── test_adapters_apis.py
+│   └── test_container.py
+├── .pre-commit-config.yaml
+├── README.md
+├── pyproject.toml
+├── ruff.toml
+└── uv.lock
+::
+```

io_adapters-0.1.0/README.md

@@ -0,0 +1,45 @@
+# io-adapters
+### API Reference
+
+[io-adapters API docs](https://second-ed.github.io/io-adapters/)
+
+Testing use cases that involve I/O is inherently difficult because they depend on external state and side effects. However, combining Dependency Injection (DI) with the Repository pattern significantly reduces this complexity.
+
+By substituting real I/O implementations with fakes that simulate their behaviour, stateful interactions can be captured entirely in memory. This allows changes to the external world to be accumulated deterministically and the final state to be asserted directly, without relying on real filesystems, networks, or services.
+
+The result is faster, more reliable tests that focus on behaviour rather than infrastructure.
+
+However, creating these fakes can be time consuming and result in a maintenance burden that may not outweigh the benefit. 
+
+This is where `io-adapters` can help. Simply register each I/O function with one of the register decorators and the functionality will be added to the `RealAdapter` object, on top of that a stub will be added to the `FakeAdapter` object too so you can pass in either to your usecase and the functionality will work.
+
+# Repo map
+```
+├── .github
+│   └── workflows
+│       ├── ci_tests.yaml
+│       └── publish.yaml
+├── .pytest_cache
+│   └── README.md
+├── docs
+│   └── source
+│       └── conf.py
+├── src
+│   └── io_adapters
+│       ├── __init__.py
+│       ├── _adapters.py
+│       ├── _container.py
+│       ├── _io_funcs.py
+│       └── _registries.py
+├── tests
+│   ├── __init__.py
+│   ├── test_adapters.py
+│   ├── test_adapters_apis.py
+│   └── test_container.py
+├── .pre-commit-config.yaml
+├── README.md
+├── pyproject.toml
+├── ruff.toml
+└── uv.lock
+::
+```

io_adapters-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "io-adapters"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "ed cuss", email = "edcussmusic@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "attrs>=25.4.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.13,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.1.0",
+    "pre-commit>=4.5.0",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "repo-mapper-rs>=0.3.0",
+    "ruff>=0.14.9",
+    "sphinx>=9.0.4",
+]

io_adapters-0.1.0/src/io_adapters/__init__.py

@@ -0,0 +1,22 @@
+from io_adapters._adapters import FakeAdapter, IoAdapter, RealAdapter
+from io_adapters._container import (
+    Container,
+    add_domain,
+    get_fake_adapter,
+    get_real_adapter,
+    register_domain_read_fn,
+    register_domain_write_fn,
+)
+from io_adapters._io_funcs import read_json, write_json  # noqa: F401
+
+__all__ = [
+    "Container",
+    "FakeAdapter",
+    "IoAdapter",
+    "RealAdapter",
+    "add_domain",
+    "get_fake_adapter",
+    "get_real_adapter",
+    "register_domain_read_fn",
+    "register_domain_write_fn",
+]

io_adapters-0.1.0/src/io_adapters/_adapters.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import datetime
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Hashable
+from pathlib import Path
+from types import MappingProxyType
+from uuid import uuid4
+
+import attrs
+from attrs.validators import deep_mapping, instance_of, is_callable
+
+from io_adapters._registries import READ_FNS, WRITE_FNS, Data, standardise_key
+
+logger = logging.getLogger(__name__)
+
+
+@attrs.define
+class IoAdapter(ABC):
+    read_fns: MappingProxyType = attrs.field(
+        default=READ_FNS,
+        validator=[
+            deep_mapping(
+                key_validator=instance_of(Hashable),
+                value_validator=is_callable(),
+                mapping_validator=instance_of(MappingProxyType),
+            )
+        ],
+        converter=MappingProxyType,
+    )
+    write_fns: MappingProxyType = attrs.field(
+        default=WRITE_FNS,
+        validator=[
+            deep_mapping(
+                key_validator=instance_of(Hashable),
+                value_validator=is_callable(),
+                mapping_validator=instance_of(MappingProxyType),
+            )
+        ],
+        converter=MappingProxyType,
+    )
+
+    def read(self, path: str | Path, file_type: str, **kwargs: dict) -> Data:
+        """Read `path` using the registered function for `file_type`.
+
+        Raises:
+            NotImplementedError: If the given `file_type` does not have a registered function.
+
+        Usage
+        -----
+
+        Here the ``read_json`` function is registered with the ``register_read_fn`` decorator.
+
+        Then when the ``adapter`` object calls ``read`` with the ``"json"`` ``file_type`` it will use the registered function.
+
+        The ``key`` used to register the function doesn't have to be a string, as long as it's ``Hashable`` it can be used.
+
+        .. code-block:: python
+
+            from io_adapters import RealAdapter, register_read_fn
+
+            @register_read_fn("json")
+            def read_json(path: str | Path, **kwargs: dict) -> dict:
+                return json.loads(Path(path).read_text(), **kwargs)
+
+            adapter = RealAdapter()
+            data = adapter.read("some/path/to/file.json", "json")
+
+        """
+        logger.info(f"{path = } {file_type = } {kwargs = }")
+        file_type = standardise_key(file_type)
+
+        if file_type not in self.read_fns:
+            msg = f"`read` is not implemented for {file_type}"
+            logger.error(msg)
+            raise NotImplementedError(msg)
+        return self.read_fns[file_type](path, **kwargs)
+
+    def write(self, data: Data, path: str | Path, file_type: str, **kwargs: dict) -> None:
+        """Write `data` to `path` using the registered function for `file_type`.
+
+        Raises:
+            NotImplementedError: If the given `file_type` does not have a registered function.
+
+        Usage
+        -----
+
+        Here the ``write_json`` function is registered with the ``register_write_fn`` decorator.
+
+        Then when the ``adapter`` object calls ``write`` with the ``WriteFormat.JSON`` ``file_type`` it will use the registered function.
+
+        .. code-block:: python
+
+            from enum import Enum
+            from io_adapters import RealAdapter, register_write_fn
+
+            class WriteFormat(Enum):
+                JSON = "json"
+
+            @register_write_fn(WriteFormat.JSON)
+            def write_json(data: dict, path: str | Path, **kwargs: dict) -> None:
+                path = Path(path)
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(json.dumps(data, **kwargs))
+
+            adapter = RealAdapter()
+            adapter.write({"a": 1}, "some/path/to/file.json", WriteFormat.JSON)
+
+            fake_adapter = FakeAdapter()
+            fake_adapter.write({"a": 1}, "some/path/to/file.json", WriteFormat.JSON)
+
+
+        The interfaces between the ``FakeAdapter`` and the ``RealAdapter`` means that the two can be passed in interchangeably, making testing much easier
+
+        .. code-block:: python
+
+            def some_usecase(adapter: IoAdapter, path: str) -> None:
+                # Some business logic
+
+                adapter.write({"a": 1}, , WriteFormat.JSON)
+
+            # in production inject the real adapter
+            some_usecase(RealAdapter(), "some/path/to/file.json")
+
+            # in testing inject the fake and assert that the fakes end state is as expected
+            fake = FakeAdapter()
+            some_usecase(fake, "some/path/to/file.json")
+            assert fake.files["some/path/to/file.json"] == {"a": 1}
+
+        """
+        logger.info(f"{path = } {file_type = } {kwargs = }")
+        file_type = standardise_key(file_type)
+
+        if file_type not in self.write_fns:
+            msg = f"`write` is not implemented for {file_type}"
+            logger.error(msg)
+            raise NotImplementedError(msg)
+        return self.write_fns[file_type](data, path, **kwargs)
+
+    @abstractmethod
+    def get_guid(self) -> str: ...
+
+    @abstractmethod
+    def get_datetime(self) -> datetime.datetime: ...
+
+
+@attrs.define
+class RealAdapter(IoAdapter):
+    def get_guid(self) -> str:
+        return str(uuid4())
+
+    def get_datetime(self) -> datetime.datetime:
+        return datetime.datetime.now(datetime.UTC)
+
+
+@attrs.define
+class FakeAdapter(IoAdapter):
+    files: dict[str, Data] = attrs.field(factory=dict, validator=instance_of(dict))
+
+    def __attrs_post_init__(self) -> None:
+        self.read_fns = MappingProxyType(dict.fromkeys(self.read_fns.keys(), self._read_fn))
+        self.write_fns = MappingProxyType(dict.fromkeys(self.write_fns.keys(), self._write_fn))
+
+    def _read_fn(self, path: str) -> Data:
+        try:
+            return self.files[path]
+        except KeyError as e:
+            raise FileNotFoundError(f"{path = } {self.files = }") from e
+
+    def _write_fn(self, data: Data, path: str) -> None:
+        self.files[str(path)] = data
+
+    def get_guid(self) -> str:
+        return "abc-123"
+
+    def get_datetime(self) -> datetime.datetime:
+        return datetime.datetime(2025, 1, 1, 12, tzinfo=datetime.UTC)

io_adapters-0.1.0/src/io_adapters/_container.py

@@ -0,0 +1,357 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Hashable, Iterable
+from enum import Enum, auto
+
+import attrs
+from attrs.validators import deep_iterable, instance_of
+
+from io_adapters import FakeAdapter, RealAdapter
+from io_adapters._registries import standardise_key
+
+logger = logging.getLogger(__name__)
+
+
+class _FnType(Enum):
+    READ = auto()
+    WRITE = auto()
+
+
+@attrs.define
+class Container:
+    """Registry and factory for domain-scoped I/O adapters.
+
+    The ``Container`` provides a central registry for I/O functions that are
+    grouped by domain. Each domain has isolated access to a specific set of
+    read and write functions, allowing different parts of an application to
+    share common I/O implementations without violating domain boundaries.
+
+    Domain isolation
+    ----------------
+    In some cases, different domains need isolated access to the same underlying
+    functionality.
+
+    For example:
+
+    - The ``orders`` domain may:
+        - read ``json`` files
+        - write ``parquet`` files
+    - The ``reporting`` domain may:
+        - read from a database
+        - write ``parquet`` files
+
+    While both domains can reuse a shared ``write_parquet`` implementation,
+    they must not have access to each other's read capabilities. The
+    ``Container`` enforces this isolation by maintaining separate registries
+    per domain.
+
+    Design
+    ------
+    The ``Container``:
+
+    - Maintains a mapping of domains to read/write function registries
+    - Provides decorator-style registration APIs for read and write functions
+    - Acts as a factory for creating domain-specific adapters
+
+    Two adapter types are supported:
+
+    - ``RealAdapter`` for production usage
+    - ``FakeAdapter`` for testing, allowing stateful simulation of I/O
+
+    Testing
+    -------
+    Using a ``FakeAdapter`` makes it possible to simulate external I/O while
+    keeping all state in memory. This allows tests to:
+
+    - Accumulate state across reads and writes
+    - Assert against the final external state
+    - Avoid filesystem or network dependencies entirely
+
+    This results in tests that are faster, deterministic, and easier to reason
+    about.
+
+    Usage overview
+    --------------
+
+    #. Define a ``Container`` with one or more domains
+    #. Register read/write functions per domain
+    #. Request either a real or fake adapter for a given domain
+    #. Inject the adapter into application code
+
+    The ``Container`` itself is intentionally simple and does not perform any
+     I/O; it only wires together domain-specific capabilities.
+
+    Tip
+    ---
+
+    Usage of a custom ``Container`` is only recommended if you have a complex set of domains and need multiple ``Container``s initialised at the same time.
+
+    If you have a simple set of domains you can use the convenience functions with the same names as the ``Container`` methods which will be added to the default ``Container`` which is an instance you don't need to initialise yourself.
+
+    """
+
+    domains: Iterable = attrs.field(validator=deep_iterable(member_validator=instance_of(Hashable)))
+    domain_fns: dict[Hashable, dict[Hashable, Callable]] = attrs.field(init=False)
+
+    def __attrs_post_init__(self) -> None:
+        self.domain_fns = {domain: {_FnType.READ: {}, _FnType.WRITE: {}} for domain in self.domains}
+
+    def add_domain(self, domain: Hashable) -> None:
+        """Add a domain to a ``Container``
+
+        .. code-block:: python
+
+            from io_adapters import Container
+
+            container = Container()
+            container.add_domain("orders")
+
+        The ``orders`` domain is now added to the ``Container`` and can have IO functions registered to it.
+
+        Relying on deliberate registering of a domain avoids situations where a typo could register a function to a non-existent domain: e.g. ``'ordesr'`` instead of the intended ``'orders'``.
+
+        Domains can also be passed into the Container on initialisation.
+
+        .. code-block:: python
+
+            container = Container(domains=["orders"])
+
+        """
+        self.domain_fns[domain] = {_FnType.READ: {}, _FnType.WRITE: {}}
+
+    def register_domain_read_fn(self, domain: Hashable, key: Hashable) -> Callable:
+        """Register a read function to a domain in a ``Container``.
+
+        Decorators can be stacked to register the same function to multiple domains.
+
+        .. code-block:: python
+
+            from io_adapters import Container
+
+            container = Container(domains=["orders", "payment"])
+
+            @container.register_domain_read_fn("orders", "str")
+            def read_str(path: str | Path, **kwargs: dict) -> str:
+                ...
+
+
+            @container.register_domain_read_fn("orders", "json")
+            @container.register_domain_read_fn("payment", "json")
+            def read_json(path: str | Path, **kwargs: dict) -> dict:
+                ...
+        """
+        domain = standardise_key(domain)
+        key = standardise_key(key)
+
+        def wrapper(func: Callable) -> Callable:
+            logger.info(f"registering read fn {key = } {func = }")
+            self.domain_fns[domain][_FnType.READ][key] = func
+            return func
+
+        return wrapper
+
+    def register_domain_write_fn(self, domain: Hashable, key: Hashable) -> Callable:
+        """Register a write function to a domain in a ``Container``.
+
+        Decorators can be stacked to register the same function to multiple domains.
+
+        .. code-block:: python
+
+            from io_adapters import Container
+
+            container = Container(domains=["orders"])
+
+            @container.register_domain_write_fn("orders", "str")
+            def write_str(data: dict, path: str | Path, **kwargs: dict) -> None:
+                ...
+
+            container.add_domain("payment")
+
+            @container.register_domain_write_fn("orders", "json")
+            @container.register_domain_write_fn("payment", "json")
+            def write_json(data: dict, path: str | Path, **kwargs: dict) -> None:
+                ...
+        """
+        domain = standardise_key(domain)
+        key = standardise_key(key)
+
+        def wrapper(func: Callable) -> Callable:
+            logger.info(f"registering read fn {key = } {func = }")
+            self.domain_fns[domain][_FnType.WRITE][key] = func
+            return func
+
+        return wrapper
+
+    def get_real_adapter(self, domain: Hashable) -> RealAdapter:
+        """Get a ``RealAdapter`` for the given domain from a ``Container``.
+
+        The returned adapter will have all of the functions registered to that domain.
+
+        .. code-block:: python
+
+            from io_adapters import RealAdapter, Container
+
+            container = Container(domains=["orders"])
+            orders_adapter: RealAdapter = container.get_real_adapter("orders")
+
+        The ``RealAdapter`` that is assigned to the ``orders_adapter`` variable will have all of the registered read and write I/O functions.
+
+        """
+        return RealAdapter(
+            read_fns=self.domain_fns[domain][_FnType.READ],
+            write_fns=self.domain_fns[domain][_FnType.WRITE],
+        )
+
+    def get_fake_adapter(self, domain: Hashable, files: dict | None = None) -> RealAdapter:
+        """Get a ``FakeAdapter`` for the given domain.
+
+        The returned adapter will have all of the functions registered to that domain.
+
+        .. code-block:: python
+
+            from io_adapters import FakeAdapter, Container
+
+            container = Container(domains=["orders"])
+            orders_adapter: FakeAdapter = container.get_fake_adapter("orders")
+
+        The ``FakeAdapter`` that is assigned to the ``orders_adapter`` variable will have fake representations for all of the registered read and write I/O functions.
+
+        This can optionally be given a dictionary of files to setup the initial state for testing. An example of how this could be used is below:
+
+        .. code-block:: python
+
+            from io_adapters import FakeAdapter, Container
+
+            starting_files = {"path/to/data.json": {"a": 0, "b": 1}}
+
+            container = Container(domains=["orders"])
+            orders_adapter: FakeAdapter = container.get_fake_adapter("orders", starting_files)
+
+            some_orders_usecase(adapter=orders_adapter, data_path="path/to/data.json")
+
+            assert orders_adapter.files["path/to/modified_data.json"] == {"a": 1, "b": 2}
+
+        """
+        return FakeAdapter(
+            read_fns=self.domain_fns[domain][_FnType.READ],
+            write_fns=self.domain_fns[domain][_FnType.WRITE],
+            files=files or {},
+        )
+
+
+DEFAULT_CONTAINER = Container(domains=[])
+
+
+def add_domain(domain: Hashable) -> None:
+    """Add a domain to the default ``Container``
+
+    .. code-block:: python
+
+        from io_adapters import add_domain
+
+        add_domain("orders")
+
+    The ``orders`` domain is now added to the default ``Container`` and can have IO functions registered to it.
+
+    Relying on deliberate registering of a domain avoids situations where a typo could register a function to a non-existent domain: e.g. ``'ordesr'`` instead of the intended ``'orders'``.
+    """
+    return DEFAULT_CONTAINER.add_domain(domain)
+
+
+def register_domain_read_fn(domain: Hashable, key: Hashable) -> Callable:
+    """Register a read function to a domain in the default ``Container``.
+
+    Decorators can be stacked to register the same function to multiple domains.
+
+    .. code-block:: python
+
+        from io_adapters import add_domain, register_domain_read_fn
+
+        add_domain("orders")
+
+        @register_domain_read_fn("orders", "str")
+        def read_str(path: str | Path, **kwargs: dict) -> str:
+            ...
+
+        add_domain("payment")
+
+        @register_domain_read_fn("orders", "json")
+        @register_domain_read_fn("payment", "json")
+        def read_json(path: str | Path, **kwargs: dict) -> dict:
+            ...
+    """
+    return DEFAULT_CONTAINER.register_domain_read_fn(domain, key)
+
+
+def register_domain_write_fn(domain: Hashable, key: Hashable) -> Callable:
+    """Register a write function to a domain in the default ``Container``.
+
+    Decorators can be stacked to register the same function to multiple domains.
+
+    .. code-block:: python
+
+        from io_adapters import add_domain, register_domain_write_fn
+
+        add_domain("orders")
+
+        @register_domain_write_fn("orders", "str")
+        def write_str(data: dict, path: str | Path, **kwargs: dict) -> None:
+            ...
+
+        add_domain("payment")
+
+        @register_domain_write_fn("orders", "json")
+        @register_domain_write_fn("payment", "json")
+        def write_json(data: dict, path: str | Path, **kwargs: dict) -> None:
+            ...
+    """
+    return DEFAULT_CONTAINER.register_domain_write_fn(domain, key)
+
+
+def get_real_adapter(domain: Hashable) -> RealAdapter:
+    """Get a ``RealAdapter`` for the given domain.
+
+    The returned adapter will have all of the functions registered to that domain.
+
+    .. code-block:: python
+
+        from io_adapters import RealAdapter, get_real_adapter
+
+        orders_adapter: RealAdapter = get_real_adapter("orders")
+
+    The ``RealAdapter`` that is assigned to the ``orders_adapter`` variable will have all of the registered read and write I/O functions.
+
+    """
+    return DEFAULT_CONTAINER.get_real_adapter(domain)
+
+
+def get_fake_adapter(domain: Hashable, files: dict | None = None) -> FakeAdapter:
+    """Get a ``FakeAdapter`` for the given domain.
+
+    The returned adapter will have all of the functions registered to that domain.
+
+    .. code-block:: python
+
+        from io_adapters import FakeAdapter, get_fake_adapter
+
+        orders_adapter: FakeAdapter = get_fake_adapter("orders")
+
+    The ``FakeAdapter`` that is assigned to the ``orders_adapter`` variable will have fake representations for all of the registered read and write I/O functions.
+
+    This can optionally be given a dictionary of files to setup the initial state for testing. An example of how this could be used is below:
+
+    .. code-block:: python
+
+        from io_adapters import FakeAdapter, get_fake_adapter
+
+        starting_files = {"path/to/data.json": {"a": 0, "b": 1}}
+
+        orders_adapter: FakeAdapter = get_fake_adapter("orders", starting_files)
+
+        some_orders_usecase(adapter=orders_adapter, data_path="path/to/data.json")
+
+        assert orders_adapter.files["path/to/modified_data.json"] == {"a": 1, "b": 2}
+
+    """
+    return DEFAULT_CONTAINER.get_fake_adapter(domain, files)

io_adapters-0.1.0/src/io_adapters/_io_funcs.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from io_adapters._registries import register_read_fn, register_write_fn
+
+
+@register_read_fn("json")
+def read_json(path: str | Path, **kwargs: dict) -> dict:
+    return json.loads(Path(path).read_text(), **kwargs)
+
+
+@register_write_fn("json")
+def write_json(data: dict, path: str | Path, **kwargs: dict) -> None:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, **kwargs))

io_adapters-0.1.0/src/io_adapters/_registries.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Hashable
+from pathlib import Path
+from typing import Concatenate, ParamSpec, TypeAlias
+
+logger = logging.getLogger(__name__)
+
+Data: TypeAlias = "Data"
+P = ParamSpec("P")
+
+ReadFn = Callable[Concatenate[str | Path, P], Data]
+WriteFn = Callable[Concatenate[Data, str | Path, P], None]
+
+
+READ_FNS: dict[str, ReadFn] = {}
+WRITE_FNS: dict[str, WriteFn] = {}
+
+
+def register_read_fn(key: Hashable) -> Callable:
+    key = standardise_key(key)
+
+    def wrapper(func: Callable) -> Callable:
+        logger.info(f"registering read fn {key = } {func = }")
+        READ_FNS[key] = func
+        return func
+
+    return wrapper
+
+
+def register_write_fn(key: Hashable) -> Callable:
+    key = standardise_key(key)
+
+    def wrapper(func: Callable) -> Callable:
+        logger.info(f"registering write fn {key = } {func = }")
+        WRITE_FNS[key] = func
+        return func
+
+    return wrapper
+
+
+def standardise_key(key: Hashable) -> Hashable:
+    return key.strip().lower() if isinstance(key, str) else key