hexconv 0.2.7__tar.gz → 0.3.1__tar.gz

{hexconv-0.2.7/src/hexconv.egg-info → hexconv-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexconv
-Version: 0.2.7
+Version: 0.3.1
 Summary: Pythonic conversion toolkit for bytes, hex, integers, arrays, binary strings, base64, and text.
 Author: hexconv contributors
 License-Expression: MIT
@@ -23,7 +23,10 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Dynamic: license-file
 
@@ -319,6 +322,23 @@ Available format specs all work in their simplest bare form:
 - `Bits()`
 - `Auto()`
 
+The short names are ergonomic aliases of the explicit long-form specs — pick
+whichever reads better, they resolve to the same format:
+
+| Short | Long form |
+| --- | --- |
+| `Hex` | `HexString` |
+| `Binary` | `BinaryString` |
+| `Base64` / `Base32` / `Base85` / `Ascii85` | `Base64String` / `Base32String` / `Base85String` / `Ascii85String` |
+| `Escaped` | `EscapedString` |
+| `Hexdump` | `HexDump` |
+| `Struct` | `StructFormat` |
+| `Bits` | `BitArray` |
+| `DecimalInt` / `DecimalIntArray` | `Int` / `IntArray` |
+| `LargeHexNumber` | `HexInt` |
+| `ASCIIText` / `RawString` | `Text` |
+| `Group` (transform) | `Chunk` |
+
 Add options only when you need control over formatting or parsing:
 
 - Display: `Hex(sep=" ", prefix=True, uppercase=True)`, `HexArray(width=2)`.
@@ -363,7 +383,7 @@ hx.from_hex("dead beef").bytes
 hx.from_text("data").hex
 # '64617461'
 
-hx.convert("data", from_=hx.Text, to=hx.HexString)
+hx.convert("data", hx.Text, hx.HexString)
 # '64617461'
 ```
 

{hexconv-0.2.7 → hexconv-0.3.1}/README.md

@@ -290,6 +290,23 @@ Available format specs all work in their simplest bare form:
 - `Bits()`
 - `Auto()`
 
+The short names are ergonomic aliases of the explicit long-form specs — pick
+whichever reads better, they resolve to the same format:
+
+| Short | Long form |
+| --- | --- |
+| `Hex` | `HexString` |
+| `Binary` | `BinaryString` |
+| `Base64` / `Base32` / `Base85` / `Ascii85` | `Base64String` / `Base32String` / `Base85String` / `Ascii85String` |
+| `Escaped` | `EscapedString` |
+| `Hexdump` | `HexDump` |
+| `Struct` | `StructFormat` |
+| `Bits` | `BitArray` |
+| `DecimalInt` / `DecimalIntArray` | `Int` / `IntArray` |
+| `LargeHexNumber` | `HexInt` |
+| `ASCIIText` / `RawString` | `Text` |
+| `Group` (transform) | `Chunk` |
+
 Add options only when you need control over formatting or parsing:
 
 - Display: `Hex(sep=" ", prefix=True, uppercase=True)`, `HexArray(width=2)`.
@@ -334,7 +351,7 @@ hx.from_hex("dead beef").bytes
 hx.from_text("data").hex
 # '64617461'
 
-hx.convert("data", from_=hx.Text, to=hx.HexString)
+hx.convert("data", hx.Text, hx.HexString)
 # '64617461'
 ```
 

{hexconv-0.2.7 → hexconv-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hexconv"
-version = "0.2.7"
+version = "0.3.1"
 description = "Pythonic conversion toolkit for bytes, hex, integers, arrays, binary strings, base64, and text."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.10"
@@ -31,7 +31,10 @@ classifiers = [
 [project.optional-dependencies]
 dev = [
     "build",
+    "hypothesis",
+    "mypy",
     "pytest",
+    "ruff",
     "twine",
 ]
 
@@ -44,3 +47,21 @@ hexconv = ["py.typed"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+# Public re-exports are grouped by concept rather than sorted alphabetically.
+"src/hexconv/__init__.py" = ["I001"]
+
+[tool.mypy]
+python_version = "3.10"
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+strict_equality = true

{hexconv-0.2.7 → hexconv-0.3.1}/src/hexconv/__init__.py

@@ -1,52 +1,60 @@
 """Conversion toolkit for bytes, hex, integers, arrays, binary, base64, and text."""
 
 from ._core import (
-    ASCIIText,
-    Auto,
+    # Core types and errors
     AutoResult,
-    Ascii85,
+    Converter,
+    HexConvError,
+    Pipeline,
+    Transform,
+    Value,
+    # Format specifications (explicit long-form names)
     Ascii85String,
-    Base64String,
-    Base64,
-    Base32,
+    Auto,
     Base32String,
-    Base85,
+    Base64String,
     Base85String,
     BinaryString,
-    Binary,
     BitArray,
-    Bits,
     Bytes,
     BytesArray,
     BytesString,
-    Chunk,
-    Converter,
-    DecimalInt,
-    DecimalIntArray,
-    Escaped,
     EscapedString,
-    Group,
-    Hex,
     HexArray,
-    HexConvError,
     HexDump,
-    Hexdump,
     HexInt,
     HexNumbersArray,
     HexString,
     Int,
     IntArray,
+    StructFormat,
+    Text,
+    # Short, ergonomic aliases for the format specifications above
+    ASCIIText,
+    Ascii85,
+    Base32,
+    Base64,
+    Base85,
+    Binary,
+    Bits,
+    DecimalInt,
+    DecimalIntArray,
+    Escaped,
+    Hex,
+    Hexdump,
     LargeHexNumber,
-    Pad,
-    Pipeline,
     RawString,
-    Reverse,
     Struct,
-    StructFormat,
-    Text,
-    Transform,
-    Value,
+    # Pipeline transforms
+    Chunk,
+    Group,
+    Pad,
+    Reverse,
+    # One-shot conversion and pipeline builders
     convert,
+    infer,
+    pipeline,
+    # Source helpers
     from_ascii85,
     from_auto,
     from_base32,
@@ -66,57 +74,63 @@ from ._core import (
     from_int_array,
     from_struct,
     from_text,
-    infer,
-    pipeline,
 )
 
 __all__ = [
-    "ASCIIText",
-    "Auto",
+    # Core types and errors
     "AutoResult",
-    "Ascii85",
+    "Converter",
+    "HexConvError",
+    "Pipeline",
+    "Transform",
+    "Value",
+    # Format specifications (explicit long-form names)
     "Ascii85String",
-    "Base32",
+    "Auto",
     "Base32String",
     "Base64String",
-    "Base64",
-    "Base85",
     "Base85String",
-    "Binary",
     "BinaryString",
     "BitArray",
-    "Bits",
     "Bytes",
     "BytesArray",
     "BytesString",
-    "Chunk",
-    "Converter",
-    "DecimalInt",
-    "DecimalIntArray",
-    "Escaped",
     "EscapedString",
-    "Group",
-    "Hex",
     "HexArray",
-    "HexConvError",
     "HexDump",
-    "Hexdump",
     "HexInt",
     "HexNumbersArray",
     "HexString",
     "Int",
     "IntArray",
+    "StructFormat",
+    "Text",
+    # Short, ergonomic aliases for the format specifications above
+    "ASCIIText",
+    "Ascii85",
+    "Base32",
+    "Base64",
+    "Base85",
+    "Binary",
+    "Bits",
+    "DecimalInt",
+    "DecimalIntArray",
+    "Escaped",
+    "Hex",
+    "Hexdump",
     "LargeHexNumber",
-    "Pad",
-    "Pipeline",
     "RawString",
-    "Reverse",
     "Struct",
-    "StructFormat",
-    "Text",
-    "Transform",
-    "Value",
+    # Pipeline transforms
+    "Chunk",
+    "Group",
+    "Pad",
+    "Reverse",
+    # One-shot conversion and pipeline builders
     "convert",
+    "infer",
+    "pipeline",
+    # Source helpers
     "from_ascii85",
     "from_auto",
     "from_base32",
@@ -136,6 +150,4 @@ __all__ = [
     "from_int_array",
     "from_struct",
     "from_text",
-    "infer",
-    "pipeline",
 ]

{hexconv-0.2.7 → hexconv-0.3.1}/src/hexconv/_core.py

@@ -3,12 +3,13 @@ from __future__ import annotations
 import ast
 import base64
 import binascii
+import builtins
 import codecs
 import re
 import struct
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
 from dataclasses import dataclass, field
-from typing import Any, Callable, TypeAlias
+from typing import Any, Literal, TypeAlias, overload
 
 
 class HexConvError(ValueError):
@@ -18,12 +19,12 @@ class HexConvError(ValueError):
 class _Format:
     """Base class for public format marker classes."""
 
-    def __call__(self, value: Any) -> "Value":
+    def __call__(self, value: Any) -> Value:
         """Parse a value using this configured format."""
 
         return _parse(value, self)
 
-    def __rshift__(self, other: Any) -> "Pipeline":
+    def __rshift__(self, other: Any) -> Pipeline:
         """Compose this format with a transform, target format, or pipeline."""
 
         return Pipeline(source=self) >> other
@@ -87,7 +88,7 @@ class HexArray(_Format):
         width: int | None = None,
         prefix: bool = False,
         uppercase: bool = False,
-        endian: "Endian" = "big",
+        endian: Endian = "big",
         pad_odd: bool = True,
     ) -> None:
         self.width = width
@@ -118,7 +119,7 @@ class HexNumbersArray(_Format):
         self,
         *,
         width: int | None = 1,
-        endian: "Endian" = "big",
+        endian: Endian = "big",
         signed: bool = False,
     ) -> None:
         self.width = width
@@ -140,7 +141,7 @@ class HexInt(_Format):
         *,
         min_width: int = 1,
         width: int | None = None,
-        endian: "Endian" = "big",
+        endian: Endian = "big",
         signed: bool = False,
         pad_odd: bool = True,
     ) -> None:
@@ -174,7 +175,7 @@ class Int(_Format):
         *,
         min_width: int = 1,
         width: int | None = None,
-        endian: "Endian" = "big",
+        endian: Endian = "big",
         signed: bool = False,
     ) -> None:
         self.min_width = min_width
@@ -205,7 +206,7 @@ class IntArray(_Format):
         self,
         *,
         width: int | None = None,
-        endian: "Endian" = "big",
+        endian: Endian = "big",
         signed: bool = False,
     ) -> None:
         self.width = width
@@ -258,7 +259,7 @@ class BinaryString(_Format):
         sep: str = "",
         prefix: bool = False,
         pad_odd: bool = True,
-        bit_order: "BitOrder" = "msb",
+        bit_order: BitOrder = "msb",
     ) -> None:
         self.sep = sep
         self.prefix = prefix
