avoine 0.1.0a1__tar.gz

avoine-0.1.0a1/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: avoine
+Version: 0.1.0a1
+Summary: Tiny serialisation and deserialisation library
+Author: classabbyamp
+Author-email: classabbyamp <dev@placeviolette.net>
+License-Expression: CC0-1.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: File Formats
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Project-URL: homepage, https://codeberg.org/classabbyamp/avoine
+Project-URL: issues, https://codeberg.org/classabbyamp/avoine/issues
+Project-URL: source, https://codeberg.org/classabbyamp/avoine
+Description-Content-Type: text/markdown
+
+# avoine
+
+A tiny serialisation and deserialisation library.
+
+`avoine` does not implement any serialisation or deserialisation itself. Instead,
+it relies on the common Python pattern of `load` and `dump` functions (for file-like
+objects) and `loads` and `dumps` functions (for string-like objects).
+
+To configure serialisation and deserialisation, use the `avoine` class:
+
+```py
+import json
+import tomllib
+
+from avoine import avoine
+
+# define a format for deserialisation (load -> from file, loads -> from string/bytes)
+# and serialisation (dump -> from file, dumps -> from string/bytes) and set it as default
+avoine.register("json", default=True, load=json.load, loads=json.loads, dump=json.dump, dumps=json.dumps)
+
+# not all methods are required
+avoine.register("toml", load=tomllib.load)
+
+# register can be used again to update a format definition
+avoine.register("toml", loads=tomllib.loads)
+
+# the default format is what is used when the format is left unspecified
+# it can be set or unset on its own
+avoine.default = "toml"
+avoine.default = None
+
+# and retrieved with
+print(avoine.default)
+
+# you can unregister a format too
+avoine.unregister("toml", default="json")
+
+# the list of currently-registered formats can be retrieved with
+avoine.formats()
+
+# or for a specific method with
+avoine.formats("load")
+
+# all configuration can be reset with
+avoine.clear()
+```
+
+Then, in your code, you can define dataclasses and add the `AvoineBase` mixin class,
+which will allow you to serialise/deserialise them from any registered format anywhere:
+
+```py
+from dataclasses import dataclass
+from avoine import AvoineBase
+
+@dataclass
+class MyStruct(AvoineBase):
+    foo: str
+    bar: MyInnerStruct
+
+@dataclass
+class MyInnerStruct(AvoineBase):
+    baz: list[str]
+    opt: str | None = None
+
+with open("mystruct.json") as f:
+    data = MyStruct.load(f)
+    # kwargs for the underlying loader/dumper are passed down to them
+    data.dumps(indent=2)
+
+with open("mystruct.toml") as f:
+    print(MyStruct.load(f, format="toml"))
+```
+
+Custom formats can be created by writing functions with the following signatures:
+
+```py
+def load(fp: SupportsRead[AnyStr], **kwargs) -> dict[str, Any]:
+    ...
+
+def loads(s: AnyStr, **kwargs) -> dict[str, Any]:
+    ...
+
+def dump(obj: Any, fp: SupportsWrite[AnyStr], **kwargs) -> None:
+    ...
+
+def dumps(obj: Any, **kwargs) -> AnyStr:
+    ...
+```
+
+Notes:
+
+- `AnyStr` can be `str`, `bytes`, or both
+- `kwargs` are optional
+
+If a set of loading/dumping functions for a format do not match these signatures,
+wrapper functions can be written to transform them to a compatible signature.
+
+## License
+
+avoine is in the public domain.
+
+To the extent possible under law, classabbyamp has waived all copyright and related or neighboring rights to this work.
+
+http://creativecommons.org/publicdomain/zero/1.0/

avoine-0.1.0a1/README.md

