hexconv 0.2.1__tar.gz → 0.2.3__tar.gz

{hexconv-0.2.1/src/hexconv.egg-info → hexconv-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexconv
-Version: 0.2.1
+Version: 0.2.3
 Summary: Pythonic conversion toolkit for bytes, hex, integers, arrays, binary strings, base64, and text.
 Author: hexconv contributors
 License-Expression: MIT
@@ -31,18 +31,9 @@ Dynamic: license-file
 
 `hexconv` is a small, dependency-free Python toolkit for converting between
 bytes, hex, integers, arrays, binary strings, base encodings, escaped strings,
-hexdumps, and text.
+hexdumps, structs, bits, and text.
 
-It is designed around a simple idea: build the conversion you mean, then call it.
-
-```python
-import hexconv as hx
-
-decode = hx.HexArray() >> hx.Text()
-
-decode([0x3C, 0x4D, 0x41, 0x47])
-# '<MAG'
-```
+It is built around ergonomic one-liners and composable format objects.
 
 ## Install
 
@@ -50,19 +41,33 @@ decode([0x3C, 0x4D, 0x41, 0x47])
 pip install hexconv
 ```
 
-## The intended interface
+## Quick tour
 
-Use format objects for direct parsing:
+Use direct helpers when you want one obvious conversion:
 
 ```python
-hx.Hex()("dead beef").bytes
+import hexconv as hx
+
+hx.from_hex("dead beef").to_bytes()
 # b'\xde\xad\xbe\xef'
 
-hx.Text()("data").hex
-# '64617461'
+hx.from_hex("dead beef").bytes
+# b'\xde\xad\xbe\xef'
 
-hx.Int(width=4, endian="little")(0x12345678).hex
-# '78563412'
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).to_hex()
+# 'deadbeef'
+
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).hex
+# 'deadbeef'
+
+hx.from_text("data").to_hex_array(prefix=True)
+# ['0x64', '0x61', '0x74', '0x61']
+
+hx.from_int(0xdeadbeef).to_bytes()
+# b'\xde\xad\xbe\xef'
+
+hx.from_int_array([0x1234, 0x5678], width=2).to_hex_array(width=2)
+# ['1234', '5678']
 ```
 
 Use `from_auto` when you want a quick best-effort parse:
@@ -78,19 +83,34 @@ hx.from_auto([0xde, 0xad, 0xbe, 0xef]).to(hx.Hex(prefix=True))
 # '0xdeadbeef'
 ```
 
-Use `>>` to compose reusable converters:
+## Composable interface
+
+`hexconv` is built around small format objects. A format can parse directly:
+
+```python
+hx.Hex()("dead beef").bytes
+# b'\xde\xad\xbe\xef'
+
+hx.Text()("data").hex
+# '64617461'
+
+hx.Int(width=4, endian="little")(0x12345678).hex
+# '78563412'
+```
+
+Formats compose with `>>`:
 
 ```python
 to_text = hx.HexArray() >> hx.Text()
-to_text([0x3C, 0x4D, 0x41, 0x47])
-# '<MAG'
+to_text([0x48, 0x65, 0x6C, 0x6C, 0x6F])
+# 'Hello'
 
 to_hex = hx.Text() >> hx.Hex(prefix=True)
 to_hex("data")
 # '0x64617461'
 ```
 
-Use transforms between formats when the data needs shaping:
+Transforms sit between formats when data needs shaping:
 
 ```python
 words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray(width=2)
@@ -106,7 +126,7 @@ pad_hex("dead")
 # '0000dead'
 ```
 
-Use the builder form when readability matters more than compactness:
+Use the builder form when named steps read better:
 
 ```python
 conv = (
@@ -120,7 +140,28 @@ conv("12345678")
 # ['0x1234', '0x5678']
 ```
 
