hexconv 0.2.4__tar.gz → 0.2.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexconv
-Version: 0.2.4
+Version: 0.2.6
 Summary: Pythonic conversion toolkit for bytes, hex, integers, arrays, binary strings, base64, and text.
 Author: hexconv contributors
 License-Expression: MIT
@@ -41,83 +41,96 @@ It is built around ergonomic one-liners and composable format objects.
 pip install hexconv
 ```
 
-## Fast compose
+## Simple usage
 
-The intended interface is small pieces snapped together:
-`source format >> optional transforms >> target format`.
+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
 
-to_bytes = hx.Hex() >> hx.Bytes()
-to_bytes("de ad be ef")
-# b'\xde\xad\xbe\xef'
-
-spaced_hex = hx.Bytes() >> hx.Hex(sep=" ")
-spaced_hex(b"\xde\xad\xbe\xef")
-# 'de ad be ef'
+hx.from_auto("0x64617461").text
+# 'data'
 
-words = hx.Hex(sep=" ") >> hx.Chunk(2) >> hx.IntArray(width=2)
-words("12 34 56 78")
-# [4660, 22136]
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).int
+# 3735928559
 
-text_to_urlsafe = hx.Text() >> hx.Base64(urlsafe=True, padding=False)
-text_to_urlsafe("data")
-# 'ZGF0YQ'
+hx.from_text("data").hex
+# '64617461'
 ```
 
-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.
+The bare `.hex`, `.text`, and `.bytes` properties are shortcuts for zero-argument
+`to_*` methods. Call the method form when you need options:
 
-## Quick tour
+```python
+value = hx.from_hex("deadbeef")
 
-Use direct helpers when you want one obvious conversion across many
-representations:
+value.to_hex()
+# 'deadbeef'  (same as value.hex)
 
-```python
-hx.from_hex("de ad be ef").bytes
+value.to_hex(sep=" ", uppercase=True)
+# 'DE AD BE EF'
+
+value.to_bytes()
 # b'\xde\xad\xbe\xef'
 
-hx.from_text("data").to_hex_array(prefix=True)
-# ['0x64', '0x61', '0x74', '0x61']
+hx.from_hex("68656c6c6f").to_text()
+# 'hello'
+```
 
-hx.from_int(0xdeadbeef).bytes
-# b'\xde\xad\xbe\xef'
+## Fast compose
 
-hx.from_int_array([0x1234, 0x5678], width=2).to_hex_array(width=2)
-# ['1234', '5678']
+Create your own converters by snapping together
+`source format >> optional transforms >> target format`.
 
-hx.from_binary("01100100 01100001 01110100 01100001").text
-# 'data'
+```python
+to_bytes = hx.Hex() >> hx.Bytes()
+to_bytes("68 69")
+# b'hi'
 
-hx.from_base64("ZGF0YQ==").text
-# 'data'
+spaced_hex = hx.Bytes() >> hx.Hex(sep=" ")
+spaced_hex(b"data")
+# '64 61 74 61'
 
-hx.from_escaped(r"\xde\xad").hex
-# 'dead'
+words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray()
+words("12 34 56 78")
+# [4660, 22136]
 
-hx.from_struct((0x1234, 0x5678), fmt=">HH").hex
+pack_to_hex = hx.Struct(">HH") >> hx.Hex()
+pack_to_hex((0x1234, 0x5678))
 # '12345678'
-
-hx.from_bits("101", pad=True).hex
-# '05'
 ```
 
-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:
 
@@ -128,8 +141,15 @@ hx.Hex()("de ad be ef").bytes
 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 `>>`, so reusable converters are normal Python objects:
@@ -142,12 +162,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]
 
@@ -174,89 +202,27 @@ 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(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:
-
-```python
-hx.Text()("hello").bytes
-# b'hello'
-
-hx.Hex()("68656c6c6f").text
-# 'hello'
-
-hx.BytesArray()([0x68, 0x69]).to(hx.Text())
-# 'hi'
-```
-
-Integer packing:
+More conversion patterns:
 
 ```python
-hx.Int(width=2)(0x1234).hex
-# '1234'
+hx.BytesArray()([0x4F, 0x4B]).to(hx.Text())
+# 'OK'
 
-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?
@@ -304,10 +270,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
@@ -331,7 +297,7 @@ conv("deadbeef")
 # 3735928559
 ```
 
-Available format specs:
+Available format specs all work in their simplest bare form:
 
 - `Bytes()`
 - `BytesArray()`
@@ -339,8 +305,8 @@ Available format specs:
 - `Hex()`
 - `HexArray()`
 - `HexInt()` / `LargeHexNumber()`
-- `Int()`
-- `IntArray()`
+- `Int()` / `DecimalInt()`
+- `IntArray()` / `DecimalIntArray()`
 - `Text()`
 - `Binary()`
 - `Base64()`
@@ -351,6 +317,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
 
@@ -358,7 +338,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.4 → hexconv-0.2.6}/README.md

@@ -12,83 +12,96 @@ It is built around ergonomic one-liners and composable format objects.
 pip install hexconv
 ```
 
