hexconv 0.2.3__tar.gz → 0.2.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexconv
-Version: 0.2.3
+Version: 0.2.5
 Summary: Pythonic conversion toolkit for bytes, hex, integers, arrays, binary strings, base64, and text.
 Author: hexconv contributors
 License-Expression: MIT
@@ -41,64 +41,99 @@ It is built around ergonomic one-liners and composable format objects.
 pip install hexconv
 ```
 
-## Quick tour
+## Simple usage
 
-Use direct helpers when you want one obvious conversion:
+Most conversions are one-liners. Use `from_auto` when you want a quick
+best-effort parse, or pick an explicit helper when the input is ambiguous.
 
 ```python
 import hexconv as hx
 
-hx.from_hex("dead beef").to_bytes()
-# b'\xde\xad\xbe\xef'
+hx.from_auto("0x64617461").text
+# 'data'
 
-hx.from_hex("dead beef").bytes
-# b'\xde\xad\xbe\xef'
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).int
+# 3735928559
 
-hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).to_hex()
-# 'deadbeef'
+hx.from_text("data").hex
+# '64617461'
+```
 
-hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).hex
-# 'deadbeef'
+## Fast compose
 
-hx.from_text("data").to_hex_array(prefix=True)
-# ['0x64', '0x61', '0x74', '0x61']
+Create your own converters by snapping together
+`source format >> optional transforms >> target format`.
 
-hx.from_int(0xdeadbeef).to_bytes()
-# b'\xde\xad\xbe\xef'
+```python
+to_bytes = hx.Hex() >> hx.Bytes()
+to_bytes("68 69")
+# b'hi'
 
-hx.from_int_array([0x1234, 0x5678], width=2).to_hex_array(width=2)
-# ['1234', '5678']
+spaced_hex = hx.Bytes() >> hx.Hex(sep=" ")
+spaced_hex(b"data")
+# '64 61 74 61'
+
+words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray()
+words("12 34 56 78")
+# [4660, 22136]
+
+pack_to_hex = hx.Struct(">HH") >> hx.Hex()
+pack_to_hex((0x1234, 0x5678))
+# '12345678'
 ```
 
-Use `from_auto` when you want a quick best-effort parse:
+## Configure when needed
+
+Formats work bare by default. Add arguments only for the conversion that needs
+them:
 
 ```python
-hx.from_auto("0xdeadbeef").bytes
+hx.convert("de ad be ef", hx.Hex(), hx.Bytes())
 # b'\xde\xad\xbe\xef'
 
-hx.from_auto(b"\xde\xad").hex
-# 'dead'
+hx.convert(b"\xde\xad\xbe\xef", hx.Bytes(), hx.Hex(sep=" ", prefix=True, uppercase=True))
+# '0xDE AD BE EF'
+
+hx.convert("π", hx.Text(encoding="utf-8"), hx.Hex())
+# 'cf80'
 
-hx.from_auto([0xde, 0xad, 0xbe, 0xef]).to(hx.Hex(prefix=True))
-# '0xdeadbeef'
+hx.from_int(0x12345678, endian="little").hex
+# '78563412'
+
+hx.convert("ZGF0YQ", hx.Base64(padding=False), hx.Text())
+# 'data'
+
+hx.from_binary("00010110 10010110", bit_order="lsb").text
+# 'hi'
 ```
 
-## Composable interface
+Hex strings may include common separators, so you do not need to manually strip
+spaces, colons, dashes, or `0x` prefixes before converting. `Hex(sep=" ")` is
+how you emit space-separated hex.
+
+## Full pipeline guide
 
 `hexconv` is built around small format objects. A format can parse directly:
 
 ```python
-hx.Hex()("dead beef").bytes
+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
+hx.Int(endian="little")(0x12345678).hex
 # '78563412'
+
+pack_words = hx.Struct(">HH")
+pack_words((0x1234, 0x5678)).hex
+# '12345678'
+
+hx.Hex()("12345678").to(pack_words)
+# (4660, 22136)
 ```
 
-Formats compose with `>>`:
+Formats compose with `>>`, so reusable converters are normal Python objects:
 
 ```python
 to_text = hx.HexArray() >> hx.Text()