@@ -414,9 +415,9 @@ class BitArray(_Format):
     def __init__(
         self,
         *,
-        bit_order: "BitOrder" = "msb",
+        bit_order: BitOrder = "msb",
         pad: bool = True,
-        pad_side: "PadSide" = "left",
+        pad_side: PadSide = "left",
     ) -> None:
         self.bit_order = bit_order
         self.pad = pad
@@ -435,9 +436,9 @@ class BitArray(_Format):
 
 Format: TypeAlias = type[_Format]
 FormatLike: TypeAlias = type[_Format] | _Format
-Endian: TypeAlias = str
-BitOrder: TypeAlias = str
-PadSide: TypeAlias = str
+Endian: TypeAlias = Literal["big", "little"]
+BitOrder: TypeAlias = Literal["msb", "lsb"]
+PadSide: TypeAlias = Literal["left", "right"]
 
 
 Hex = HexString
@@ -468,12 +469,12 @@ class Value:
     source: str | None = None
     meta: dict[str, Any] = field(default_factory=dict)
 
-    def with_data(self, data: bytes, *, source: str | None = None) -> "Value":
+    def with_data(self, data: bytes, *, source: str | None = None) -> Value:
         """Return a copy with different bytes and preserved metadata."""
 
         return Value(bytes(data), source=source or self.source, meta=dict(self.meta))
 
