hexconv 0.2.2__tar.gz → 0.2.4__tar.gz

{hexconv-0.2.2/src/hexconv.egg-info → hexconv-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexconv
-Version: 0.2.2
+Version: 0.2.4
 Summary: Pythonic conversion toolkit for bytes, hex, integers, arrays, binary strings, base64, and text.
 Author: hexconv contributors
 License-Expression: MIT
@@ -31,38 +31,77 @@ 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.
+It is built around ergonomic one-liners and composable format objects.
+
+## Install
+
+```bash
+pip install hexconv
+```
+
+## Fast compose
+
+The intended interface is small pieces snapped together:
+`source format >> optional transforms >> target format`.
 
 ```python
 import hexconv as hx
 
-decode = hx.HexArray() >> hx.Text()
+to_bytes = hx.Hex() >> hx.Bytes()
+to_bytes("de ad be ef")
+# b'\xde\xad\xbe\xef'
 
-decode([0x48, 0x65, 0x6C, 0x6C, 0x6F])
-# 'Hello'
-```
+spaced_hex = hx.Bytes() >> hx.Hex(sep=" ")
+spaced_hex(b"\xde\xad\xbe\xef")
+# 'de ad be ef'
 
-## Install
+words = hx.Hex(sep=" ") >> hx.Chunk(2) >> hx.IntArray(width=2)
+words("12 34 56 78")
+# [4660, 22136]
 
-```bash
-pip install hexconv
+text_to_urlsafe = hx.Text() >> hx.Base64(urlsafe=True, padding=False)
+text_to_urlsafe("data")
+# 'ZGF0YQ'
 ```
 
-## The intended interface
+Hex input accepts common separators, so spaced or copied hex usually does not
+need manual cleanup before conversion. `Hex(sep=" ")` is also how you emit
+space-separated hex.
 
-Use format objects for direct parsing:
+## Quick tour
+
+Use direct helpers when you want one obvious conversion across many
+representations:
 
 ```python
-hx.Hex()("dead beef").bytes
+hx.from_hex("de ad be ef").bytes
 # b'\xde\xad\xbe\xef'
 
-hx.Text()("data").hex
-# '64617461'
+hx.from_text("data").to_hex_array(prefix=True)
+# ['0x64', '0x61', '0x74', '0x61']
 
-hx.Int(width=4, endian="little")(0x12345678).hex
-# '78563412'
+hx.from_int(0xdeadbeef).bytes
+# b'\xde\xad\xbe\xef'
+
+hx.from_int_array([0x1234, 0x5678], width=2).to_hex_array(width=2)
+# ['1234', '5678']
+
+hx.from_binary("01100100 01100001 01110100 01100001").text
+# 'data'
+
+hx.from_base64("ZGF0YQ==").text
+# 'data'
+
+hx.from_escaped(r"\xde\xad").hex
+# 'dead'
+
+hx.from_struct((0x1234, 0x5678), fmt=">HH").hex
+# '12345678'
+
+hx.from_bits("101", pad=True).hex
+# '05'
 ```
 
 Use `from_auto` when you want a quick best-effort parse:
@@ -78,7 +117,22 @@ 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()("de ad be ef").bytes
+# b'\xde\xad\xbe\xef'
+
+hx.Text()("data").hex
+# '64617461'
+
+hx.Int(width=4, endian="little")(0x12345678).hex
+# '78563412'
+```
+
+Formats compose with `>>`, so reusable converters are normal Python objects:
 
 ```python
 to_text = hx.HexArray() >> hx.Text()
@@ -90,7 +144,7 @@ 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 +160,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 +174,31 @@ 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(b"\xde\xad\xbe\xef", hx.Bytes(), hx.Hex(sep=" "))
+# 'de ad be ef'
+
+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 +310,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.2 → hexconv-0.2.4}/README.md

@@ -2,38 +2,77 @@
 
 `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.
+It is built around ergonomic one-liners and composable format objects.
+
+## Install
+
+```bash
+pip install hexconv
+```
+
+## Fast compose
+
+The intended interface is small pieces snapped together:
+`source format >> optional transforms >> target format`.
 
 ```python
 import hexconv as hx
 
-decode = hx.HexArray() >> hx.Text()
+to_bytes = hx.Hex() >> hx.Bytes()
+to_bytes("de ad be ef")
+# b'\xde\xad\xbe\xef'
 
-decode([0x48, 0x65, 0x6C, 0x6C, 0x6F])
-# 'Hello'
-```
+spaced_hex = hx.Bytes() >> hx.Hex(sep=" ")
+spaced_hex(b"\xde\xad\xbe\xef")
+# 'de ad be ef'
 
-## Install
+words = hx.Hex(sep=" ") >> hx.Chunk(2) >> hx.IntArray(width=2)
+words("12 34 56 78")
+# [4660, 22136]
 
-```bash
-pip install hexconv
+text_to_urlsafe = hx.Text() >> hx.Base64(urlsafe=True, padding=False)
+text_to_urlsafe("data")
+# 'ZGF0YQ'
 ```
 
-## The intended interface
+Hex input accepts common separators, so spaced or copied hex usually does not
+need manual cleanup before conversion. `Hex(sep=" ")` is also how you emit
+space-separated hex.
 
-Use format objects for direct parsing:
+## Quick tour
+
+Use direct helpers when you want one obvious conversion across many
+representations:
 
 ```python
-hx.Hex()("dead beef").bytes
+hx.from_hex("de ad be ef").bytes
 # b'\xde\xad\xbe\xef'
 