@@ -108,12 +143,20 @@ to_text([0x48, 0x65, 0x6C, 0x6C, 0x6F])
 to_hex = hx.Text() >> hx.Hex(prefix=True)
 to_hex("data")
 # '0x64617461'
+
+pack_to_hex = hx.Struct(">HH") >> hx.Hex()
+pack_to_hex((0x1234, 0x5678))
+# '12345678'
+
+unpack_from_hex = hx.Hex() >> hx.Struct(">HH")
+unpack_from_hex("12345678")
+# (4660, 22136)
 ```
 
 Transforms sit between formats when data needs shaping:
 
 ```python
-words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray(width=2)
+words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray()
 words("12345678")
 # [4660, 22136]
 
@@ -140,30 +183,7 @@ conv("12345678")
 # ['0x1234', '0x5678']
 ```
 
-## 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:
+More conversion patterns:
 
 ```python
 hx.Text()("hello").bytes
@@ -172,54 +192,24 @@ hx.Text()("hello").bytes
 hx.Hex()("68656c6c6f").text
 # 'hello'
 
-hx.BytesArray()([0x68, 0x69]).to(hx.Text())
-# 'hi'
-```
+hx.BytesArray()([0x4F, 0x4B]).to(hx.Text())
+# 'OK'
 
-Integer packing:
-
-```python
-hx.Int(width=2)(0x1234).hex
-# '1234'
-
-hx.Int(width=2, endian="little")(0x1234).hex
+hx.Int(endian="little")(0x1234).hex
 # '3412'
 
-(hx.Hex() >> hx.Chunk(2) >> hx.IntArray(width=2))("12345678")
-# [4660, 22136]
-```
-
-Base encodings:
-
-```python
-hx.Text()("data").to(hx.Base64())
-# 'ZGF0YQ=='
-
 hx.Text()("data").to(hx.Base32(padding=False))
 # 'MRQXIYI'
 
-hx.Base64(urlsafe=True, padding=False)("-_8").hex
-# 'fbff'
-```
-
-Escaped strings, hexdumps, structs, and bits:
-
-```python
-hx.Escaped()(r"\xde\xad").hex
-# 'dead'
-
-dump = hx.Hex()("deadbeef").to(hx.Hexdump(width=2))
-hx.Hexdump()(dump).hex
-# 'deadbeef'
-
-hx.Struct(">HH")((0x1234, 0x5678)).hex
-# '12345678'
+dump = hx.Text()("data").to(hx.Hexdump(width=2))
+hx.Hexdump()(dump).text
+# 'data'
 
 hx.Hex()("12345678").to(hx.Struct(">HH"))
 # (4660, 22136)
 
-hx.Bits()([1, 0, 1]).hex
-# '05'
+hx.Bits()("0100111101001011").text
+# 'OK'
 ```
 
 ## Why explicit formats?
@@ -267,10 +257,10 @@ result.reason
 `from_auto(..., explain=True)` returns the same explanation object:
 
 ```python
-result = hx.from_auto("0b101", explain=True)
+result = hx.from_auto("0b0100111101001011", explain=True)
 
-result.value.hex
-# '05'
+result.value.text
+# 'OK'
 ```
 
 ## Design priorities
@@ -294,7 +284,7 @@ conv("deadbeef")
 # 3735928559
 ```
 
-Available format specs:
+Available format specs all work in their simplest bare form:
 
 - `Bytes()`
 - `BytesArray()`
@@ -302,8 +292,8 @@ Available format specs:
 - `Hex()`
 - `HexArray()`
 - `HexInt()` / `LargeHexNumber()`
-- `Int()`
-- `IntArray()`
+- `Int()` / `DecimalInt()`
+- `IntArray()` / `DecimalIntArray()`
 - `Text()`
 - `Binary()`
 - `Base64()`
@@ -314,6 +304,20 @@ Available format specs:
 - `Hexdump()`
 - `Struct(fmt)`
 - `Bits()`