-    def with_meta(self, **meta: Any) -> "Value":
+    def with_meta(self, **meta: Any) -> Value:
         """Return a copy with additional metadata used by composable transforms."""
 
         merged = dict(self.meta)
@@ -484,6 +485,12 @@ class Value:
         """Emit this value using a public format marker such as HexString."""
 
         format_type = _format_type(format_)
+        if "chunk_width" in self.meta and format_type not in _CHUNK_AWARE_OUTPUTS:
+            raise HexConvError(
+                f"chunking has no effect on {format_type.__name__} output; emit to a "
+                "chunk-aware format such as HexArray, HexNumbersArray, IntArray, or "
+                "DecimalIntArray, or drop the Chunk/Group step"
+            )
         output_options = _format_options(format_, "output")
         output_options.update(options)
         try:
@@ -602,18 +609,6 @@ class Value:
         _validate_endian(endian)
         return int.from_bytes(self._data, endian, signed=signed)
 
-    @property
-    def int(self) -> int:
-        """Shortcut for to_int()."""
-
-        return self.to_int()
-
-    @property
-    def integer(self) -> int:
-        """Shortcut for to_int()."""
-
-        return self.to_int()
-
     def to_int_array(
         self,
         *,
@@ -779,6 +774,22 @@ class Value:
             raise HexConvError("chunk width cannot be None")
         return chunk_width
 
+    # ``int``/``integer`` are convenience shortcuts whose names shadow the builtin
+    # ``int``. They are declared after every method above so those methods keep
+    # annotating with the builtin, and they spell their own return type as
+    # ``builtins.int`` so their order here does not matter.
+    @property
+    def int(self) -> builtins.int:
+        """Shortcut for to_int()."""
+
+        return self.to_int()
+
+    @property
+    def integer(self) -> builtins.int:
+        """Shortcut for to_int()."""
+
+        return self.to_int()
+
 
 @dataclass(frozen=True)
 class AutoResult:
@@ -796,7 +807,7 @@ class Transform:
     def __call__(self, value: Any) -> Value:
         return self.apply(_ensure_value(value))
 
-    def __rshift__(self, other: Any) -> "Pipeline":
+    def __rshift__(self, other: Any) -> Pipeline:
         return Pipeline(transforms=[self]) >> other
 
     def apply(self, value: Value) -> Value:
@@ -852,7 +863,7 @@ class Pad(Transform):
         width: int | None = None,
         block_size: int | None = None,
         byte: int = 0,
-    ) -> "Pad":
+    ) -> Pad:
         return cls(width=width, block_size=block_size, byte=byte, side="left")
 
     @classmethod
@@ -862,7 +873,7 @@ class Pad(Transform):
         width: int | None = None,
         block_size: int | None = None,
         byte: int = 0,
-    ) -> "Pad":
+    ) -> Pad:
         return cls(width=width, block_size=block_size, byte=byte, side="right")
 
     def apply(self, value: Value) -> Value:
@@ -899,23 +910,23 @@ class Pipeline:
         self.transforms = list(transforms or [])
         self.target = target
 
-    def from_(self, source: FormatLike) -> "Pipeline":
+    def from_(self, source: FormatLike) -> Pipeline:
         return Pipeline(source=source, transforms=self.transforms, target=self.target)
 
-    def to(self, target: FormatLike) -> "Pipeline":
+    def to(self, target: FormatLike) -> Pipeline:
         return Pipeline(source=self.source, transforms=self.transforms, target=target)
 