-hx.Text()("data").hex
-# '64617461'
+hx.from_text("data").to_hex_array(prefix=True)
+# ['0x64', '0x61', '0x74', '0x61']
 
-hx.Int(width=4, endian="little")(0x12345678).hex
-# '78563412'
+hx.from_int(0xdeadbeef).bytes
+# b'\xde\xad\xbe\xef'
+
+hx.from_int_array([0x1234, 0x5678], width=2).to_hex_array(width=2)
+# ['1234', '5678']
+
+hx.from_binary("01100100 01100001 01110100 01100001").text
+# 'data'
+
+hx.from_base64("ZGF0YQ==").text
+# 'data'
+
+hx.from_escaped(r"\xde\xad").hex
+# 'dead'
+
+hx.from_struct((0x1234, 0x5678), fmt=">HH").hex
+# '12345678'
+
+hx.from_bits("101", pad=True).hex
+# '05'
 ```
 
 Use `from_auto` when you want a quick best-effort parse:
@@ -49,7 +88,22 @@ 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()("de ad be ef").bytes
+# b'\xde\xad\xbe\xef'
+
+hx.Text()("data").hex
+# '64617461'
+
+hx.Int(width=4, endian="little")(0x12345678).hex
+# '78563412'
+```
+
+Formats compose with `>>`, so reusable converters are normal Python objects:
 
 ```python
 to_text = hx.HexArray() >> hx.Text()
@@ -61,7 +115,7 @@ 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 +131,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 +145,31 @@ 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(b"\xde\xad\xbe\xef", hx.Bytes(), hx.Hex(sep=" "))
+# 'de ad be ef'
+
+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 +281,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.2 → hexconv-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hexconv"
-version = "0.2.2"
+version = "0.2.4"
 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.2 → hexconv-0.2.4}/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.2 → hexconv-0.2.4/src/hexconv.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexconv
-Version: 0.2.2
+Version: 0.2.4
 Summary: Pythonic conversion toolkit for bytes, hex, integers, arrays, binary strings, base64, and text.
 Author: hexconv contributors
 License-Expression: MIT
@@ -31,38 +31,77 @@ 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.
+It is built around ergonomic one-liners and composable format objects.
+
+## Install
+
+```bash
+pip install hexconv
+```
+
+## Fast compose
+
+The intended interface is small pieces snapped together:
+`source format >> optional transforms >> target format`.
 
 ```python
 import hexconv as hx
 
-decode = hx.HexArray() >> hx.Text()
+to_bytes = hx.Hex() >> hx.Bytes()
+to_bytes("de ad be ef")
+# b'\xde\xad\xbe\xef'
 
-decode([0x48, 0x65, 0x6C, 0x6C, 0x6F])
-# 'Hello'
-```
+spaced_hex = hx.Bytes() >> hx.Hex(sep=" ")
+spaced_hex(b"\xde\xad\xbe\xef")
+# 'de ad be ef'
 
-## Install
+words = hx.Hex(sep=" ") >> hx.Chunk(2) >> hx.IntArray(width=2)
+words("12 34 56 78")
+# [4660, 22136]
 
-```bash
-pip install hexconv
+text_to_urlsafe = hx.Text() >> hx.Base64(urlsafe=True, padding=False)
+text_to_urlsafe("data")
+# 'ZGF0YQ'
 ```
 
-## The intended interface
+Hex input accepts common separators, so spaced or copied hex usually does not
+need manual cleanup before conversion. `Hex(sep=" ")` is also how you emit
+space-separated hex.
 
-Use format objects for direct parsing:
+## Quick tour
+
+Use direct helpers when you want one obvious conversion across many
+representations:
 
 ```python
-hx.Hex()("dead beef").bytes
+hx.from_hex("de ad be ef").bytes
 # b'\xde\xad\xbe\xef'
 
-hx.Text()("data").hex
-# '64617461'
+hx.from_text("data").to_hex_array(prefix=True)
+# ['0x64', '0x61', '0x74', '0x61']
 
-hx.Int(width=4, endian="little")(0x12345678).hex
-# '78563412'
+hx.from_int(0xdeadbeef).bytes
+# b'\xde\xad\xbe\xef'
+
+hx.from_int_array([0x1234, 0x5678], width=2).to_hex_array(width=2)
+# ['1234', '5678']
+
+hx.from_binary("01100100 01100001 01110100 01100001").text
+# 'data'
+
+hx.from_base64("ZGF0YQ==").text
+# 'data'
+
+hx.from_escaped(r"\xde\xad").hex
+# 'dead'
+
+hx.from_struct((0x1234, 0x5678), fmt=">HH").hex
+# '12345678'
+
+hx.from_bits("101", pad=True).hex
+# '05'
 ```
 
 Use `from_auto` when you want a quick best-effort parse:
@@ -78,7 +117,22 @@ 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()("de ad be ef").bytes
+# b'\xde\xad\xbe\xef'
+
+hx.Text()("data").hex
+# '64617461'
+
+hx.Int(width=4, endian="little")(0x12345678).hex
+# '78563412'
+```
+
+Formats compose with `>>`, so reusable converters are normal Python objects:
 
 ```python
 to_text = hx.HexArray() >> hx.Text()
@@ -90,7 +144,7 @@ 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 +160,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 +174,31 @@ 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(b"\xde\xad\xbe\xef", hx.Bytes(), hx.Hex(sep=" "))
+# 'de ad be ef'
+
+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 +310,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.2 → hexconv-0.2.4}/tests/test_hexconv.py

@@ -45,6 +45,16 @@ 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(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_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():