+- `Auto()`
+
+Add options only when you need control over formatting or parsing:
+
+- Display: `Hex(sep=" ", prefix=True, uppercase=True)`, `HexArray(width=2)`.
+- Integer packing: `Int(width=4)`, `Int(endian="little")`, `IntArray(width=2)`.
+- Text: `Text(encoding="utf-8", errors="replace")`.
+- Base encodings: `Base64(urlsafe=True, padding=False)`, `Base32(padding=False)`.
+- Binary/bits: `Binary(sep=" ", prefix=True, bit_order="lsb")`, `Bits(pad_side="right")`.
+- Dumps/escapes/structs: `Hexdump(width=8)`, `Escaped(uppercase=True)`, `Struct(">HH")`.
+
+Some options only matter in one direction. For example, `Hex(sep=" ")`
+controls hex output formatting, while hex input already accepts common
+separators such as spaces, colons, dashes, underscores, and `0x` prefixes.
 
 ## Transforms
 
@@ -321,7 +325,7 @@ Transforms are byte-to-byte steps that sit between input and output formats.
 
 ```python
 hx.Hex() >> hx.Chunk(2) >> hx.HexArray()
-hx.Hex() >> hx.Group(2) >> hx.IntArray(width=2)
+hx.Hex() >> hx.Group(2) >> hx.IntArray()
 hx.Hex() >> hx.Pad.left(width=8) >> hx.Hex()
 hx.Hex() >> hx.Pad.right(block_size=8, byte=0xFF) >> hx.Hex()
 hx.Hex() >> hx.Reverse() >> hx.Hex()

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

@@ -12,64 +12,99 @@ It is built around ergonomic one-liners and composable format objects.
 pip install hexconv
 ```
 
-## Quick tour
+## Simple usage
 
-Use direct helpers when you want one obvious conversion:
+Most conversions are one-liners. Use `from_auto` when you want a quick
+best-effort parse, or pick an explicit helper when the input is ambiguous.
 
 ```python
 import hexconv as hx
 
-hx.from_hex("dead beef").to_bytes()
-# b'\xde\xad\xbe\xef'
+hx.from_auto("0x64617461").text
+# 'data'
 
-hx.from_hex("dead beef").bytes
-# b'\xde\xad\xbe\xef'
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).int
+# 3735928559
 
-hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).to_hex()
-# 'deadbeef'
+hx.from_text("data").hex
+# '64617461'
+```
 
-hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).hex
-# 'deadbeef'
+## Fast compose
 
-hx.from_text("data").to_hex_array(prefix=True)
-# ['0x64', '0x61', '0x74', '0x61']
+Create your own converters by snapping together
+`source format >> optional transforms >> target format`.
 
-hx.from_int(0xdeadbeef).to_bytes()
-# b'\xde\xad\xbe\xef'
+```python
+to_bytes = hx.Hex() >> hx.Bytes()
+to_bytes("68 69")
+# b'hi'
 
-hx.from_int_array([0x1234, 0x5678], width=2).to_hex_array(width=2)
-# ['1234', '5678']
+spaced_hex = hx.Bytes() >> hx.Hex(sep=" ")
+spaced_hex(b"data")
+# '64 61 74 61'
+
+words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray()
+words("12 34 56 78")
+# [4660, 22136]
+
+pack_to_hex = hx.Struct(">HH") >> hx.Hex()
+pack_to_hex((0x1234, 0x5678))
+# '12345678'
 ```
 
-Use `from_auto` when you want a quick best-effort parse:
+## Configure when needed
+
+Formats work bare by default. Add arguments only for the conversion that needs
+them:
 
 ```python
-hx.from_auto("0xdeadbeef").bytes
+hx.convert("de ad be ef", hx.Hex(), hx.Bytes())
 # b'\xde\xad\xbe\xef'
 
-hx.from_auto(b"\xde\xad").hex
-# 'dead'
+hx.convert(b"\xde\xad\xbe\xef", hx.Bytes(), hx.Hex(sep=" ", prefix=True, uppercase=True))
+# '0xDE AD BE EF'
+
+hx.convert("π", hx.Text(encoding="utf-8"), hx.Hex())
+# 'cf80'
 
-hx.from_auto([0xde, 0xad, 0xbe, 0xef]).to(hx.Hex(prefix=True))
-# '0xdeadbeef'
+hx.from_int(0x12345678, endian="little").hex
+# '78563412'
+
+hx.convert("ZGF0YQ", hx.Base64(padding=False), hx.Text())
+# 'data'
+
+hx.from_binary("00010110 10010110", bit_order="lsb").text
+# 'hi'
 ```
 