@@ -0,0 +1,104 @@
+# avoine
+
+A tiny serialisation and deserialisation library.
+
+`avoine` does not implement any serialisation or deserialisation itself. Instead,
+it relies on the common Python pattern of `load` and `dump` functions (for file-like
+objects) and `loads` and `dumps` functions (for string-like objects).
+
+To configure serialisation and deserialisation, use the `avoine` class:
+
+```py
+import json
+import tomllib
+
+from avoine import avoine
+
+# define a format for deserialisation (load -> from file, loads -> from string/bytes)
+# and serialisation (dump -> from file, dumps -> from string/bytes) and set it as default
+avoine.register("json", default=True, load=json.load, loads=json.loads, dump=json.dump, dumps=json.dumps)
+
+# not all methods are required
+avoine.register("toml", load=tomllib.load)
+
+# register can be used again to update a format definition
+avoine.register("toml", loads=tomllib.loads)
+
+# the default format is what is used when the format is left unspecified
+# it can be set or unset on its own
+avoine.default = "toml"
+avoine.default = None
+
+# and retrieved with
+print(avoine.default)
+
+# you can unregister a format too
+avoine.unregister("toml", default="json")
+
+# the list of currently-registered formats can be retrieved with
+avoine.formats()
+
+# or for a specific method with
+avoine.formats("load")
+
+# all configuration can be reset with
+avoine.clear()
+```
+
+Then, in your code, you can define dataclasses and add the `AvoineBase` mixin class,
+which will allow you to serialise/deserialise them from any registered format anywhere:
+
+```py
+from dataclasses import dataclass
+from avoine import AvoineBase
+
+@dataclass
+class MyStruct(AvoineBase):
+    foo: str
+    bar: MyInnerStruct
+
+@dataclass
+class MyInnerStruct(AvoineBase):
+    baz: list[str]
+    opt: str | None = None
+
+with open("mystruct.json") as f:
+    data = MyStruct.load(f)
+    # kwargs for the underlying loader/dumper are passed down to them
+    data.dumps(indent=2)
+
+with open("mystruct.toml") as f:
+    print(MyStruct.load(f, format="toml"))
+```
+
+Custom formats can be created by writing functions with the following signatures:
+
+```py
+def load(fp: SupportsRead[AnyStr], **kwargs) -> dict[str, Any]:
+    ...
+
+def loads(s: AnyStr, **kwargs) -> dict[str, Any]:
+    ...
+
+def dump(obj: Any, fp: SupportsWrite[AnyStr], **kwargs) -> None:
+    ...
+
+def dumps(obj: Any, **kwargs) -> AnyStr:
+    ...
+```
+
+Notes:
+
+- `AnyStr` can be `str`, `bytes`, or both
+- `kwargs` are optional
+
+If a set of loading/dumping functions for a format do not match these signatures,
+wrapper functions can be written to transform them to a compatible signature.
+
+## License
+
+avoine is in the public domain.
+
+To the extent possible under law, classabbyamp has waived all copyright and related or neighboring rights to this work.
+
+http://creativecommons.org/publicdomain/zero/1.0/

avoine-0.1.0a1/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "avoine"
+version = "0.1.0a1"
+description = "Tiny serialisation and deserialisation library"
+license = "CC0-1.0"
+readme = "README.md"
+authors = [
+  { name = "classabbyamp", email = "dev@placeviolette.net" }
+]
+
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: File Formats",
+  "Typing :: Typed",
+]
+
+requires-python = ">=3.12"
+dependencies = []
+
+[project.urls]
+homepage = "https://codeberg.org/classabbyamp/avoine"
+source = "https://codeberg.org/classabbyamp/avoine"
+issues = "https://codeberg.org/classabbyamp/avoine/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.13,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+  { include-group = "test" },
+]
+test = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+]

avoine-0.1.0a1/src/avoine/__init__.py

@@ -0,0 +1,2 @@
+from .avoine import avoine, AvoineBase
+__all__ = ["avoine", "AvoineBase"]

avoine-0.1.0a1/src/avoine/avoine.py