-## Fast compose
+## Simple usage
 
-The intended interface is small pieces snapped together:
-`source format >> optional transforms >> target format`.
+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
 
-to_bytes = hx.Hex() >> hx.Bytes()
-to_bytes("de ad be ef")
-# b'\xde\xad\xbe\xef'
-
-spaced_hex = hx.Bytes() >> hx.Hex(sep=" ")
-spaced_hex(b"\xde\xad\xbe\xef")
-# 'de ad be ef'
+hx.from_auto("0x64617461").text
+# 'data'
 
-words = hx.Hex(sep=" ") >> hx.Chunk(2) >> hx.IntArray(width=2)
-words("12 34 56 78")
-# [4660, 22136]
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).int
+# 3735928559
 
-text_to_urlsafe = hx.Text() >> hx.Base64(urlsafe=True, padding=False)
-text_to_urlsafe("data")
-# 'ZGF0YQ'
+hx.from_text("data").hex
+# '64617461'
 ```
 
-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.
+The bare `.hex`, `.text`, and `.bytes` properties are shortcuts for zero-argument
+`to_*` methods. Call the method form when you need options:
 
-## Quick tour
+```python
+value = hx.from_hex("deadbeef")
 
-Use direct helpers when you want one obvious conversion across many
-representations:
+value.to_hex()
+# 'deadbeef'  (same as value.hex)
 
-```python
-hx.from_hex("de ad be ef").bytes
+value.to_hex(sep=" ", uppercase=True)
+# 'DE AD BE EF'
+
+value.to_bytes()
 # b'\xde\xad\xbe\xef'
 
-hx.from_text("data").to_hex_array(prefix=True)
-# ['0x64', '0x61', '0x74', '0x61']
+hx.from_hex("68656c6c6f").to_text()
+# 'hello'
+```
 
-hx.from_int(0xdeadbeef).bytes
-# b'\xde\xad\xbe\xef'
+## Fast compose
 
-hx.from_int_array([0x1234, 0x5678], width=2).to_hex_array(width=2)
-# ['1234', '5678']
+Create your own converters by snapping together
+`source format >> optional transforms >> target format`.
 
-hx.from_binary("01100100 01100001 01110100 01100001").text
-# 'data'
+```python
+to_bytes = hx.Hex() >> hx.Bytes()
+to_bytes("68 69")
+# b'hi'
 
-hx.from_base64("ZGF0YQ==").text
-# 'data'
+spaced_hex = hx.Bytes() >> hx.Hex(sep=" ")
+spaced_hex(b"data")
+# '64 61 74 61'
 
-hx.from_escaped(r"\xde\xad").hex
-# 'dead'
+words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray()
+words("12 34 56 78")
+# [4660, 22136]
 
-hx.from_struct((0x1234, 0x5678), fmt=">HH").hex
+pack_to_hex = hx.Struct(">HH") >> hx.Hex()
+pack_to_hex((0x1234, 0x5678))
 # '12345678'
-
-hx.from_bits("101", pad=True).hex
-# '05'
 ```
 
-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:
 
@@ -99,8 +112,15 @@ hx.Hex()("de ad be ef").bytes
 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 `>>`, so reusable converters are normal Python objects:
@@ -113,12 +133,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]
 
@@ -145,89 +173,27 @@ 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(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:
-
-```python
-hx.Text()("hello").bytes
-# b'hello'
-
-hx.Hex()("68656c6c6f").text
-# 'hello'
-
-hx.BytesArray()([0x68, 0x69]).to(hx.Text())
-# 'hi'
-```
-
-Integer packing:
+More conversion patterns:
 
 ```python
-hx.Int(width=2)(0x1234).hex
-# '1234'
+hx.BytesArray()([0x4F, 0x4B]).to(hx.Text())
+# 'OK'
 
-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?
@@ -275,10 +241,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
@@ -302,7 +268,7 @@ conv("deadbeef")
 # 3735928559
 ```
 
-Available format specs:
+Available format specs all work in their simplest bare form:
 
 - `Bytes()`
 - `BytesArray()`
@@ -310,8 +276,8 @@ Available format specs:
 - `Hex()`
 - `HexArray()`
 - `HexInt()` / `LargeHexNumber()`
-- `Int()`
-- `IntArray()`
+- `Int()` / `DecimalInt()`
+- `IntArray()` / `DecimalIntArray()`
 - `Text()`
 - `Binary()`
 - `Base64()`
@@ -322,6 +288,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
 
@@ -329,7 +309,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.4 → hexconv-0.2.6}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexconv
-Version: 0.2.4
+Version: 0.2.6
 Summary: Pythonic conversion toolkit for bytes, hex, integers, arrays, binary strings, base64, and text.
 Author: hexconv contributors
 License-Expression: MIT