-## Composable interface
+Hex strings may include common separators, so you do not need to manually strip
+spaces, colons, dashes, or `0x` prefixes before converting. `Hex(sep=" ")` is
+how you emit space-separated hex.
+
+## Full pipeline guide
 
 `hexconv` is built around small format objects. A format can parse directly:
 
 ```python
-hx.Hex()("dead beef").bytes
+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
+hx.Int(endian="little")(0x12345678).hex
 # '78563412'
+
+pack_words = hx.Struct(">HH")
+pack_words((0x1234, 0x5678)).hex
+# '12345678'
+
+hx.Hex()("12345678").to(pack_words)
+# (4660, 22136)
 ```
 
-Formats compose with `>>`:
+Formats compose with `>>`, so reusable converters are normal Python objects:
 
 ```python
 to_text = hx.HexArray() >> hx.Text()
@@ -79,12 +114,20 @@ to_text([0x48, 0x65, 0x6C, 0x6C, 0x6F])
 to_hex = hx.Text() >> hx.Hex(prefix=True)
 to_hex("data")
 # '0x64617461'
+
+pack_to_hex = hx.Struct(">HH") >> hx.Hex()
+pack_to_hex((0x1234, 0x5678))
+# '12345678'
+
+unpack_from_hex = hx.Hex() >> hx.Struct(">HH")
+unpack_from_hex("12345678")
+# (4660, 22136)
 ```
 
 Transforms sit between formats when data needs shaping:
 
 ```python
-words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray(width=2)
+words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray()
 words("12345678")
 # [4660, 22136]
 
@@ -111,30 +154,7 @@ conv("12345678")
 # ['0x1234', '0x5678']
 ```
 
-## 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:
+More conversion patterns:
 
 ```python
 hx.Text()("hello").bytes
@@ -143,54 +163,24 @@ hx.Text()("hello").bytes
 hx.Hex()("68656c6c6f").text
 # 'hello'
 
-hx.BytesArray()([0x68, 0x69]).to(hx.Text())
-# 'hi'
-```
+hx.BytesArray()([0x4F, 0x4B]).to(hx.Text())
+# 'OK'
 
-Integer packing:
-
-```python
-hx.Int(width=2)(0x1234).hex
-# '1234'
-
-hx.Int(width=2, endian="little")(0x1234).hex
+hx.Int(endian="little")(0x1234).hex
 # '3412'
 
-(hx.Hex() >> hx.Chunk(2) >> hx.IntArray(width=2))("12345678")
-# [4660, 22136]
-```
-
-Base encodings:
-
-```python
-hx.Text()("data").to(hx.Base64())
-# 'ZGF0YQ=='
-
 hx.Text()("data").to(hx.Base32(padding=False))
 # 'MRQXIYI'
 
-hx.Base64(urlsafe=True, padding=False)("-_8").hex
-# 'fbff'
-```
-
-Escaped strings, hexdumps, structs, and bits:
-
-```python
-hx.Escaped()(r"\xde\xad").hex
-# 'dead'
-
-dump = hx.Hex()("deadbeef").to(hx.Hexdump(width=2))
-hx.Hexdump()(dump).hex
-# 'deadbeef'
-
-hx.Struct(">HH")((0x1234, 0x5678)).hex
-# '12345678'
+dump = hx.Text()("data").to(hx.Hexdump(width=2))
+hx.Hexdump()(dump).text
+# 'data'
 
 hx.Hex()("12345678").to(hx.Struct(">HH"))
 # (4660, 22136)
 
-hx.Bits()([1, 0, 1]).hex
-# '05'
+hx.Bits()("0100111101001011").text
+# 'OK'
 ```
 
 ## Why explicit formats?
@@ -238,10 +228,10 @@ result.reason
 `from_auto(..., explain=True)` returns the same explanation object:
 
 ```python
-result = hx.from_auto("0b101", explain=True)
+result = hx.from_auto("0b0100111101001011", explain=True)
 
-result.value.hex
-# '05'
+result.value.text
+# 'OK'
 ```
 
 ## Design priorities
