hexconv 0.1.0__py3-none-any.whl

hexconv/__init__.py

@@ -0,0 +1,76 @@
+"""CTF-friendly conversions between bytes, hex, integers, arrays, and text."""
+
+from ._core import (
+    ASCIIText,
+    Auto,
+    Base64String,
+    BinaryString,
+    Bytes,
+    BytesArray,
+    BytesString,
+    Converter,
+    DecimalInt,
+    DecimalIntArray,
+    HexArray,
+    HexConvError,
+    HexInt,
+    HexNumbersArray,
+    HexString,
+    Int,
+    IntArray,
+    LargeHexNumber,
+    RawString,
+    Text,
+    Value,
+    convert,
+    from_auto,
+    from_base64,
+    from_binary,
+    from_bytes,
+    from_bytes_array,
+    from_bytes_string,
+    from_hex,
+    from_hex_array,
+    from_hex_int,
+    from_int,
+    from_int_array,
+    from_text,
+)
+
+__all__ = [
+    "ASCIIText",
+    "Auto",
+    "Base64String",
+    "BinaryString",
+    "Bytes",
+    "BytesArray",
+    "BytesString",
+    "Converter",
+    "DecimalInt",
+    "DecimalIntArray",
+    "HexArray",
+    "HexConvError",
+    "HexInt",
+    "HexNumbersArray",
+    "HexString",
+    "Int",
+    "IntArray",
+    "LargeHexNumber",
+    "RawString",
+    "Text",
+    "Value",
+    "convert",
+    "from_auto",
+    "from_base64",
+    "from_binary",
+    "from_bytes",
+    "from_bytes_array",
+    "from_bytes_string",
+    "from_hex",
+    "from_hex_array",
+    "from_hex_int",
+    "from_int",
+    "from_int_array",
+    "from_text",
+]
+

hexconv/_core.py