-## Common conversions
+## Configurable one-shot conversions
+
+Use `convert` when you want an explicit source and target in one expression:
+
+```python
+hx.convert("de ad be ef", hx.Hex(sep=" "), hx.Bytes())
+# b'\xde\xad\xbe\xef'
+
+hx.convert("data", hx.Text(), hx.Hex(prefix=True))
+# '0x64617461'
+
+hx.convert("π", hx.Text(encoding="utf-8"), hx.Hex())
+# 'cf80'
+
+hx.convert("-_8", hx.Base64(urlsafe=True, padding=False), hx.Hex())
+# 'fbff'
+```
+
+Hex strings may include common separators, so you do not need to manually strip
+spaces, colons, dashes, or `0x` prefixes before converting.
+
+## Common conversion patterns
 
 Text, bytes, and hex:
 
@@ -232,6 +273,13 @@ result.value.hex
 # '05'
 ```
 
+## Design priorities
+
+- Easy: obvious conversions stay one-liners.
+- Composable: reusable converters are just `format >> transform >> format`.
+- Flexible: configure endianness, width, padding, grouping, text encoding, and base encodings where needed.
+- Fast and lightweight: no runtime dependencies, bytes-native internals, and direct use of Python's optimized `bytes`, `int`, `base64`, and `struct` primitives.
+
 ## Format objects
 
 Format objects are both parsers and pipeline endpoints.

{hexconv-0.2.1 → hexconv-0.2.3}/README.md

@@ -2,18 +2,9 @@
 
 `hexconv` is a small, dependency-free Python toolkit for converting between
 bytes, hex, integers, arrays, binary strings, base encodings, escaped strings,
-hexdumps, and text.
+hexdumps, structs, bits, and text.
 
-It is designed around a simple idea: build the conversion you mean, then call it.
-
-```python
-import hexconv as hx
-
-decode = hx.HexArray() >> hx.Text()
-
-decode([0x3C, 0x4D, 0x41, 0x47])
-# '<MAG'
-```
+It is built around ergonomic one-liners and composable format objects.
 
 ## Install
 
@@ -21,19 +12,33 @@ decode([0x3C, 0x4D, 0x41, 0x47])
 pip install hexconv
 ```
 
-## The intended interface
+## Quick tour
 
-Use format objects for direct parsing:
+Use direct helpers when you want one obvious conversion:
 
 ```python
-hx.Hex()("dead beef").bytes
+import hexconv as hx
+
+hx.from_hex("dead beef").to_bytes()
 # b'\xde\xad\xbe\xef'
 
-hx.Text()("data").hex
-# '64617461'
+hx.from_hex("dead beef").bytes
+# b'\xde\xad\xbe\xef'
 
-hx.Int(width=4, endian="little")(0x12345678).hex
-# '78563412'
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).to_hex()
+# 'deadbeef'
+
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).hex
+# 'deadbeef'
+
+hx.from_text("data").to_hex_array(prefix=True)
+# ['0x64', '0x61', '0x74', '0x61']
+
+hx.from_int(0xdeadbeef).to_bytes()
+# b'\xde\xad\xbe\xef'
+
+hx.from_int_array([0x1234, 0x5678], width=2).to_hex_array(width=2)
+# ['1234', '5678']
 ```
 
 Use `from_auto` when you want a quick best-effort parse:
@@ -49,19 +54,34 @@ hx.from_auto([0xde, 0xad, 0xbe, 0xef]).to(hx.Hex(prefix=True))
 # '0xdeadbeef'
 ```
 
-Use `>>` to compose reusable converters:
+## Composable interface
+
+`hexconv` is built around small format objects. A format can parse directly:
+
+```python
+hx.Hex()("dead beef").bytes
+# b'\xde\xad\xbe\xef'
+
+hx.Text()("data").hex
+# '64617461'
+
+hx.Int(width=4, endian="little")(0x12345678).hex
+# '78563412'
+```
+
+Formats compose with `>>`:
 
 ```python
 to_text = hx.HexArray() >> hx.Text()
-to_text([0x3C, 0x4D, 0x41, 0x47])
-# '<MAG'
+to_text([0x48, 0x65, 0x6C, 0x6C, 0x6F])
+# 'Hello'
 
 to_hex = hx.Text() >> hx.Hex(prefix=True)
 to_hex("data")
 # '0x64617461'
 ```
 
-Use transforms between formats when the data needs shaping:
+Transforms sit between formats when data needs shaping:
 
 ```python
 words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray(width=2)