@@ -265,7 +255,7 @@ conv("deadbeef")
 # 3735928559
 ```
 
-Available format specs:
+Available format specs all work in their simplest bare form:
 
 - `Bytes()`
 - `BytesArray()`
@@ -273,8 +263,8 @@ Available format specs:
 - `Hex()`
 - `HexArray()`
 - `HexInt()` / `LargeHexNumber()`
-- `Int()`
-- `IntArray()`
+- `Int()` / `DecimalInt()`
+- `IntArray()` / `DecimalIntArray()`
 - `Text()`
 - `Binary()`
 - `Base64()`
@@ -285,6 +275,20 @@ Available format specs:
 - `Hexdump()`
 - `Struct(fmt)`
 - `Bits()`
+- `Auto()`
+
+Add options only when you need control over formatting or parsing:
+
+- Display: `Hex(sep=" ", prefix=True, uppercase=True)`, `HexArray(width=2)`.
+- Integer packing: `Int(width=4)`, `Int(endian="little")`, `IntArray(width=2)`.
+- Text: `Text(encoding="utf-8", errors="replace")`.
+- Base encodings: `Base64(urlsafe=True, padding=False)`, `Base32(padding=False)`.
+- Binary/bits: `Binary(sep=" ", prefix=True, bit_order="lsb")`, `Bits(pad_side="right")`.
+- Dumps/escapes/structs: `Hexdump(width=8)`, `Escaped(uppercase=True)`, `Struct(">HH")`.
+
+Some options only matter in one direction. For example, `Hex(sep=" ")`
+controls hex output formatting, while hex input already accepts common
+separators such as spaces, colons, dashes, underscores, and `0x` prefixes.
 
 ## Transforms
 
@@ -292,7 +296,7 @@ Transforms are byte-to-byte steps that sit between input and output formats.
 
 ```python
 hx.Hex() >> hx.Chunk(2) >> hx.HexArray()
-hx.Hex() >> hx.Group(2) >> hx.IntArray(width=2)
+hx.Hex() >> hx.Group(2) >> hx.IntArray()
 hx.Hex() >> hx.Pad.left(width=8) >> hx.Hex()
 hx.Hex() >> hx.Pad.right(block_size=8, byte=0xFF) >> hx.Hex()
 hx.Hex() >> hx.Reverse() >> hx.Hex()

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexconv
-Version: 0.2.3
+Version: 0.2.5
 Summary: Pythonic conversion toolkit for bytes, hex, integers, arrays, binary strings, base64, and text.
 Author: hexconv contributors
 License-Expression: MIT
@@ -41,64 +41,99 @@ It is built around ergonomic one-liners and composable format objects.
 pip install hexconv
 ```
 
-## Quick tour
+## Simple usage
 
-Use direct helpers when you want one obvious conversion:
+Most conversions are one-liners. Use `from_auto` when you want a quick
+best-effort parse, or pick an explicit helper when the input is ambiguous.
 
 ```python
 import hexconv as hx
 
-hx.from_hex("dead beef").to_bytes()
-# b'\xde\xad\xbe\xef'
+hx.from_auto("0x64617461").text
+# 'data'
 
-hx.from_hex("dead beef").bytes
-# b'\xde\xad\xbe\xef'
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).int
+# 3735928559
 
-hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).to_hex()
-# 'deadbeef'
+hx.from_text("data").hex
+# '64617461'
+```
 
-hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).hex
-# 'deadbeef'
+## Fast compose
 
-hx.from_text("data").to_hex_array(prefix=True)
-# ['0x64', '0x61', '0x74', '0x61']
+Create your own converters by snapping together
+`source format >> optional transforms >> target format`.
 
-hx.from_int(0xdeadbeef).to_bytes()
-# b'\xde\xad\xbe\xef'
+```python
+to_bytes = hx.Hex() >> hx.Bytes()
+to_bytes("68 69")
+# b'hi'
 
-hx.from_int_array([0x1234, 0x5678], width=2).to_hex_array(width=2)
-# ['1234', '5678']
+spaced_hex = hx.Bytes() >> hx.Hex(sep=" ")
+spaced_hex(b"data")
+# '64 61 74 61'
+
+words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray()
+words("12 34 56 78")
+# [4660, 22136]
+
+pack_to_hex = hx.Struct(">HH") >> hx.Hex()
+pack_to_hex((0x1234, 0x5678))
+# '12345678'
 ```
 
-Use `from_auto` when you want a quick best-effort parse:
+## Configure when needed
+
+Formats work bare by default. Add arguments only for the conversion that needs
+them:
 
 ```python