@@ -0,0 +1,179 @@
+from collections.abc import Callable
+from dataclasses import dataclass, asdict
+from typing import TYPE_CHECKING, Any, AnyStr, Concatenate, Literal, Self
+
+if TYPE_CHECKING:
+    from _typeshed import DataclassInstance, SupportsRead, SupportsWrite
+else:
+    DataclassInstance = object
+
+type Load[AnyStr: (str, bytes)] = Callable[Concatenate[SupportsRead[AnyStr], ...], dict[str, Any]]
+type Loads[AnyStr: (str, bytes)] = Callable[Concatenate[AnyStr, ...], dict[str, Any]]
+
+type Dump[AnyStr: (str, bytes)] = Callable[Concatenate[Any, SupportsWrite[AnyStr], ...], None]
+type Dumps[AnyStr: (str, bytes)] = Callable[Concatenate[Any, ...], AnyStr]
+
+
+@dataclass
+class AvoineFormat:
+    load: Load | None = None
+    loads: Loads | None = None
+    dump: Dump | None = None
+    dumps: Dumps | None = None
+
+
+class Avoine:
+    """Manages state for avoine"""
+
+    __fmts: dict[str, AvoineFormat] = {}
+    __default_fmt: str | None = None
+
+    def register(self, name: str, *, default: bool = False,
+                 load: Load | None = None,
+                 loads: Loads | None = None,
+                 dump: Dump | None = None,
+                 dumps: Dumps | None = None):
+        """Register a loading/dumping format
+
+        :param name: the name of the format
+        :param default: make this format the default (used when unspecified)
+        :param load: the loader from file-like object function
+        :param loads: the loader from string-like object function
+        :param dump: the dumper to file-like object function
+        :param dumps: the dumper to string-like object function
+        """
+        if name not in self.__fmts:
+            self.__fmts[name] = AvoineFormat()
+        self.__fmts[name].load = load
+        self.__fmts[name].loads = loads
+        self.__fmts[name].dump = dump
+        self.__fmts[name].dumps = dumps
+        if default:
+            self.__default_fmt = name
+
+    def unregister(self, name: str, default: str | None = None):
+        """Unregisters a format
+
+        :param name: the name of the format
+        :param default: the name of the new default format
+        """
+        if name in self.__fmts:
+            del self.__fmts[name]
+        if self.default == name:
+            self.default = None
+        if default:
+            self.default = default
+
+    def clear(self):
+        """Clear all registered formats"""
+        self.__fmts = {}
+        self.__default_fmt = None
+
+    def formats(self, method: Literal["load", "loads", "dump", "dumps"] | None = None) -> list[str]:
+        """List all registered formats
+
+        :param method: list all registered formats that implement this method
+        :raises ValueError: if the method is unknown
+        """
+        match method:
+            case "load" | "loads" | "dump" | "dumps":
+                return [k for k, v in self.__fmts.items() if getattr(v, method) is not None]
+            case None:
+                return list(self.__fmts.keys())
+            case _:
+                raise ValueError(f"unknown method: {method}")
+
+    @property
+    def default(self) -> str | None:
+        """Get the default format for loading/dumping
+
+        :return: the name of the default format (or `None` if not set)
+        """
+        return self.__default_fmt
+
+    @default.setter
+    def default(self, format: str | None = None):
+        """Set the default format for loading/dumping
+
+        :param format: the new default format
+        :raises ValueError: if the format is not registered
+        """
+        if format is not None and format not in self.__fmts:
+            raise ValueError(f"unknown format: {format}")
+        self.__default_fmt = format
+
+    def _get_format(self, format: str | None = None) -> AvoineFormat:
+        if (not format and not (format := self.default)):
+            raise NotImplementedError(f"no default format set, format must be specified")
+        if format not in self.__fmts:
+            raise ValueError(f"unknown format: {format}")
+        return self.__fmts[format]
+
+
+class AvoineBase(DataclassInstance):
+    """Mixin to add loading/dumping capabilities to a dataclass"""
+
+    @classmethod
+    def load(cls, fp: SupportsRead[AnyStr], format: str | None = None, **kwargs) -> Self:
+        """Load data from a file-like object
+
+        Exceptions from the underlying loader are passed up.
+
+        :param fp: the file-like object to read from
+        :param format: the format to use for loading
+        :param kwargs: keyword arguments passed to the underlying loader
+        :raises ValueError: if the format is not registered
+        :raises NotImplementedError: if loading from file-like object is not supported for the specified format
+        """
+        if (load := avoine._get_format(format).load) is None:
+            raise NotImplementedError(f"loading from {format} file is not supported")
+        return cls(**load(fp, **kwargs))
+
+    @classmethod
+    def loads(cls, s: AnyStr, format: str | None = None, **kwargs) -> Self:
+        """Load data from a string-like object
+
+        Exceptions from the underlying loader are passed up.
+
+        :param s: the string-like object to read from
+        :param format: the format to use for loading
+        :param kwargs: keyword arguments passed to the underlying loader
+        :raises ValueError: if the format is not registered
+        :raises NotImplementedError: if loading from string-like object is not supported for the specified format
+        """
+        if (loads := avoine._get_format(format).loads) is None:
+            raise NotImplementedError(f"loading from {format} string is not supported")
+        return cls(**loads(s, **kwargs))
+
+    def dump(self, fp: SupportsWrite[AnyStr], format: str | None = None, **kwargs):
+        """Dump data to a file-like object
+
+        Exceptions from the underlying dumper are passed up.
+
+        :param fp: the file-like object to write to
+        :param format: the format to use for dumping
+        :param kwargs: keyword arguments passed to the underlying dumper
+        :raises ValueError: if the format is not registered
+        :raises NotImplementedError: if dumping to file-like object is not supported for the specified format
+        """
+        if (dump := avoine._get_format(format).dump) is None:
+            raise NotImplementedError(f"dumping to {format} file is not supported")
+        dump(asdict(self), fp, **kwargs)
+
+    def dumps(self, format: str | None = None, **kwargs) -> AnyStr:
+        """Dump data to a string-like object
+
+        Exceptions from the underlying dumper are passed up.
+
+        :param format: the format to use for dumping
+        :param kwargs: keyword arguments passed to the underlying dumper
+        :raises ValueError: if the format is not registered
+        :raises NotImplementedError: if dumping to string-like object is not supported for the specified format
+        :return: the dumped data
+        """
+        if (dumps := avoine._get_format(format).dumps) is None:
+            raise NotImplementedError(f"dumping to {format} string is not supported")
+        return dumps(asdict(self), **kwargs)
+
+
+avoine = Avoine()