-    def then(self, transform: Transform) -> "Pipeline":
+    def then(self, transform: Transform) -> Pipeline:
         return Pipeline(
             source=self.source,
             transforms=[*self.transforms, transform],
             target=self.target,
         )
 
-    def chunk(self, width: int, *, strict: bool = True) -> "Pipeline":
+    def chunk(self, width: int, *, strict: bool = True) -> Pipeline:
         return self.then(Chunk(width, strict=strict))
 
-    def group(self, width: int, *, strict: bool = True) -> "Pipeline":
+    def group(self, width: int, *, strict: bool = True) -> Pipeline:
         return self.then(Group(width, strict=strict))
 
     def pad(
@@ -925,13 +936,13 @@ class Pipeline:
         block_size: int | None = None,
         byte: int = 0,
         side: PadSide = "left",
-    ) -> "Pipeline":
+    ) -> Pipeline:
         return self.then(Pad(width=width, block_size=block_size, byte=byte, side=side))
 
-    def reverse(self) -> "Pipeline":
+    def reverse(self) -> Pipeline:
         return self.then(Reverse())
 
-    def __rshift__(self, other: Any) -> "Pipeline":
+    def __rshift__(self, other: Any) -> Pipeline:
         if isinstance(other, Pipeline):
             source = self.source if self.source is not None else other.source
             return Pipeline(
@@ -1002,31 +1013,22 @@ def convert(
     from_format: FormatLike | None = None,
     to_format: FormatLike | None = None,
     *,
-    from_: FormatLike | None = None,
-    to: FormatLike | None = None,
     input_options: dict[str, Any] | None = None,
     output_options: dict[str, Any] | None = None,
 ) -> Any:
     """One-shot conversion between explicit formats.
 
-    Preferred:
+    The source and target formats are positional:
+
         convert(value, Hex(), Bytes())
 
-    Backward-compatible:
-        convert(value, from_=Hex(), to=Bytes())
+    Omit ``from_format`` to infer the source with ``Auto``; omit ``to_format``
+    to emit raw ``Bytes``.
     """
 
-    if from_format is not None and from_ is not None:
-        raise HexConvError("use either positional input format or from_, not both")
-    if to_format is not None and to is not None:
-        raise HexConvError("use either positional output format or to, not both")
-
-    input_format = from_format if from_format is not None else from_
-    output_format = to_format if to_format is not None else to
-
     return Converter(
-        Auto if input_format is None else input_format,
-        Bytes if output_format is None else output_format,
+        Auto if from_format is None else from_format,
+        Bytes if to_format is None else to_format,
         input_options=input_options,
         output_options=output_options,
     )(value)
@@ -1082,6 +1084,18 @@ def infer(value: Any) -> AutoResult:
     raise HexConvError(f"cannot infer source format for {type(value).__name__}")
 
 
+@overload
+def from_auto(value: Any, *, explain: Literal[False] = ...) -> Value: ...
+
+
+@overload
+def from_auto(value: Any, *, explain: Literal[True]) -> AutoResult: ...
+
+
+@overload
+def from_auto(value: Any, *, explain: bool) -> Value | AutoResult: ...
+
+
 def from_auto(value: Any, *, explain: bool = False) -> Value | AutoResult:
     """Parse a value using convenience heuristics.
 
@@ -1100,6 +1114,12 @@ def from_auto(value: Any, *, explain: bool = False) -> Value | AutoResult:
     return result if explain else result.value
 
 
+def _from_auto_value(value: Any) -> Value:
+    """Auto-format parser that always returns a Value (never AutoResult)."""
+
+    return from_auto(value)
+
+
 def from_bytes(value: bytes | bytearray | memoryview | Iterable[int]) -> Value:
     """Parse a bytes-like object or a byte-sized integer sequence."""
 
@@ -1549,7 +1569,7 @@ def _emit_bits(value: Value, **options: Any) -> list[int]:
 
 
 _INPUTS: dict[Format, Callable[..., Value]] = {
-    Auto: from_auto,
+    Auto: _from_auto_value,
     Bytes: from_bytes,
     BytesArray: from_bytes_array,
     BytesString: from_bytes_string,
@@ -1604,6 +1624,14 @@ _OUTPUTS: dict[Format, Callable[..., Any]] = {
 }
 
 
+# Output formats whose emitters honor a Chunk/Group width stored on Value.meta.
+# Every other target silently ignores chunking, so emitting to one after a chunk
+# is treated as a mistake (see Value.to).
+_CHUNK_AWARE_OUTPUTS: frozenset[Format] = frozenset(
+    {HexArray, HexNumbersArray, IntArray, DecimalIntArray}
+)
+
+
 def _is_format_like(value: Any) -> bool:
     return isinstance(value, _Format) or (
         isinstance(value, type) and issubclass(value, _Format)
@@ -1631,10 +1659,7 @@ def _format_options(format_: FormatLike, direction: str) -> dict[str, Any]:
 def _ensure_value(value: Any) -> Value:
     if isinstance(value, Value):
         return value
-    parsed = from_auto(value)
-    if isinstance(parsed, AutoResult):
-        return parsed.value
-    return parsed
+    return from_auto(value)
 
 
 def _validate_endian(endian: Endian) -> None:
@@ -1824,6 +1849,8 @@ def _int_to_bytes(
 
 
 def _signed_int_to_minimal_bytes(value: int, *, min_width: int, endian: Endian) -> bytes:
+    # Two's complement needs a bit beyond the magnitude for the sign, so start
+    # one byte wider than the magnitude and widen further until the value fits.
     candidate = max(min_width, 1, (abs(value).bit_length() + 8) // 8)
     for width in range(candidate, candidate + 2):
         try:

{hexconv-0.2.7 → hexconv-0.3.1/src/hexconv.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexconv
-Version: 0.2.7
+Version: 0.3.1
 Summary: Pythonic conversion toolkit for bytes, hex, integers, arrays, binary strings, base64, and text.
 Author: hexconv contributors
 License-Expression: MIT
@@ -23,7 +23,10 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Dynamic: license-file
 
@@ -319,6 +322,23 @@ Available format specs all work in their simplest bare form:
 - `Bits()`
 - `Auto()`
 
+The short names are ergonomic aliases of the explicit long-form specs — pick
+whichever reads better, they resolve to the same format:
+
+| Short | Long form |
+| --- | --- |
+| `Hex` | `HexString` |
+| `Binary` | `BinaryString` |
+| `Base64` / `Base32` / `Base85` / `Ascii85` | `Base64String` / `Base32String` / `Base85String` / `Ascii85String` |
+| `Escaped` | `EscapedString` |
+| `Hexdump` | `HexDump` |
+| `Struct` | `StructFormat` |
+| `Bits` | `BitArray` |
+| `DecimalInt` / `DecimalIntArray` | `Int` / `IntArray` |
+| `LargeHexNumber` | `HexInt` |
+| `ASCIIText` / `RawString` | `Text` |
+| `Group` (transform) | `Chunk` |
+
 Add options only when you need control over formatting or parsing:
 
 - Display: `Hex(sep=" ", prefix=True, uppercase=True)`, `HexArray(width=2)`.
@@ -363,7 +383,7 @@ hx.from_hex("dead beef").bytes
 hx.from_text("data").hex
 # '64617461'
 
-hx.convert("data", from_=hx.Text, to=hx.HexString)
+hx.convert("data", hx.Text, hx.HexString)
 # '64617461'
 ```
 

{hexconv-0.2.7 → hexconv-0.3.1}/src/hexconv.egg-info/SOURCES.txt

@@ -10,4 +10,5 @@ src/hexconv.egg-info/SOURCES.txt
 src/hexconv.egg-info/dependency_links.txt
 src/hexconv.egg-info/requires.txt
 src/hexconv.egg-info/top_level.txt
-tests/test_hexconv.py
+tests/test_hexconv.py
+tests/test_properties.py

{hexconv-0.2.7 → hexconv-0.3.1}/src/hexconv.egg-info/requires.txt

@@ -1,5 +1,8 @@
 
 [dev]
 build
+hypothesis
+mypy
 pytest
+ruff
 twine

{hexconv-0.2.7 → hexconv-0.3.1}/tests/test_hexconv.py

@@ -44,62 +44,150 @@ def test_converter_class_matches_proposed_usage():
 
 
 def test_convert_one_shot():
-    assert hx.convert("data", from_=hx.Text, to=hx.HexString) == "64617461"
+    assert hx.convert("data", hx.Text, hx.HexString) == "64617461"
     assert hx.convert("de ad be ef", hx.Hex(), hx.Bytes()) == b"\xde\xad\xbe\xef"
     assert hx.convert(b"\xde\xad\xbe\xef", hx.Bytes(), hx.Hex(sep=" ")) == "de ad be ef"
     assert hx.convert("data", hx.Text(), hx.Hex(prefix=True)) == "0x64617461"
 
 
-def test_documented_format_options_quick_tour():
-    assert hx.from_hex("de ad:be-ef").bytes == b"\xde\xad\xbe\xef"
-    assert hx.from_bytes(b"\xde\xad\xbe\xef").to(hx.Hex(sep=":", uppercase=True)) == "DE:AD:BE:EF"
-    assert hx.from_bytes_array([0xDE, 0xAD, 0xBE, 0xEF]).to(
-        hx.HexArray(width=2, prefix=True, uppercase=True)
-    ) == ["0xDEAD", "0xBEEF"]
-    assert hx.from_text("π", encoding="utf-8").to(hx.Hex(prefix=True)) == "0xcf80"
-    assert hx.from_int(0x12345678, endian="little").hex == "78563412"
-    assert hx.from_int_array([0x1234, 0x5678], width=2).to(hx.HexArray(width=2)) == [
-        "1234",
-        "5678",
-    ]
-    assert hx.from_binary("01100100 01100001 01110100 01100001").text == "data"
-    assert hx.from_base64("-_8", urlsafe=True, padding=False).hex == "fbff"
-    assert hx.from_base32("MRQXIYI", padding=False).text == "data"
-    assert hx.from_escaped(r"\xDE\xAD").hex == "dead"
-    assert hx.from_struct((0x1234, 0x5678), fmt=">HH").hex == "12345678"
-    assert hx.from_bits("101", pad_side="right").hex == "a0"
-
-    assert hx.convert("de ad be ef", hx.Hex(), hx.Bytes()) == b"\xde\xad\xbe\xef"
-    assert (
-        hx.convert(
+_QUICK_TOUR_CASES = [
+    (
+        "hex_separators",
+        lambda: hx.from_hex("de ad:be-ef").bytes,
+        b"\xde\xad\xbe\xef",
+    ),
+    (
+        "hex_sep_uppercase",
+        lambda: hx.from_bytes(b"\xde\xad\xbe\xef").to(hx.Hex(sep=":", uppercase=True)),
+        "DE:AD:BE:EF",
+    ),
+    (
+        "hex_array_width2",
+        lambda: hx.from_bytes_array([0xDE, 0xAD, 0xBE, 0xEF]).to(
+            hx.HexArray(width=2, prefix=True, uppercase=True)
+        ),
+        ["0xDEAD", "0xBEEF"],
+    ),
+    (
+        "text_utf8_prefix",
+        lambda: hx.from_text("π", encoding="utf-8").to(hx.Hex(prefix=True)),
+        "0xcf80",
+    ),
+    (
+        "int_little_endian",
+        lambda: hx.from_int(0x12345678, endian="little").hex,
+        "78563412",
+    ),
+    (
+        "int_array_width2",
+        lambda: hx.from_int_array([0x1234, 0x5678], width=2).to(hx.HexArray(width=2)),
+        ["1234", "5678"],
+    ),
+    (
+        "binary_to_text",
+        lambda: hx.from_binary("01100100 01100001 01110100 01100001").text,
+        "data",
+    ),
+    (
+        "base64_urlsafe_in",
+        lambda: hx.from_base64("-_8", urlsafe=True, padding=False).hex,
+        "fbff",
+    ),
+    (
+        "base32_no_padding_in",
+        lambda: hx.from_base32("MRQXIYI", padding=False).text,
+        "data",
+    ),
+    (
+        "escaped_in",
+        lambda: hx.from_escaped(r"\xDE\xAD").hex,
+        "dead",
+    ),
+    (
+        "struct_pack",
+        lambda: hx.from_struct((0x1234, 0x5678), fmt=">HH").hex,
+        "12345678",
+    ),
+    (
+        "bits_pad_right",
+        lambda: hx.from_bits("101", pad_side="right").hex,
+        "a0",
+    ),
+    (
+        "convert_hex_to_bytes",
+        lambda: hx.convert("de ad be ef", hx.Hex(), hx.Bytes()),
+        b"\xde\xad\xbe\xef",
+    ),
+    (
+        "convert_bytes_to_hex",
+        lambda: hx.convert(
             b"\xde\xad\xbe\xef",
             hx.Bytes(),
             hx.Hex(sep=" ", prefix=True, uppercase=True),
-        )
-        == "0xDE AD BE EF"
-    )
-    assert hx.convert(["0xDEAD", "0xBEEF"], hx.HexArray(width=2), hx.IntArray(width=2)) == [
-        57005,
-        48879,
-    ]
-    assert hx.convert("78563412", hx.Hex(), hx.Int(endian="little")) == 305419896
-    assert hx.convert("0b10100000", hx.Binary(bit_order="lsb"), hx.Hex()) == "05"
-    assert hx.from_text("data").to(hx.Base64(urlsafe=True, padding=False)) == "ZGF0YQ"
-    assert hx.from_text("data").to(hx.Base85()) == "WMOn+"
-    assert hx.from_text("data").to(hx.Ascii85(adobe=True)) == "<~A79Rg~>"
-    assert hx.from_hex("deadbeef").to(hx.Hexdump(width=2, offset=False, ascii=False)) == "de ad\nbe ef"
-    assert hx.from_hex("dead").to(hx.Escaped(uppercase=True)) == r"\xDE\xAD"
-    assert hx.from_hex("0506").to(hx.Binary(sep=" ", prefix=True, bit_order="lsb")) == (
-        "0b10100000 0b01100000"
-    )
-    assert hx.from_hex("05").to(hx.Bits(bit_order="lsb")) == [1, 0, 1, 0, 0, 0, 0, 0]
-
-
-def test_convert_rejects_mixed_positional_and_keyword_formats():
-    with pytest.raises(hx.HexConvError, match="from_"):
-        hx.convert("data", hx.Text(), from_=hx.Text(), to=hx.Hex())
-    with pytest.raises(hx.HexConvError, match="to"):
-        hx.convert("data", hx.Text(), hx.Hex(), to=hx.Hex())
+        ),
+        "0xDE AD BE EF",
+    ),
+    (
+        "convert_hexarray_to_intarray",
+        lambda: hx.convert(
+            ["0xDEAD", "0xBEEF"], hx.HexArray(width=2), hx.IntArray(width=2)
+        ),
+        [57005, 48879],
+    ),
+    (
+        "convert_hex_to_int_little",
+        lambda: hx.convert("78563412", hx.Hex(), hx.Int(endian="little")),
+        305419896,
+    ),
+    (
+        "convert_binary_to_hex_lsb",
+        lambda: hx.convert("0b10100000", hx.Binary(bit_order="lsb"), hx.Hex()),
+        "05",
+    ),
+    (
+        "base64_urlsafe_out",
+        lambda: hx.from_text("data").to(hx.Base64(urlsafe=True, padding=False)),
+        "ZGF0YQ",
+    ),
+    (
+        "base85_out",
+        lambda: hx.from_text("data").to(hx.Base85()),
+        "WMOn+",
+    ),
+    (
+        "ascii85_adobe_out",
+        lambda: hx.from_text("data").to(hx.Ascii85(adobe=True)),
+        "<~A79Rg~>",
+    ),
+    (
+        "hexdump_bare_out",
+        lambda: hx.from_hex("deadbeef").to(hx.Hexdump(width=2, offset=False, ascii=False)),
+        "de ad\nbe ef",
+    ),
+    (
+        "escaped_uppercase_out",
+        lambda: hx.from_hex("dead").to(hx.Escaped(uppercase=True)),
+        r"\xDE\xAD",
+    ),
+    (
+        "binary_sep_prefix_lsb_out",
+        lambda: hx.from_hex("0506").to(hx.Binary(sep=" ", prefix=True, bit_order="lsb")),
+        "0b10100000 0b01100000",
+    ),
+    (
+        "bits_lsb_out",
+        lambda: hx.from_hex("05").to(hx.Bits(bit_order="lsb")),
+        [1, 0, 1, 0, 0, 0, 0, 0],
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    "op, expected",
+    [pytest.param(op, expected, id=name) for name, op, expected in _QUICK_TOUR_CASES],
+)
+def test_documented_format_options_quick_tour(op, expected):
+    assert op() == expected
 
 
 def test_converter_options():
@@ -115,7 +203,7 @@ def test_converter_options():
 def test_bytes_string_literal():
     assert hx.from_bytes_string(r"b'\xde\xad'").to_hex() == "dead"
     assert hx.from_hex("dead").to_bytes_string() == r"b'\xde\xad'"
-    assert hx.convert(b"\xde", from_=hx.Bytes, to=hx.BytesString) == r"b'\xde'"
+    assert hx.convert(b"\xde", hx.Bytes, hx.BytesString) == r"b'\xde'"
 
 
 def test_odd_hex_left_pads_by_default_and_can_be_strict():
@@ -155,7 +243,7 @@ def test_invalid_byte_array_item_reports_context():
 def test_constructable_hex_and_text_specs():
     assert hx.Hex()("de:ad").hex == "dead"
     assert hx.from_hex("dead").to(hx.Hex(prefix=True, uppercase=True)) == "0xDEAD"
-    assert hx.convert("π", from_=hx.Text(encoding="utf-8"), to=hx.Hex()) == "cf80"
+    assert hx.convert("π", hx.Text(encoding="utf-8"), hx.Hex()) == "cf80"
     assert hx.from_hex("cf80").to(hx.Text(encoding="utf-8")) == "π"
 
 
@@ -174,18 +262,27 @@ def test_pipeline_transforms_pad_reverse_and_group():
     assert (hx.Hex() >> hx.Group(2) >> hx.IntArray())("12345678") == [0x1234, 0x5678]
 
 
+def test_chunk_into_non_chunk_aware_format_is_rejected():
+    with pytest.raises(hx.HexConvError, match="chunking has no effect"):
+        (hx.Hex() >> hx.Chunk(2) >> hx.Hex())("12345678")
+    with pytest.raises(hx.HexConvError, match="chunking has no effect"):
+        (hx.Hex() >> hx.Group(2) >> hx.Text())("12345678")
+    # Chunk-aware targets still accept a grouping width.
+    assert (hx.Hex() >> hx.Chunk(2) >> hx.HexArray())("12345678") == ["1234", "5678"]
+
+
 def test_urlsafe_base64_base32_base85_and_ascii85():
     assert hx.from_bytes(b"\xfb\xff").to(hx.Base64(urlsafe=True, padding=False)) == "-_8"
-    assert hx.convert("-_8", from_=hx.Base64(urlsafe=True, padding=False), to=hx.Hex()) == "fbff"
+    assert hx.convert("-_8", hx.Base64(urlsafe=True, padding=False), hx.Hex()) == "fbff"
 
     assert hx.from_text("data").to(hx.Base32(padding=False)) == "MRQXIYI"
-    assert hx.convert("MRQXIYI", from_=hx.Base32(padding=False), to=hx.Text()) == "data"
+    assert hx.convert("MRQXIYI", hx.Base32(padding=False), hx.Text()) == "data"
 
     base85 = hx.from_text("data").to(hx.Base85())
-    assert hx.convert(base85, from_=hx.Base85(), to=hx.Text()) == "data"
+    assert hx.convert(base85, hx.Base85(), hx.Text()) == "data"
 
     ascii85 = hx.from_text("data").to(hx.Ascii85())
-    assert hx.convert(ascii85, from_=hx.Ascii85(), to=hx.Text()) == "data"
+    assert hx.convert(ascii85, hx.Ascii85(), hx.Text()) == "data"
 
 
 def test_escaped_string_format():
@@ -198,14 +295,14 @@ def test_hexdump_format_round_trip():
     dump = hx.from_hex("deadbeef").to(hx.Hexdump(width=2))
     assert "00000000" in dump
     assert hx.from_hexdump(dump).hex == "deadbeef"
-    assert hx.convert(dump, from_=hx.Hexdump(), to=hx.Hex()) == "deadbeef"
+    assert hx.convert(dump, hx.Hexdump(), hx.Hex()) == "deadbeef"
 
 
 def test_struct_format_pack_and_unpack():
     packed = hx.from_struct((0x1234, 0x5678), fmt=">HH")
     assert packed.hex == "12345678"
     assert packed.to(hx.Struct(">HH")) == (0x1234, 0x5678)
-    assert hx.convert((0x1234, 0x5678), from_=hx.Struct(">HH"), to=hx.Hex()) == "12345678"
+    assert hx.convert((0x1234, 0x5678), hx.Struct(">HH"), hx.Hex()) == "12345678"
     assert hx.Struct(">HH")((0x1234, 0x5678)).hex == "12345678"
     assert (hx.Struct(">HH") >> hx.Hex())((0x1234, 0x5678)) == "12345678"
     assert (hx.Hex() >> hx.Struct(">HH"))("12345678") == (0x1234, 0x5678)

hexconv-0.3.1/tests/test_properties.py

@@ -0,0 +1,99 @@
+"""Property-based round-trip invariants.
+
+For every lossless format, parsing what we emit must reproduce the original
+bytes (or integers). Hypothesis explores edge cases that the example-based
+tests in ``test_hexconv.py`` do not.
+"""
+
+from hypothesis import given
+from hypothesis import strategies as st
+
+import hexconv as hx
+
+
+@given(st.binary(), st.sampled_from(["", " ", ":", "-", "_", ","]))
+def test_hex_round_trip(data, sep):
+    text = hx.from_bytes(data).to_hex(sep=sep)
+    assert hx.from_hex(text).to_bytes() == data
+
+
+@given(st.binary(), st.booleans())
+def test_hex_prefix_and_uppercase_round_trip(data, uppercase):
+    text = hx.from_bytes(data).to_hex(prefix=True, uppercase=uppercase)
+    assert hx.from_hex(text).to_bytes() == data
+
+
+@given(st.binary(), st.booleans(), st.booleans())
+def test_base64_round_trip(data, urlsafe, padding):
+    text = hx.from_bytes(data).to_base64(urlsafe=urlsafe, padding=padding)
+    assert hx.from_base64(text, urlsafe=urlsafe, padding=padding).to_bytes() == data
+
+
+@given(st.binary(), st.booleans())
+def test_base32_round_trip(data, padding):
+    text = hx.from_bytes(data).to_base32(padding=padding)
+    assert hx.from_base32(text, padding=padding).to_bytes() == data
+
+
+@given(st.binary())
+def test_base85_round_trip(data):
+    assert hx.from_base85(hx.from_bytes(data).to_base85()).to_bytes() == data
+
+
+@given(st.binary(), st.booleans())
+def test_ascii85_round_trip(data, adobe):
+    text = hx.from_bytes(data).to_ascii85(adobe=adobe)
+    assert hx.from_ascii85(text, adobe=adobe).to_bytes() == data
+
+
+@given(st.binary(), st.sampled_from(["msb", "lsb"]))
+def test_binary_round_trip(data, bit_order):
+    text = hx.from_bytes(data).to_binary(bit_order=bit_order)
+    assert hx.from_binary(text, bit_order=bit_order).to_bytes() == data
+
+
+@given(st.binary(), st.sampled_from(["msb", "lsb"]))
+def test_bits_round_trip(data, bit_order):
+    bits = hx.from_bytes(data).to_bits(bit_order=bit_order)
+    assert hx.from_bits(bits, bit_order=bit_order).to_bytes() == data
+
+
+@given(st.binary())
+def test_escaped_round_trip(data):
+    assert hx.from_escaped(hx.from_bytes(data).to_escaped()).to_bytes() == data
+
+
+@given(st.binary())
+def test_bytes_string_round_trip(data):
+    text = hx.from_bytes(data).to_bytes_string()
+    assert hx.from_bytes_string(text).to_bytes() == data
+
+
+@given(st.binary())
+def test_bytes_array_round_trip(data):
+    assert hx.from_bytes_array(hx.from_bytes(data).to_bytes_array()).to_bytes() == data
+
+
+@given(st.binary(min_size=1))
+def test_hexdump_round_trip(data):
+    dump = hx.from_bytes(data).to_hexdump()
+    assert hx.from_hexdump(dump).to_bytes() == data
+
+
+@given(st.integers(min_value=0))
+def test_unsigned_int_round_trip(n):
+    assert hx.from_int(n).to_int() == n
+
+
+@given(st.integers())
+def test_signed_int_round_trip(n):
+    assert hx.from_int(n, signed=True).to_int(signed=True) == n
+
+
+@given(
+    st.lists(st.integers(min_value=0, max_value=0xFFFF)),
+    st.sampled_from(["big", "little"]),
+)
+def test_int_array_width2_round_trip(values, endian):
+    packed = hx.from_int_array(values, width=2, endian=endian)
+    assert packed.to_int_array(width=2, endian=endian) == values