-hx.from_auto("0xdeadbeef").bytes
+hx.convert("de ad be ef", hx.Hex(), hx.Bytes())
 # b'\xde\xad\xbe\xef'
 
-hx.from_auto(b"\xde\xad").hex
-# 'dead'
+hx.convert(b"\xde\xad\xbe\xef", hx.Bytes(), hx.Hex(sep=" ", prefix=True, uppercase=True))
+# '0xDE AD BE EF'
+
+hx.convert("π", hx.Text(encoding="utf-8"), hx.Hex())
+# 'cf80'
 
-hx.from_auto([0xde, 0xad, 0xbe, 0xef]).to(hx.Hex(prefix=True))
-# '0xdeadbeef'
+hx.from_int(0x12345678, endian="little").hex
+# '78563412'
+
+hx.convert("ZGF0YQ", hx.Base64(padding=False), hx.Text())
+# 'data'
+
+hx.from_binary("00010110 10010110", bit_order="lsb").text
+# 'hi'
 ```
 
-## Composable interface
+Hex strings may include common separators, so you do not need to manually strip
+spaces, colons, dashes, or `0x` prefixes before converting. `Hex(sep=" ")` is
+how you emit space-separated hex.
+
+## Full pipeline guide
 
 `hexconv` is built around small format objects. A format can parse directly:
 
 ```python
-hx.Hex()("dead beef").bytes
+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
+hx.Int(endian="little")(0x12345678).hex
 # '78563412'
+
+pack_words = hx.Struct(">HH")
+pack_words((0x1234, 0x5678)).hex
+# '12345678'
+
+hx.Hex()("12345678").to(pack_words)
+# (4660, 22136)
 ```
 
-Formats compose with `>>`:
+Formats compose with `>>`, so reusable converters are normal Python objects:
 
 ```python
 to_text = hx.HexArray() >> hx.Text()
@@ -108,12 +143,20 @@ to_text([0x48, 0x65, 0x6C, 0x6C, 0x6F])
 to_hex = hx.Text() >> hx.Hex(prefix=True)
 to_hex("data")
 # '0x64617461'
+
+pack_to_hex = hx.Struct(">HH") >> hx.Hex()
+pack_to_hex((0x1234, 0x5678))
+# '12345678'
+
+unpack_from_hex = hx.Hex() >> hx.Struct(">HH")
+unpack_from_hex("12345678")
+# (4660, 22136)
 ```
 
 Transforms sit between formats when data needs shaping:
 
 ```python
-words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray(width=2)
+words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray()
 words("12345678")
 # [4660, 22136]
 
@@ -140,30 +183,7 @@ conv("12345678")
 # ['0x1234', '0x5678']
 ```
 
-## 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:
+More conversion patterns:
 
 ```python
 hx.Text()("hello").bytes
@@ -172,54 +192,24 @@ hx.Text()("hello").bytes
 hx.Hex()("68656c6c6f").text
 # 'hello'
 
-hx.BytesArray()([0x68, 0x69]).to(hx.Text())
-# 'hi'
-```
+hx.BytesArray()([0x4F, 0x4B]).to(hx.Text())
+# 'OK'
 
-Integer packing:
-
-```python
-hx.Int(width=2)(0x1234).hex
-# '1234'
-
-hx.Int(width=2, endian="little")(0x1234).hex
+hx.Int(endian="little")(0x1234).hex
 # '3412'
 
-(hx.Hex() >> hx.Chunk(2) >> hx.IntArray(width=2))("12345678")
-# [4660, 22136]
-```
-
-Base encodings:
-
-```python
-hx.Text()("data").to(hx.Base64())
-# 'ZGF0YQ=='
-
 hx.Text()("data").to(hx.Base32(padding=False))
 # 'MRQXIYI'
 
-hx.Base64(urlsafe=True, padding=False)("-_8").hex
-# 'fbff'
-```
-
-Escaped strings, hexdumps, structs, and bits:
-
-```python
-hx.Escaped()(r"\xde\xad").hex
-# 'dead'
-
-dump = hx.Hex()("deadbeef").to(hx.Hexdump(width=2))
-hx.Hexdump()(dump).hex
-# 'deadbeef'
-
-hx.Struct(">HH")((0x1234, 0x5678)).hex
-# '12345678'
+dump = hx.Text()("data").to(hx.Hexdump(width=2))
+hx.Hexdump()(dump).text
+# 'data'
 
 hx.Hex()("12345678").to(hx.Struct(">HH"))
 # (4660, 22136)
 
