pydantic-fixedwidth 0.2.2__py3-none-any.whl

pydantic_fixedwidth/__init__.py

@@ -0,0 +1,3 @@
+from .fixedwidth import Fixedwidth, Options, OrderedField, Padding
+
+__all__ = ("Fixedwidth", "Options", "OrderedField", "Padding")

pydantic_fixedwidth/fixedwidth.py

@@ -0,0 +1,170 @@
+# noqa: D100
+from __future__ import annotations
+
+import logging
+from collections import OrderedDict
+from functools import partial
+from typing import Any, Callable, ClassVar, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.fields import FieldInfo  # noqa: TC002
+from typing_extensions import Self
+
+logger = logging.getLogger(__name__)
+
+
+__counter = 0
+
+
+def OrderedField(  # noqa: N802, PLR0913
+    *args: Any,
+    length: int,
+    justify: Literal["left", "right"] = "left",
+    fill_char: bytes = b" ",
+    encoding: str = "utf-8",
+    from_str: Callable[[str], Any] = lambda x: x.strip(),
+    to_str: Callable[[Any], str] = str,
+    **kwargs: Any,
+) -> Any:
+    """A wrapper for `pydantic.Field` with fixed-width related settings.
+
+    Args:
+        args: Positional arguments to be passed to `pydantic.Field`.
+        length: The fixed width length of the field.
+        justify: Justification of the field content.
+        fill_char: Byte used to fill the field.
+        encoding: Encoding used for the field.
+        from_str: Function to convert from string to the field type.
+            If field type is not `str`, user must provide it.
+        to_str: Function to convert from the field type to string.
+        kwargs: Additional keyword arguments to be passed to `pydantic.Field`.
+
+    Returns:
+        A `pydantic.Field` instance with fixed-width related settings.
+    """
+    global __counter  # noqa: PLW0603
+
+    kwargs.setdefault("json_schema_extra", {})
+    field: FieldInfo = Field(*args, **kwargs)
+
+    options = Options(
+        field_info=field,
+        length=length,
+        order=__counter,
+        justify=justify,
+        fill_char=fill_char,
+        encoding=encoding,
+        from_str=from_str,
+        to_str=to_str,
+    )
+    options.save()
+    __counter += 1
+
+    return field
+
+
+# Shortcuts for convenience
+Padding = partial(OrderedField, default="")
+
+
+class Fixedwidth(BaseModel):
+    """A base class for fixed-width models."""
+
+    _field_options: ClassVar[OrderedDict[str, Options]]
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, *args: Any, **kwargs: Any) -> None:
+        super().__pydantic_init_subclass__(*args, **kwargs)
+
+        field_options = (
+            (
+                key,
+                Options.load(value),
+            )
+            for key, value in cls.model_fields.items()
+            if not value.exclude
+        )
+
+        sorted_by_order = sorted(field_options, key=lambda x: x[1].order)
+        cls._field_options = OrderedDict(sorted_by_order)
+
+    def format_bytes(self) -> bytes:
+        """Format the model as a fixed-width byte string."""
+        values: list[bytes] = []
+        for field_name, options in self._field_options.items():
+            value = getattr(self, field_name)
+            s = options.to_str(value)
+            b = str.encode(s, options.encoding)
+            if len(b) > options.length:
+                msg = f"Value of {field_name!r} ({b!r}; length: {len(b)}) is longer than field length {options.length}"
+                raise ValueError(msg)
+
+            b = (
+                b.ljust(options.length, options.fill_char)
+                if options.justify == "left"
+                else b.rjust(options.length, options.fill_char)
+            )
+            values.append(b)
+
+        result = b"".join(values)
+        logger.debug("Formatted %r into %r", self, result)
+
+        return result
+
+    @classmethod
+    def parse_bytes(cls, raw: bytes, **extras: Any) -> Self:
+        """Parse a fixed-width byte string into a model."""
+        values: dict[str, Any] = {}
+        index = 0
+        for field_name, options in cls._field_options.items():
+            b = raw[index : index + options.length]
+            s = bytes.decode(b, options.encoding)
+            value = options.from_str(s)
+            values[field_name] = value
+            index += options.length
+
+        obj = cls(**values, **extras)
+        logger.debug("Parsed %r into %r", raw, obj)
+
+        return obj
+
+
+_OPTIONS_KEY = "__pydantic_fixedwidth__"
+"""Key to store `Options` in `field_info.json_schema_extra`."""
+
+
+class Options(BaseModel):
+    """Options for a fixed-width field."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    field_info: FieldInfo
+
+    length: int
+    order: int
+    justify: Literal["left", "right"]
+    fill_char: bytes = Field(..., min_length=1, max_length=1)
+    encoding: str
+
+    from_str: Callable[[str], Any]
+    """Callable to create object from a string to the field type."""
+
+    to_str: Callable[[Any], str]
+    """Callable to cast the field type to a string."""
+
+    def save(self) -> None:
+        """Save `Options` to `field_info`."""
+        if not isinstance(self.field_info.json_schema_extra, dict):
+            msg = f"`json_schema_extra` must be a `dict`, but got: {type(self.field_info.json_schema_extra)!r}"
+            raise TypeError(msg)
+
+        self.field_info.json_schema_extra[_OPTIONS_KEY] = self.model_dump()
+
+    @classmethod
+    def load(cls, field_info: FieldInfo) -> Options:
+        """Load `Options` from `field_info`."""
+        if not isinstance(field_info.json_schema_extra, dict):
+            msg = f"`json_schema_extra` must be a `dict`, but got: {type(field_info.json_schema_extra)!r}"
+            raise TypeError(msg)
+
+        return cls.model_validate(field_info.json_schema_extra.get(_OPTIONS_KEY, {}))

pydantic_fixedwidth-0.2.2.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: pydantic-fixedwidth
+Version: 0.2.2
+Summary: Custom Pydantic models for parsing and serializing fixed-width format of data.
+Project-URL: Homepage, https://github.com/lasuillard/pydantic-fixedwidth
+Project-URL: Repository, https://github.com/lasuillard/pydantic-fixedwidth.git
+Project-URL: Issues, https://github.com/lasuillard/pydantic-fixedwidth/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: <4.0,>=3.9
+Requires-Dist: pydantic<3,>=2
+Description-Content-Type: text/markdown
+
+# pydantic-fixedwidth
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![codecov](https://codecov.io/gh/lasuillard-s/pydantic-fixedwidth/graph/badge.svg?token=R5pQWB43DP)](https://codecov.io/gh/lasuillard-s/pydantic-fixedwidth)
+[![PyPI - Version](https://img.shields.io/pypi/v/pydantic-fixedwidth)](https://pypi.org/project/pydantic-fixedwidth/)
+
+Custom Pydantic models for serializing and deserializing fixed-width format data.
+
+
+## 🚀 Quick Start
+
+Install this package with pip:
+
+```shell
+$ pip install pydantic-fixedwidth
+```
+
+Usage example:
+
+```python
+from datetime import datetime, timezone
+
+from pydantic_fixedwidth import Fixedwidth, Padding
+from pydantic_fixedwidth import OrderedField as Field
+
+tzinfo = timezone.utc
+
+
+class SomeRequest(Fixedwidth):
+    string: str = Field(length=8)
+    hangul: str = Field(length=6)
+    number: int = Field(length=10, justify="right", fill_char=b"0")
+
+    # Just an padding field
+    p_: str = Padding(length=10)
+
+    # This field will be ignored in ser/de
+    ignore: str = Field(length=10, default="IGNORE", exclude=True)
+
+    ts: datetime = Field(
+        length=20,
+        to_str=lambda dt: dt.strftime("%Y%m%d%H%M%S%f"),
+        from_str=lambda s: datetime.strptime(s, "%Y%m%d%H%M%S%f").replace(tzinfo=tzinfo),
+    )
+
+
+# Format model to bytes
+some_request = SomeRequest(
+    string="<DFG&",
+    hangul="한글",
+    number=381,
+    ts=datetime(2024, 1, 23, 14, 11, 20, 124277, tzinfo=tzinfo),
+)
+b = some_request.format_bytes()
+
+assert len(b) == 54
+assert b == b"<DFG&   \xed\x95\x9c\xea\xb8\x800000000381          20240123141120124277"
+
+# Parse bytes into model
+parsed_request = SomeRequest.parse_bytes(b)
+
+assert parsed_request == some_request
+```

pydantic_fixedwidth-0.2.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+pydantic_fixedwidth/__init__.py,sha256=vVLHRSOlPVHzVbG3RGpUqNcBUPrnbbDSC03BwrMVMWA,131
+pydantic_fixedwidth/fixedwidth.py,sha256=bYTPpWvGlwQM2l6LdOlADQvvCWNmXniLHnTutDjcKao,5379
+pydantic_fixedwidth/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pydantic_fixedwidth-0.2.2.dist-info/METADATA,sha256=pyXQ1QcNV5MmbtxTsFq5ZXoS0639ZnNo6eMtpxtEGZ8,2288
+pydantic_fixedwidth-0.2.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pydantic_fixedwidth-0.2.2.dist-info/licenses/LICENSE,sha256=Q5GkvYijQ2KTQ-QWhv43ilzCno4ZrzrEuATEQZd9rYo,1067
+pydantic_fixedwidth-0.2.2.dist-info/RECORD,,

pydantic_fixedwidth-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pydantic_fixedwidth-0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yuchan Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.