@@ -77,7 +97,7 @@ pad_hex("dead")
 # '0000dead'
 ```
 
-Use the builder form when readability matters more than compactness:
+Use the builder form when named steps read better:
 
 ```python
 conv = (
@@ -91,7 +111,28 @@ conv("12345678")
 # ['0x1234', '0x5678']
 ```
 
-## Common conversions
+## Configurable one-shot conversions
+
+Use `convert` when you want an explicit source and target in one expression:
+
+```python
+hx.convert("de ad be ef", hx.Hex(sep=" "), hx.Bytes())
+# b'\xde\xad\xbe\xef'
+
+hx.convert("data", hx.Text(), hx.Hex(prefix=True))
+# '0x64617461'
+
+hx.convert("π", hx.Text(encoding="utf-8"), hx.Hex())
+# 'cf80'
+
+hx.convert("-_8", hx.Base64(urlsafe=True, padding=False), hx.Hex())
+# 'fbff'
+```
+
+Hex strings may include common separators, so you do not need to manually strip
+spaces, colons, dashes, or `0x` prefixes before converting.
+
+## Common conversion patterns
 
 Text, bytes, and hex:
 
@@ -203,6 +244,13 @@ result.value.hex
 # '05'
 ```
 
+## Design priorities
+
+- Easy: obvious conversions stay one-liners.
+- Composable: reusable converters are just `format >> transform >> format`.
+- Flexible: configure endianness, width, padding, grouping, text encoding, and base encodings where needed.
+- Fast and lightweight: no runtime dependencies, bytes-native internals, and direct use of Python's optimized `bytes`, `int`, `base64`, and `struct` primitives.
+
 ## Format objects
 
 Format objects are both parsers and pipeline endpoints.

{hexconv-0.2.1 → hexconv-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hexconv"
-version = "0.2.1"
+version = "0.2.3"
 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"

{hexconv-0.2.1 → hexconv-0.2.3}/src/hexconv/_core.py

@@ -999,17 +999,34 @@ class Converter:
 
 def convert(
     value: Any,
+    from_format: FormatLike | None = None,
+    to_format: FormatLike | None = None,
     *,
-    from_: FormatLike = Auto,
-    to: FormatLike = Bytes,
+    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."""
+    """One-shot conversion between explicit formats.
+
+    Preferred:
+        convert(value, Hex(), Bytes())
+
+    Backward-compatible:
+        convert(value, from_=Hex(), to=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(
-        from_,
-        to,
+        Auto if input_format is None else input_format,
+        Bytes if output_format is None else output_format,
         input_options=input_options,
         output_options=output_options,
     )(value)

{hexconv-0.2.1 → hexconv-0.2.3/src/hexconv.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexconv
-Version: 0.2.1
+Version: 0.2.3
 Summary: Pythonic conversion toolkit for bytes, hex, integers, arrays, binary strings, base64, and text.
 Author: hexconv contributors
 License-Expression: MIT
@@ -31,18 +31,9 @@ Dynamic: license-file
 
 `hexconv` is a small, dependency-free Python toolkit for converting between
 bytes, hex, integers, arrays, binary strings, base encodings, escaped strings,
-hexdumps, and text.
+hexdumps, structs, bits, and text.
 
-It is designed around a simple idea: build the conversion you mean, then call it.
-
-```python
-import hexconv as hx
-
-decode = hx.HexArray() >> hx.Text()
-
-decode([0x3C, 0x4D, 0x41, 0x47])
-# '<MAG'
-```
+It is built around ergonomic one-liners and composable format objects.
 
 ## Install
 
@@ -50,19 +41,33 @@ decode([0x3C, 0x4D, 0x41, 0x47])
 pip install hexconv
 ```
 
-## The intended interface
+## Quick tour
 
-Use format objects for direct parsing:
+Use direct helpers when you want one obvious conversion:
 
 ```python
-hx.Hex()("dead beef").bytes
+import hexconv as hx
+
+hx.from_hex("dead beef").to_bytes()
 # b'\xde\xad\xbe\xef'
 
-hx.Text()("data").hex
-# '64617461'
+hx.from_hex("dead beef").bytes
+# b'\xde\xad\xbe\xef'
 
-hx.Int(width=4, endian="little")(0x12345678).hex
-# '78563412'
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).to_hex()
+# 'deadbeef'
+
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).hex
+# 'deadbeef'
+
+hx.from_text("data").to_hex_array(prefix=True)
+# ['0x64', '0x61', '0x74', '0x61']
+
+hx.from_int(0xdeadbeef).to_bytes()
+# b'\xde\xad\xbe\xef'
+
+hx.from_int_array([0x1234, 0x5678], width=2).to_hex_array(width=2)
+# ['1234', '5678']
 ```
 
 Use `from_auto` when you want a quick best-effort parse:
@@ -78,19 +83,34 @@ hx.from_auto([0xde, 0xad, 0xbe, 0xef]).to(hx.Hex(prefix=True))
 # '0xdeadbeef'
 ```
 
-Use `>>` to compose reusable converters:
+## Composable interface
+
+`hexconv` is built around small format objects. A format can parse directly:
+
+```python
+hx.Hex()("dead beef").bytes
+# b'\xde\xad\xbe\xef'
+
+hx.Text()("data").hex
+# '64617461'
+
+hx.Int(width=4, endian="little")(0x12345678).hex
+# '78563412'
+```
+
+Formats compose with `>>`:
 
 ```python
 to_text = hx.HexArray() >> hx.Text()
-to_text([0x3C, 0x4D, 0x41, 0x47])
-# '<MAG'
+to_text([0x48, 0x65, 0x6C, 0x6C, 0x6F])
+# 'Hello'
 
 to_hex = hx.Text() >> hx.Hex(prefix=True)
 to_hex("data")
 # '0x64617461'
 ```
 
-Use transforms between formats when the data needs shaping:
+Transforms sit between formats when data needs shaping:
 
 ```python
 words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray(width=2)
@@ -106,7 +126,7 @@ pad_hex("dead")
 # '0000dead'
 ```
 
-Use the builder form when readability matters more than compactness:
+Use the builder form when named steps read better:
 
 ```python
 conv = (
@@ -120,7 +140,28 @@ conv("12345678")
 # ['0x1234', '0x5678']
 ```
 
-## Common conversions
+## Configurable one-shot conversions
+
+Use `convert` when you want an explicit source and target in one expression:
+
+```python
+hx.convert("de ad be ef", hx.Hex(sep=" "), hx.Bytes())
+# b'\xde\xad\xbe\xef'
+
+hx.convert("data", hx.Text(), hx.Hex(prefix=True))
+# '0x64617461'
+
+hx.convert("π", hx.Text(encoding="utf-8"), hx.Hex())
+# 'cf80'
+
+hx.convert("-_8", hx.Base64(urlsafe=True, padding=False), hx.Hex())
+# 'fbff'
+```
+
+Hex strings may include common separators, so you do not need to manually strip
+spaces, colons, dashes, or `0x` prefixes before converting.
+
+## Common conversion patterns
 
 Text, bytes, and hex:
 
@@ -232,6 +273,13 @@ result.value.hex
 # '05'
 ```
 
+## Design priorities
+
+- Easy: obvious conversions stay one-liners.
+- Composable: reusable converters are just `format >> transform >> format`.
+- Flexible: configure endianness, width, padding, grouping, text encoding, and base encodings where needed.
+- Fast and lightweight: no runtime dependencies, bytes-native internals, and direct use of Python's optimized `bytes`, `int`, `base64`, and `struct` primitives.
+
 ## Format objects
 
 Format objects are both parsers and pipeline endpoints.

{hexconv-0.2.1 → hexconv-0.2.3}/tests/test_hexconv.py

@@ -45,6 +45,15 @@ 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("de ad be ef", hx.Hex(sep=" "), hx.Bytes()) == b"\xde\xad\xbe\xef"
+    assert hx.convert("data", hx.Text(), hx.Hex(prefix=True)) == "0x64617461"
+
+
+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())
 
 
 def test_converter_options():