-hx.Bits()([1, 0, 1]).hex
-# '05'
+hx.Bits()("0100111101001011").text
+# 'OK'
 ```
 
 ## Why explicit formats?
@@ -267,10 +257,10 @@ result.reason
 `from_auto(..., explain=True)` returns the same explanation object:
 
 ```python
-result = hx.from_auto("0b101", explain=True)
+result = hx.from_auto("0b0100111101001011", explain=True)
 
-result.value.hex
-# '05'
+result.value.text
+# 'OK'
 ```
 
 ## Design priorities
@@ -294,7 +284,7 @@ conv("deadbeef")
 # 3735928559
 ```
 
-Available format specs:
+Available format specs all work in their simplest bare form:
 
 - `Bytes()`
 - `BytesArray()`
@@ -302,8 +292,8 @@ Available format specs:
 - `Hex()`
 - `HexArray()`
 - `HexInt()` / `LargeHexNumber()`
-- `Int()`
-- `IntArray()`
+- `Int()` / `DecimalInt()`
+- `IntArray()` / `DecimalIntArray()`
 - `Text()`
 - `Binary()`
 - `Base64()`
@@ -314,6 +304,20 @@ Available format specs:
 - `Hexdump()`
 - `Struct(fmt)`
 - `Bits()`
+- `Auto()`
+
+Add options only when you need control over formatting or parsing:
+
+- Display: `Hex(sep=" ", prefix=True, uppercase=True)`, `HexArray(width=2)`.
+- Integer packing: `Int(width=4)`, `Int(endian="little")`, `IntArray(width=2)`.
+- Text: `Text(encoding="utf-8", errors="replace")`.
+- Base encodings: `Base64(urlsafe=True, padding=False)`, `Base32(padding=False)`.
+- Binary/bits: `Binary(sep=" ", prefix=True, bit_order="lsb")`, `Bits(pad_side="right")`.
+- Dumps/escapes/structs: `Hexdump(width=8)`, `Escaped(uppercase=True)`, `Struct(">HH")`.
+
+Some options only matter in one direction. For example, `Hex(sep=" ")`
+controls hex output formatting, while hex input already accepts common
+separators such as spaces, colons, dashes, underscores, and `0x` prefixes.
 
 ## Transforms
 
@@ -321,7 +325,7 @@ Transforms are byte-to-byte steps that sit between input and output formats.
 
 ```python
 hx.Hex() >> hx.Chunk(2) >> hx.HexArray()
-hx.Hex() >> hx.Group(2) >> hx.IntArray(width=2)
+hx.Hex() >> hx.Group(2) >> hx.IntArray()
 hx.Hex() >> hx.Pad.left(width=8) >> hx.Hex()
 hx.Hex() >> hx.Pad.right(block_size=8, byte=0xFF) >> hx.Hex()
 hx.Hex() >> hx.Reverse() >> hx.Hex()

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

@@ -45,10 +45,56 @@ 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("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(
+            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())
@@ -114,10 +160,10 @@ def test_constructable_hex_and_text_specs():
 
 
 def test_pipeline_builder_and_shift_composition():
-    conv = hx.pipeline().from_(hx.Hex(sep=" ")).chunk(2).to(hx.IntArray(width=2))
+    conv = hx.pipeline().from_(hx.Hex()).chunk(2).to(hx.IntArray())
     assert conv("12 34 56 78") == [0x1234, 0x5678]
 
-    shift_conv = hx.Hex(sep=" ") >> hx.Chunk(2) >> hx.HexArray()
+    shift_conv = hx.Hex() >> hx.Chunk(2) >> hx.HexArray()
     assert shift_conv("12 34 56 78") == ["1234", "5678"]
 
 
@@ -160,6 +206,9 @@ def test_struct_format_pack_and_unpack():
     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.Struct(">HH")((0x1234, 0x5678)).hex == "12345678"
+    assert (hx.Struct(">HH") >> hx.Hex())((0x1234, 0x5678)) == "12345678"
+    assert (hx.Hex() >> hx.Struct(">HH"))("12345678") == (0x1234, 0x5678)
 
 
 def test_bit_array_and_lsb_bit_order():