@@ -41,83 +41,96 @@ It is built around ergonomic one-liners and composable format objects.
 pip install hexconv
 ```
 
-## Fast compose
+## Simple usage
 
-The intended interface is small pieces snapped together:
-`source format >> optional transforms >> target format`.
+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
 
-to_bytes = hx.Hex() >> hx.Bytes()
-to_bytes("de ad be ef")
-# b'\xde\xad\xbe\xef'
-
-spaced_hex = hx.Bytes() >> hx.Hex(sep=" ")
-spaced_hex(b"\xde\xad\xbe\xef")
-# 'de ad be ef'
+hx.from_auto("0x64617461").text
+# 'data'
 
-words = hx.Hex(sep=" ") >> hx.Chunk(2) >> hx.IntArray(width=2)
-words("12 34 56 78")
-# [4660, 22136]
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).int
+# 3735928559
 
-text_to_urlsafe = hx.Text() >> hx.Base64(urlsafe=True, padding=False)
-text_to_urlsafe("data")
-# 'ZGF0YQ'
+hx.from_text("data").hex
+# '64617461'
 ```
 
-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.
+The bare `.hex`, `.text`, and `.bytes` properties are shortcuts for zero-argument
+`to_*` methods. Call the method form when you need options:
 
-## Quick tour
+```python
+value = hx.from_hex("deadbeef")
 
-Use direct helpers when you want one obvious conversion across many
-representations:
+value.to_hex()
+# 'deadbeef'  (same as value.hex)
 
-```python
-hx.from_hex("de ad be ef").bytes
+value.to_hex(sep=" ", uppercase=True)
+# 'DE AD BE EF'
+
+value.to_bytes()
 # b'\xde\xad\xbe\xef'
 
-hx.from_text("data").to_hex_array(prefix=True)
-# ['0x64', '0x61', '0x74', '0x61']
+hx.from_hex("68656c6c6f").to_text()
+# 'hello'
+```
 
-hx.from_int(0xdeadbeef).bytes
-# b'\xde\xad\xbe\xef'
+## Fast compose
 
-hx.from_int_array([0x1234, 0x5678], width=2).to_hex_array(width=2)
-# ['1234', '5678']
+Create your own converters by snapping together
+`source format >> optional transforms >> target format`.
 
-hx.from_binary("01100100 01100001 01110100 01100001").text
-# 'data'
+```python
+to_bytes = hx.Hex() >> hx.Bytes()
+to_bytes("68 69")
+# b'hi'
 
-hx.from_base64("ZGF0YQ==").text
-# 'data'
+spaced_hex = hx.Bytes() >> hx.Hex(sep=" ")
+spaced_hex(b"data")
+# '64 61 74 61'
 
-hx.from_escaped(r"\xde\xad").hex
-# 'dead'
+words = hx.Hex() >> hx.Chunk(2) >> hx.IntArray()
+words("12 34 56 78")
+# [4660, 22136]
 
-hx.from_struct((0x1234, 0x5678), fmt=">HH").hex
+pack_to_hex = hx.Struct(">HH") >> hx.Hex()
+pack_to_hex((0x1234, 0x5678))
 # '12345678'
-
-hx.from_bits("101", pad=True).hex
-# '05'
 ```
 
-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:
 
@@ -128,8 +141,15 @@ hx.Hex()("de ad be ef").bytes
 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 `>>`, so reusable converters are normal Python objects:
@@ -142,12 +162,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]
 
@@ -174,89 +202,27 @@ 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(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:
-
-```python
-hx.Text()("hello").bytes
-# b'hello'
-
-hx.Hex()("68656c6c6f").text
-# 'hello'
-
-hx.BytesArray()([0x68, 0x69]).to(hx.Text())
-# 'hi'
-```
-
-Integer packing:
+More conversion patterns:
 
 ```python
-hx.Int(width=2)(0x1234).hex
-# '1234'
+hx.BytesArray()([0x4F, 0x4B]).to(hx.Text())
+# 'OK'
 
-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?
@@ -304,10 +270,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
@@ -331,7 +297,7 @@ conv("deadbeef")
 # 3735928559
 ```
 
-Available format specs:
+Available format specs all work in their simplest bare form:
 
 - `Bytes()`
 - `BytesArray()`
@@ -339,8 +305,8 @@ Available format specs:
 - `Hex()`
 - `HexArray()`
 - `HexInt()` / `LargeHexNumber()`
-- `Int()`
-- `IntArray()`
+- `Int()` / `DecimalInt()`
+- `IntArray()` / `DecimalIntArray()`
 - `Text()`
 - `Binary()`
 - `Base64()`
@@ -351,6 +317,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
 
@@ -358,7 +338,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.4 → hexconv-0.2.6}/tests/test_hexconv.py

@@ -45,11 +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())
@@ -115,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"]
 
 
@@ -161,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():