@@ -0,0 +1,832 @@
+from __future__ import annotations
+
+import ast
+import base64
+import binascii
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any, Callable, TypeAlias
+
+
+class HexConvError(ValueError):
+    """Raised when a value cannot be parsed or emitted in the requested format."""
+
+
+class _Format:
+    """Base class for public format marker classes."""
+
+
+class Auto(_Format):
+    """Infer the source format using CTF-friendly heuristics."""
+
+
+class Bytes(_Format):
+    """A Python bytes-like object."""
+
+
+class BytesArray(_Format):
+    """A sequence of byte-sized integers, e.g. [0xde, 0xad]."""
+
+
+class BytesString(_Format):
+    """A string containing a Python bytes literal, e.g. "b'\\xde\\xad'"."""
+
+
+class HexString(_Format):
+    """A hex string, e.g. 'deadbeef', '0xdeadbeef', or 'de ad be ef'."""
+
+
+class HexArray(_Format):
+    """A sequence of hex tokens, e.g. ['de', 'ad'] or ['0xde', '0xad']."""
+
+
+class HexNumbersArray(_Format):
+    """A sequence of integers commonly displayed as hex, e.g. [0xde, 0xad]."""
+
+
+class HexInt(_Format):
+    """A single integer or string interpreted as a large hex number."""
+
+
+class LargeHexNumber(HexInt):
+    """Alias for HexInt."""
+
+
+class Int(_Format):
+    """A Python integer."""
+
+
+class DecimalInt(Int):
+    """Alias for Int."""
+
+
+class IntArray(_Format):
+    """A sequence of integers packed into bytes."""
+
+
+class DecimalIntArray(IntArray):
+    """Alias for IntArray."""
+
+
+class Text(_Format):
+    """Raw text encoded to bytes."""
+
+
+class ASCIIText(Text):
+    """Alias for Text, with ASCII as the default encoding."""
+
+
+class RawString(Text):
+    """Alias for Text."""
+
+
+class BinaryString(_Format):
+    """A binary bit string, e.g. '01100110 01101100'."""
+
+
+class Base64String(_Format):
+    """A base64-encoded string."""
+
+
+Format: TypeAlias = type[_Format]
+Endian: TypeAlias = str
+
+
+_HEX_SEPARATORS = re.compile(r"[\s_:\-,;]+")
+_HEX_PREFIX = re.compile(r"(?i)0x")
+_HEX_CHARS = re.compile(r"^[0-9a-fA-F]*$")
+_BINARY_SEPARATORS = re.compile(r"[\s_:\-,;]+")
+_BINARY_PREFIX = re.compile(r"(?i)0b")
+_BINARY_CHARS = re.compile(r"^[01]*$")
+
+
+@dataclass(frozen=True)
+class Value:
+    """Canonical byte-backed value with output methods for common CTF formats."""
+
+    _data: bytes
+    source: str | None = None
+
+    def to(self, format_: Format, **options: Any) -> Any:
+        """Emit this value using a public format marker such as HexString."""
+
+        try:
+            emitter = _OUTPUTS[format_]
+        except KeyError as exc:
+            raise HexConvError(f"unsupported output format: {format_!r}") from exc
+        return emitter(self, **options)
+
+    def to_bytes(self) -> bytes:
+        """Return a Python bytes object."""
+
+        return self._data
+
+    @property
+    def bytes(self) -> bytes:
+        """Shortcut for to_bytes()."""
+
+        return self.to_bytes()
+
+    def to_bytearray(self) -> bytearray:
+        """Return a Python bytearray."""
+
+        return bytearray(self._data)
+
+    @property
+    def bytearray(self) -> bytearray:
+        """Shortcut for to_bytearray()."""
+
+        return self.to_bytearray()
+
+    def to_bytes_array(self) -> list[int]:
+        """Return one integer per byte."""
+
+        return list(self._data)
+
+    def to_bytes_string(self) -> str:
+        """Return a Python bytes literal string, e.g. "b'\\xde\\xad'"."""
+
+        return repr(self._data)
+
+    @property
+    def bytes_string(self) -> str:
+        """Shortcut for to_bytes_string()."""
+
+        return self.to_bytes_string()
+
+    @property
+    def bytes_array(self) -> list[int]:
+        """Shortcut for to_bytes_array()."""
+
+        return self.to_bytes_array()
+
+    def to_hex(
+        self,
+        *,
+        sep: str = "",
+        prefix: bool = False,
+        uppercase: bool = False,
+    ) -> str:
+        """Return a hex string.
+
+        Args:
+            sep: Separator inserted between bytes. Examples: "", " ", ":".
+            prefix: Add a single "0x" prefix to the whole string.
+            uppercase: Use uppercase A-F.
+        """
+
+        if sep == "":
+            text = self._data.hex()
+        elif len(sep) == 1:
+            text = self._data.hex(sep)
+        else:
+            text = sep.join(f"{byte:02x}" for byte in self._data)
+        if uppercase:
+            text = text.upper()
+        if prefix:
+            text = "0x" + text
+        return text
+
+    @property
+    def hex(self) -> str:
+        """Shortcut for to_hex()."""
+
+        return self.to_hex()
+
+    def to_hex_array(
+        self,
+        *,
+        width: int = 1,
+        prefix: bool = False,
+        uppercase: bool = False,
+    ) -> list[str]:
+        """Return hex tokens grouped by byte width."""
+
+        tokens = [chunk.hex() for chunk in _chunks(self._data, width)]
+        if uppercase:
+            tokens = [token.upper() for token in tokens]
+        if prefix:
+            tokens = ["0x" + token for token in tokens]
+        return tokens
+
+    def to_hex_numbers(self, *, width: int = 1, endian: Endian = "big") -> list[int]:
+        """Return integers for chunks that are commonly displayed with hex()."""
+
+        return self.to_int_array(width=width, endian=endian, signed=False)
+
+    def to_int(self, *, endian: Endian = "big", signed: bool = False) -> int:
+        """Return the whole byte sequence as one integer."""
+
+        _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,
+        *,
+        width: int = 1,
+        endian: Endian = "big",
+        signed: bool = False,
+    ) -> list[int]:
+        """Return one integer per fixed-width chunk."""
+
+        _validate_endian(endian)
+        return [
+            int.from_bytes(chunk, endian, signed=signed)
+            for chunk in _chunks(self._data, width)
+        ]
+
+    def to_text(self, *, encoding: str = "ascii", errors: str = "strict") -> str:
+        """Decode bytes to text. ASCII is the default for CTF workflows."""
+
+        return self._data.decode(encoding, errors=errors)
+
+    @property
+    def text(self) -> str:
+        """Shortcut for to_text()."""
+
+        return self.to_text()
+
+    def to_ascii(self, *, errors: str = "strict") -> str:
+        """Decode bytes as ASCII."""
+
+        return self.to_text(encoding="ascii", errors=errors)
+
+    def to_binary(self, *, sep: str = "") -> str:
+        """Return an 8-bit binary representation for each byte."""
+
+        return sep.join(f"{byte:08b}" for byte in self._data)
+
+    @property
+    def binary(self) -> str:
+        """Shortcut for to_binary()."""
+
+        return self.to_binary()
+
+    def to_base64(self) -> str:
+        """Return standard base64 text."""
+
+        return base64.b64encode(self._data).decode("ascii")
+
+    @property
+    def base64(self) -> str:
+        """Shortcut for to_base64()."""
+
+        return self.to_base64()
+
+
+class Converter:
+    """Reusable converter between two explicit formats.
+
+    Example:
+        Converter(BytesArray, HexArray)([0xde, 0xad]) == ["de", "ad"]
+    """
+
+    def __init__(
+        self,
+        from_: Format = Auto,
+        to: Format = Bytes,
+        *,
+        input_options: dict[str, Any] | None = None,
+        output_options: dict[str, Any] | None = None,
+    ) -> None:
+        self.from_ = from_
+        self.to = to
+        self.input_options = dict(input_options or {})
+        self.output_options = dict(output_options or {})
+
+    def __call__(self, value: Any) -> Any:
+        parsed = _parse(value, self.from_, **self.input_options)
+        return parsed.to(self.to, **self.output_options)
+
+    def parse(self, value: Any) -> Value:
+        """Parse a value and return the canonical Value instead of emitting."""
+
+        return _parse(value, self.from_, **self.input_options)
+
+    def convert(self, value: Any) -> Any:
+        """Alias for __call__."""
+
+        return self(value)
+
+
+def convert(
+    value: Any,
+    *,
+    from_: Format = Auto,
+    to: Format = Bytes,
+    input_options: dict[str, Any] | None = None,
+    output_options: dict[str, Any] | None = None,
+) -> Any:
+    """One-shot conversion between explicit formats."""
+
+    return Converter(
+        from_,
+        to,
+        input_options=input_options,
+        output_options=output_options,
+    )(value)
+
+
+def from_auto(value: Any) -> Value:
+    """Parse a value using convenience heuristics.
+
+    Heuristics are intentionally simple:
+    - Value -> unchanged
+    - bytes-like -> bytes
+    - int -> minimal-width integer bytes
+    - bytes literal string like "b'\\xde'" -> bytes
+    - 0x-prefixed or hex-looking strings -> hex
+    - 0b-prefixed binary strings -> binary
+    - text strings -> ASCII text
+    - integer sequences -> byte array if every value fits one byte; otherwise int array
+    """
+
+    if isinstance(value, Value):
+        return value
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return from_bytes(value)
+    if isinstance(value, int) and not isinstance(value, bool):
+        return from_int(value)
+    if isinstance(value, str):
+        stripped = value.strip()
+        if _looks_like_bytes_literal(stripped):
+            return from_bytes_string(stripped)
+        if _looks_like_binary(stripped):
+            return from_binary(stripped)
+        if _looks_like_hex(stripped):
+            return from_hex(stripped)
+        return from_text(value)
+    try:
+        values = _coerce_int_sequence(value, name="integer sequence")
+    except HexConvError:
+        values = None
+    if values is not None:
+        if all(0 <= item <= 0xFF for item in values):
+            return from_bytes_array(values)
+        return from_int_array(values, width=None)
+    raise HexConvError(f"cannot infer source format for {type(value).__name__}")
+
+
+def from_bytes(value: bytes | bytearray | memoryview | Iterable[int]) -> Value:
+    """Parse a bytes-like object or a byte-sized integer sequence."""
+
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return Value(bytes(value), source="bytes")
+    if isinstance(value, Iterable) and not isinstance(value, (str, bytes, bytearray)):
+        return from_bytes_array(value)
+    raise HexConvError(f"expected bytes-like object, got {type(value).__name__}")
+
+
+def from_bytes_array(values: Iterable[int]) -> Value:
+    """Parse a sequence of byte-sized integers."""
+
+    items = _coerce_int_sequence(values, name="bytes array")
+    for index, item in enumerate(items):
+        if not 0 <= item <= 0xFF:
+            raise HexConvError(
+                f"bytes array item at index {index} is outside 0..255: {item!r}"
+            )
+    return Value(bytes(items), source="bytes_array")
+
+
+def from_bytes_string(value: str | bytes | bytearray | memoryview) -> Value:
+    """Parse a Python bytes literal string, e.g. "b'\\xde\\xad'"."""
+
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return from_bytes(value)
+    if not isinstance(value, str):
+        raise HexConvError(f"expected bytes literal string, got {type(value).__name__}")
+    try:
+        parsed = ast.literal_eval(value.strip())
+    except (SyntaxError, ValueError) as exc:
+        raise HexConvError(f"invalid bytes literal: {value!r}") from exc
+    if not isinstance(parsed, bytes):
+        raise HexConvError(f"literal did not evaluate to bytes: {value!r}")
+    return Value(parsed, source="bytes_string")
+
+
+def from_hex(value: str | bytes | bytearray, *, pad_odd: bool = True) -> Value:
+    """Parse a hex string.
+
+    Common separators are accepted: whitespace, underscores, colons, hyphens,
+    commas, and semicolons. A global or per-token 0x prefix is accepted.
+    Odd-length hex is left-padded by default, so "abc" becomes "0abc".
+    """
+
+    digits = _parse_hex_digits(value, pad_odd=pad_odd)
+    try:
+        return Value(bytes.fromhex(digits), source="hex")
+    except ValueError as exc:
+        raise HexConvError(f"invalid hex string: {value!r}") from exc
+
+
+def from_hex_array(
+    values: Iterable[str | int],
+    *,
+    width: int | None = None,
+    endian: Endian = "big",
+    pad_odd: bool = True,
+) -> Value:
+    """Parse a sequence of hex tokens.
+
+    String tokens are interpreted as hex bytes. Integer tokens are packed using
+    `width` if provided, otherwise their minimal positive byte width.
+    """
+
+    _validate_endian(endian)
+    if not isinstance(values, Iterable) or isinstance(values, (str, bytes, bytearray)):
+        raise HexConvError("expected a sequence of hex tokens")
+
+    parts: list[bytes] = []
+    for item in values:
+        if isinstance(item, int) and not isinstance(item, bool):
+            parts.append(_int_to_bytes(item, width=width, min_width=1, endian=endian))
+            continue
+        digits = _parse_hex_digits(item, pad_odd=pad_odd)
+        if width is None:
+            parts.append(bytes.fromhex(digits))
+        else:
+            parts.append(
+                _int_to_bytes(int(digits or "0", 16), width=width, endian=endian)
+            )
+    return Value(b"".join(parts), source="hex_array")
+
+
+def from_hex_int(
+    value: str | int,
+    *,
+    min_width: int = 1,
+    width: int | None = None,
+    endian: Endian = "big",
+    pad_odd: bool = True,
+) -> Value:
+    """Parse a single large hex number.
+
+    This treats the input as a number, not as a visible byte sequence. Use
+    from_hex() when leading zeroes or visible byte order must be preserved.
+    """
+
+    if isinstance(value, int) and not isinstance(value, bool):
+        return from_int(value, min_width=min_width, width=width, endian=endian)
+    if not isinstance(value, str):
+        raise HexConvError(f"expected str or int hex number, got {type(value).__name__}")
+    digits = _parse_hex_digits(value, pad_odd=pad_odd)
+    return from_int(
+        int(digits or "0", 16),
+        min_width=min_width,
+        width=width,
+        endian=endian,
+    )
+
+
+def from_int(
+    value: int,
+    *,
+    min_width: int = 1,
+    width: int | None = None,
+    endian: Endian = "big",
+    signed: bool = False,
+) -> Value:
+    """Pack one integer into bytes."""
+
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise HexConvError(f"expected int, got {type(value).__name__}")
+    return Value(
+        _int_to_bytes(
+            value,
+            width=width,
+            min_width=min_width,
+            endian=endian,
+            signed=signed,
+        ),
+        source="int",
+    )
+
+
+def from_int_array(
+    values: Iterable[int],
+    *,
+    width: int | None = 1,
+    endian: Endian = "big",
+    signed: bool = False,
+) -> Value:
+    """Pack a sequence of integers into bytes.
+
+    `width=1` matches a byte array. Use `width=None` for minimal-width packing
+    per integer, or set a fixed width such as 2, 4, or 8 for word arrays.
+    """
+
+    items = _coerce_int_sequence(values, name="integer array")
+    return Value(
+        b"".join(
+            _int_to_bytes(item, width=width, min_width=1, endian=endian, signed=signed)
+            for item in items
+        ),
+        source="int_array",
+    )
+
+
+def from_text(
+    value: str,
+    *,
+    encoding: str = "ascii",
+    errors: str = "strict",
+) -> Value:
+    """Encode raw text to bytes. ASCII is the default for CTF workflows."""
+
+    if not isinstance(value, str):
+        raise HexConvError(f"expected str, got {type(value).__name__}")
+    return Value(value.encode(encoding, errors=errors), source="text")
+
+
+def from_binary(value: str | bytes | bytearray, *, pad_odd: bool = True) -> Value:
+    """Parse a binary bit string into bytes."""
+
+    bits = _parse_binary_digits(value, pad_odd=pad_odd)
+    return Value(
+        bytes(int(bits[index : index + 8], 2) for index in range(0, len(bits), 8)),
+        source="binary",
+    )
+
+
+def from_base64(value: str | bytes | bytearray, *, validate: bool = True) -> Value:
+    """Parse standard base64 text."""
+
+    if isinstance(value, str):
+        raw = value.encode("ascii")
+    elif isinstance(value, (bytes, bytearray)):
+        raw = bytes(value)
+    else:
+        raise HexConvError(f"expected base64 str or bytes, got {type(value).__name__}")
+    try:
+        return Value(base64.b64decode(raw, validate=validate), source="base64")
+    except (binascii.Error, ValueError) as exc:
+        raise HexConvError(f"invalid base64 value: {value!r}") from exc
+
+
+def _parse(value: Any, format_: Format, **options: Any) -> Value:
+    try:
+        parser = _INPUTS[format_]
+    except KeyError as exc:
+        raise HexConvError(f"unsupported input format: {format_!r}") from exc
+    return parser(value, **options)
+
+
+def _emit_bytes(value: Value) -> bytes:
+    return value.to_bytes()
+
+
+def _emit_bytearray(value: Value) -> bytearray:
+    return value.to_bytearray()
+
+
+def _emit_bytes_string(value: Value) -> str:
+    return value.to_bytes_string()
+
+
+def _emit_bytes_array(value: Value) -> list[int]:
+    return value.to_bytes_array()
+
+
+def _emit_hex_string(value: Value, **options: Any) -> str:
+    return value.to_hex(**options)
+
+
+def _emit_hex_array(value: Value, **options: Any) -> list[str]:
+    return value.to_hex_array(**options)
+
+
+def _emit_hex_numbers_array(value: Value, **options: Any) -> list[int]:
+    return value.to_hex_numbers(**options)
+
+
+def _emit_int(value: Value, **options: Any) -> int:
+    return value.to_int(**options)
+
+
+def _emit_int_array(value: Value, **options: Any) -> list[int]:
+    return value.to_int_array(**options)
+
+
+def _emit_text(value: Value, **options: Any) -> str:
+    return value.to_text(**options)
+
+
+def _emit_binary(value: Value, **options: Any) -> str:
+    return value.to_binary(**options)
+
+
+def _emit_base64(value: Value) -> str:
+    return value.to_base64()
+
+
+_INPUTS: dict[Format, Callable[..., Value]] = {
+    Auto: from_auto,
+    Bytes: from_bytes,
+    BytesArray: from_bytes_array,
+    BytesString: from_bytes_string,
+    HexString: from_hex,
+    HexArray: from_hex_array,
+    HexNumbersArray: from_int_array,
+    HexInt: from_hex_int,
+    LargeHexNumber: from_hex_int,
+    Int: from_int,
+    DecimalInt: from_int,
+    IntArray: from_int_array,
+    DecimalIntArray: from_int_array,
+    Text: from_text,
+    ASCIIText: from_text,
+    RawString: from_text,
+    BinaryString: from_binary,
+    Base64String: from_base64,
+}
+
+_OUTPUTS: dict[Format, Callable[..., Any]] = {
+    Bytes: _emit_bytes,
+    BytesArray: _emit_bytes_array,
+    BytesString: _emit_bytes_string,
+    HexString: _emit_hex_string,
+    HexArray: _emit_hex_array,
+    HexNumbersArray: _emit_hex_numbers_array,
+    HexInt: _emit_int,
+    LargeHexNumber: _emit_int,
+    Int: _emit_int,
+    DecimalInt: _emit_int,
+    IntArray: _emit_int_array,
+    DecimalIntArray: _emit_int_array,
+    Text: _emit_text,
+    ASCIIText: _emit_text,
+    RawString: _emit_text,
+    BinaryString: _emit_binary,
+    Base64String: _emit_base64,
+}
+
+
+def _validate_endian(endian: Endian) -> None:
+    if endian not in {"big", "little"}:
+        raise HexConvError("endian must be 'big' or 'little'")
+
+
+def _validate_width(width: int | None, *, name: str = "width") -> None:
+    if width is None:
+        return
+    if not isinstance(width, int) or isinstance(width, bool) or width <= 0:
+        raise HexConvError(f"{name} must be a positive integer or None")
+
+
+def _chunks(data: bytes, width: int) -> list[bytes]:
+    _validate_width(width)
+    if width is None:  # kept for type-checkers; _validate_width rejects only invalid ints
+        raise HexConvError("chunk width cannot be None")
+    return [data[index : index + width] for index in range(0, len(data), width)]
+
+
+def _coerce_int_sequence(values: Any, *, name: str) -> list[int]:
+    if isinstance(values, (str, bytes, bytearray, memoryview)):
+        raise HexConvError(f"expected {name} as a sequence of integers")
+    if not isinstance(values, Iterable):
+        raise HexConvError(f"expected {name} as a sequence of integers")
+    try:
+        items = list(values)
+    except TypeError as exc:
+        raise HexConvError(f"expected {name} as a sequence of integers") from exc
+    if not all(isinstance(item, int) and not isinstance(item, bool) for item in items):
+        raise HexConvError(f"expected {name} as a sequence of integers")
+    return items
+
+
+def _parse_hex_digits(value: Any, *, pad_odd: bool) -> str:
+    if isinstance(value, (bytes, bytearray)):
+        try:
+            text = bytes(value).decode("ascii")
+        except UnicodeDecodeError as exc:
+            raise HexConvError("hex bytes must be ASCII text") from exc
+    elif isinstance(value, str):
+        text = value
+    else:
+        raise HexConvError(f"expected hex string, got {type(value).__name__}")
+
+    text = text.strip()
+    digits = _HEX_PREFIX.sub("", text)
+    digits = _HEX_SEPARATORS.sub("", digits)
+    if not _HEX_CHARS.fullmatch(digits):
+        raise HexConvError(f"invalid hex characters in {value!r}")
+    if len(digits) % 2:
+        if not pad_odd:
+            raise HexConvError(f"hex string has odd length: {value!r}")
+        digits = "0" + digits
+    return digits
+
+
+def _parse_binary_digits(value: Any, *, pad_odd: bool) -> str:
+    if isinstance(value, (bytes, bytearray)):
+        try:
+            text = bytes(value).decode("ascii")
+        except UnicodeDecodeError as exc:
+            raise HexConvError("binary bytes must be ASCII text") from exc
+    elif isinstance(value, str):
+        text = value
+    else:
+        raise HexConvError(f"expected binary string, got {type(value).__name__}")
+
+    bits = _BINARY_PREFIX.sub("", text.strip())
+    bits = _BINARY_SEPARATORS.sub("", bits)
+    if not _BINARY_CHARS.fullmatch(bits):
+        raise HexConvError(f"invalid binary characters in {value!r}")
+    remainder = len(bits) % 8
+    if remainder:
+        if not pad_odd:
+            raise HexConvError(f"binary string is not byte-aligned: {value!r}")
+        bits = ("0" * (8 - remainder)) + bits
+    return bits
+
+
+def _looks_like_bytes_literal(value: str) -> bool:
+    return (
+        len(value) >= 3
+        and value[0] in {"b", "B"}
+        and value[1] in {"'", '"'}
+        and value[-1] == value[1]
+    )
+
+
+def _looks_like_binary(value: str) -> bool:
+    stripped = value.strip()
+    if not stripped:
+        return False
+    return stripped.lower().startswith("0b")
+
+
+def _looks_like_hex(value: str) -> bool:
+    stripped = value.strip()
+    if not stripped:
+        return False
+    if "0x" in stripped.lower():
+        return True
+    if _HEX_SEPARATORS.search(stripped):
+        try:
+            _parse_hex_digits(stripped, pad_odd=True)
+        except HexConvError:
+            return False
+        return True
+    return bool(_HEX_CHARS.fullmatch(stripped) and len(stripped) >= 2)
+
+
+def _int_to_bytes(
+    value: int,
+    *,
+    width: int | None = None,
+    min_width: int = 1,
+    endian: Endian = "big",
+    signed: bool = False,
+) -> bytes:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise HexConvError(f"expected int, got {type(value).__name__}")
+    _validate_width(width)
+    _validate_width(min_width, name="min_width")
+    _validate_endian(endian)
+    if not signed and value < 0:
+        raise HexConvError("negative integers require signed=True")
+
+    if width is not None:
+        try:
+            return value.to_bytes(width, endian, signed=signed)
+        except OverflowError as exc:
+            raise HexConvError(f"integer {value!r} does not fit in {width} bytes") from exc
+
+    if signed:
+        return _signed_int_to_minimal_bytes(value, min_width=min_width, endian=endian)
+
+    needed = max(min_width, 1, (value.bit_length() + 7) // 8)
+    try:
+        return value.to_bytes(needed, endian, signed=False)
+    except OverflowError as exc:
+        raise HexConvError(f"could not pack integer {value!r}") from exc
+
+
+def _signed_int_to_minimal_bytes(value: int, *, min_width: int, endian: Endian) -> bytes:
+    candidate = max(min_width, 1, (abs(value).bit_length() + 8) // 8)
+    for width in range(candidate, candidate + 2):
+        try:
+            return value.to_bytes(width, endian, signed=True)
+        except OverflowError:
+            continue
+    width = candidate + 2
+    while True:
+        try:
+            return value.to_bytes(width, endian, signed=True)
+        except OverflowError:
+            width += 1

hexconv/py.typed

@@ -0,0 +1 @@
+

hexconv-0.1.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: hexconv
+Version: 0.1.0
+Summary: Pythonic CTF-friendly conversions between bytes, hex, integers, arrays, and text.
+Author: hexconv contributors
+License-Expression: MIT
+Keywords: ctf,hex,bytes,conversion,pwn,crypto
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# hexconv
+
+`hexconv` is a small, dependency-free Python library for CTF-style conversions between
+bytes, byte arrays, hex strings, hex arrays, integers, integer arrays, bytes literals,
+binary strings, base64, and raw text.
+
+The main idea is: explicitly state what you have, then ask for what you want.
+
+```python
+import hexconv as hx
+
+hx.from_hex("dead beef").to_bytes()
+# b'\xde\xad\xbe\xef'
+
+hx.from_hex("dead beef").bytes
+# b'\xde\xad\xbe\xef'
+
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).to_hex()
+# 'deadbeef'
+
+hx.from_bytes_array([0xde, 0xad, 0xbe, 0xef]).hex
+# 'deadbeef'
+
+hx.from_text("flag").to_hex_array(prefix=True)
+# ['0x66', '0x6c', '0x61', '0x67']
+
+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']
+```
+
+## Why explicit source helpers?
+
+Some inputs are impossible to infer safely:
+
+```python
+"face"
+```
+
+That could be ASCII text (`66 61 63 65`) or hex bytes (`fa ce`). So `hexconv`
+keeps the safe path explicit:
+
+```python
+hx.from_text("face").to_hex()
+# '66616365'
+
+hx.from_hex("face").to_bytes()
+# b'\xfa\xce'
+```
+
+If you do want convenience heuristics, use `from_auto`:
+
+```python
+hx.from_auto("0xdeadbeef").to_int()
+# 3735928559
+```
+
+## Converter API
+
+If you prefer a reusable converter object, use marker classes:
+
+```python
+conv = hx.Converter(hx.BytesArray, hx.HexArray)
+conv([0xde, 0xad, 0xbe, 0xef])
+# ['de', 'ad', 'be', 'ef']
+
+hx.convert("flag", from_=hx.Text, to=hx.HexString)
+# '666c6167'
+```
+
+For conversions with options, pass input and output option dictionaries:
+
+```python
+conv = hx.Converter(
+    hx.DecimalIntArray,
+    hx.HexArray,
+    input_options={"width": 2},
+    output_options={"width": 2, "prefix": True},
+)
+
+conv([4660, 22136])
+# ['0x1234', '0x5678']
+```
+
+## Supported source helpers
+
+- `from_bytes(value)`
+- `from_bytes_array(values)`
+- `from_bytes_string(value)` for strings like `"b'\\xde\\xad'"`
+- `from_hex(value)`
+- `from_hex_array(values)`
+- `from_hex_int(value)`
+- `from_int(value)`
+- `from_int_array(values, width=...)`
+- `from_text(value)`
+- `from_binary(value)`
+- `from_base64(value)`
+- `from_auto(value)`
+
+## Common output methods
+
+- `to_bytes()`
+- `to_bytearray()`
+- `to_bytes_array()`
+- `to_bytes_string()`
+- `to_hex(sep="", prefix=False, uppercase=False)`
+- `to_hex_array(width=1, prefix=False, uppercase=False)`
+- `to_hex_numbers(width=1)`
+- `to_int(endian="big", signed=False)`
+- `to_int_array(width=1, endian="big", signed=False)`
+- `to_text(encoding="ascii", errors="strict")`
+- `to_binary(sep="")`
+- `to_base64()`
+- `to(format_marker, **options)`

hexconv-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+hexconv/__init__.py,sha256=DQgu_mkaK24jRrxQtAU07eQgLvsp-2k6Mg-bWxVw4WM,1267
+hexconv/_core.py,sha256=YexqAQOTJkcidsakcEohZlt_FzmQwDmOQb17QZ_xOiA,24291
+hexconv/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+hexconv-0.1.0.dist-info/licenses/LICENSE,sha256=jLvnEroKuznlNa13aVTgp4usZ2rEI8v1Em1npsUYGso,1078
+hexconv-0.1.0.dist-info/METADATA,sha256=SG996wA-DIw7dIh7KlR-qRfRcZk2Hez2M81OkUPejF8,3711
+hexconv-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+hexconv-0.1.0.dist-info/top_level.txt,sha256=d5UALxOrOalfcPc_Y7Mc_4E2gGPvGvV-92009p_acB0,8
+hexconv-0.1.0.dist-info/RECORD,,

hexconv-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hexconv-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 hexconv contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

hexconv-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hexconv