hexicon 0.1.0__tar.gz

hexicon-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

hexicon-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 buddha
+
+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.

hexicon-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: hexicon
+Version: 0.1.0
+Summary: Visual fingerprints for network addresses — lossless, bit-accurate identicons for IPv6, IPv4, and MAC addresses.
+Project-URL: Homepage, https://github.com/phatbuddha/hexicon
+Project-URL: Repository, https://github.com/phatbuddha/hexicon
+Project-URL: Issues, https://github.com/phatbuddha/hexicon/issues
+Author: phatbuddha
+License-Expression: MIT
+License-File: LICENSE
+Keywords: identicon,ipv4,ipv6,mac,network,terminal,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: System :: Networking
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Hexicon
+
+**Visual fingerprints for network addresses.**
+
+A terminal-first tool to turn IPv6, IPv4, and MAC addresses into bit-accurate, lossless, human-readable visual patterns. Visualize structured binary data in the terminal without losing bit order or structure.
+Or identicons, but for network addresses.
+
+## Why?
+
+Network addresses are hard to compare at a glance.
+Hexicon lets you compare addresses in logs visually, get an intuitive feel for address distribution, and simplify debugging.
+Or just create pixel art to represent your addresses.
+
+---
+
+## Features
+
+- Supports **IPv6, IPv4, and MAC addresses**
+- Bit-accurate rendering. No hashing, no data loss
+- Semantic structure (network/host, OUI/NIC, octets)
+- Terminal-friendly block rendering with multiple layouts: grid, split, inline, barcode
+- JSON output for programmatic use
+- Zero dependencies. Python stdlib only
+
+## Installation
+
+```bash
+pip install hexicon
+```
+
+## How it works
+
+Hexicon converts addresses into bit-accurate patterns through a deterministic, lossless pipeline. No hashing.
+
+Addresses are normalised to their canonical form, converted to a bitstream, grouped into scanlines of `width` bits, paired as adjacent scanlines (top/bottom), and mapped to half-block characters.
+Each cell (half a block) represents a single bit.
+
+## Usage
+
+### CLI
+
+```bash
+hexicon 2001:db8::1
+
+hexicon --random
+
+hexicon --random --type ipv6 --layout barcode --show-bits --output text
+
+# Read from stdin
+echo "::1" | hexicon -
+```
+
+### Python API
+
+```python
+from hexicon import render_address, addr_to_nibbles
+
+# Render an address to text
+print(render_address("2001:db8::1"))
+
+# Get structured data
+schema = addr_to_nibbles("2001:db8::1")
+print(schema.type)   # "ipv6"
+print(schema.parts)  # [Part(name="net", ...), Part(name="host", ...)]
+
+# JSON output
+print(render_address("::1", output="json"))
+```
+
+## Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--type` | `auto`, `ipv6`, `ipv4`, `mac` | `auto` | Address type |
+| `--layout` | `auto`, `grid`, `split`, `inline`, `barcode` | `auto` | Layout mode |
+| `--width` | `N` or `auto` | `auto` | Bits per scanline row |
+| `--scale` | `N` | `1` | Vertical scaling factor |
+| `--invert` | flag | — | Invert filled/empty pixels |
+| `--output` | `text`, `json` | `text` | Output format |
+| `--random` | flag | — | Generate a random address |
+| `--show-bits` | flag | — | Debug: print bit values |
+| `--no-newline` | flag | — | Suppress trailing newline |
+
+## Layouts
+
+### Split
+Default view. Semantic separation of address parts. For IPv6: network │ host. For MAC: OUI │ NIC.
+
+### Grid
+Vertical stacked version of split view.
+
+### Inline
+Single 1-height continuous strip. Good for logs or embedding.
+
+### Barcode
+Compact 2-height view.
+
+## JSON Output
+
+Returns a JSON object with the following fields:
+
+```json
+{
+  "type": "ipv6",
+  "address": "2001:db8::1",
+  "parts": [
+    {
+      "name": "net",
+      "rows": ["▀ ▀▄", "..."],
+      "bit_range": [0, 64],
+      "label": "network"
+    }
+  ]
+}
+```
+
+## License
+
+MIT

hexicon-0.1.0/README.md

@@ -0,0 +1,119 @@
+# Hexicon
+
+**Visual fingerprints for network addresses.**
+
+A terminal-first tool to turn IPv6, IPv4, and MAC addresses into bit-accurate, lossless, human-readable visual patterns. Visualize structured binary data in the terminal without losing bit order or structure.
+Or identicons, but for network addresses.
+
+## Why?
+
+Network addresses are hard to compare at a glance.
+Hexicon lets you compare addresses in logs visually, get an intuitive feel for address distribution, and simplify debugging.
+Or just create pixel art to represent your addresses.
+
+---
+
+## Features
+
+- Supports **IPv6, IPv4, and MAC addresses**
+- Bit-accurate rendering. No hashing, no data loss
+- Semantic structure (network/host, OUI/NIC, octets)
+- Terminal-friendly block rendering with multiple layouts: grid, split, inline, barcode
+- JSON output for programmatic use
+- Zero dependencies. Python stdlib only
+
+## Installation
+
+```bash
+pip install hexicon
+```
+
+## How it works
+
+Hexicon converts addresses into bit-accurate patterns through a deterministic, lossless pipeline. No hashing.
+
+Addresses are normalised to their canonical form, converted to a bitstream, grouped into scanlines of `width` bits, paired as adjacent scanlines (top/bottom), and mapped to half-block characters.
+Each cell (half a block) represents a single bit.
+
+## Usage
+
+### CLI
+
+```bash
+hexicon 2001:db8::1
+
+hexicon --random
+
+hexicon --random --type ipv6 --layout barcode --show-bits --output text
+
+# Read from stdin
+echo "::1" | hexicon -
+```
+
+### Python API
+
+```python
+from hexicon import render_address, addr_to_nibbles
+
+# Render an address to text
+print(render_address("2001:db8::1"))
+
+# Get structured data
+schema = addr_to_nibbles("2001:db8::1")
+print(schema.type)   # "ipv6"
+print(schema.parts)  # [Part(name="net", ...), Part(name="host", ...)]
+
+# JSON output
+print(render_address("::1", output="json"))
+```
+
+## Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--type` | `auto`, `ipv6`, `ipv4`, `mac` | `auto` | Address type |
+| `--layout` | `auto`, `grid`, `split`, `inline`, `barcode` | `auto` | Layout mode |
+| `--width` | `N` or `auto` | `auto` | Bits per scanline row |
+| `--scale` | `N` | `1` | Vertical scaling factor |
+| `--invert` | flag | — | Invert filled/empty pixels |
+| `--output` | `text`, `json` | `text` | Output format |
+| `--random` | flag | — | Generate a random address |
+| `--show-bits` | flag | — | Debug: print bit values |
+| `--no-newline` | flag | — | Suppress trailing newline |
+
+## Layouts
+
+### Split
+Default view. Semantic separation of address parts. For IPv6: network │ host. For MAC: OUI │ NIC.
+
+### Grid
+Vertical stacked version of split view.
+
+### Inline
+Single 1-height continuous strip. Good for logs or embedding.
+
+### Barcode
+Compact 2-height view.
+
+## JSON Output
+
+Returns a JSON object with the following fields:
+
+```json
+{
+  "type": "ipv6",
+  "address": "2001:db8::1",
+  "parts": [
+    {
+      "name": "net",
+      "rows": ["▀ ▀▄", "..."],
+      "bit_range": [0, 64],
+      "label": "network"
+    }
+  ]
+}
+```
+
+## License
+
+MIT

hexicon-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hexicon"
+version = "0.1.0"
+description = "Visual fingerprints for network addresses — lossless, bit-accurate identicons for IPv6, IPv4, and MAC addresses."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "phatbuddha" },
+]
+keywords = ["ipv6", "ipv4", "mac", "identicon", "network", "visualization", "terminal"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Networking",
+    "Topic :: Utilities",
+]
+
+[project.scripts]
+hexicon = "hexicon.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/phatbuddha/hexicon"
+Repository = "https://github.com/phatbuddha/hexicon"
+Issues = "https://github.com/phatbuddha/hexicon/issues"

hexicon-0.1.0/src/hexicon/__init__.py

@@ -0,0 +1,43 @@
+"""Hexicon – visual fingerprints for network addresses."""
+
+from hexicon._core import (
+    CHARSET_DEFAULT,
+    DEFAULT_WIDTH,
+    LAYOUT_CHOICES,
+    OUTPUT_CHOICES,
+    TYPE_CHOICES,
+    AddressSchema,
+    Part,
+    addr_to_nibbles,
+    detect_type,
+    format_json,
+    format_text,
+    int_to_nibbles,
+    nibbles_to_bits,
+    parse_addr,
+    random_addr,
+    render_address,
+    render_grid,
+)
+
+__all__ = [
+    "CHARSET_DEFAULT",
+    "DEFAULT_WIDTH",
+    "LAYOUT_CHOICES",
+    "OUTPUT_CHOICES",
+    "TYPE_CHOICES",
+    "AddressSchema",
+    "Part",
+    "addr_to_nibbles",
+    "detect_type",
+    "format_json",
+    "format_text",
+    "int_to_nibbles",
+    "nibbles_to_bits",
+    "parse_addr",
+    "random_addr",
+    "render_address",
+    "render_grid",
+]
+
+__version__ = "0.1.0"

hexicon-0.1.0/src/hexicon/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running hexicon as ``python -m hexicon``"""
+
+from hexicon.cli import main
+
+main()

hexicon-0.1.0/src/hexicon/_core.py

@@ -0,0 +1,304 @@
+"""Core rendering logic for hexicon"""
+
+import dataclasses
+import ipaddress
+import json
+import random
+import re
+import sys
+
+# ── Charset ───────────────────────────────────────────────────────────────────
+
+CHARSET_DEFAULT = " ▄▀█"   # index: top*2 + bottom  →  0=' ' 1='▄' 2='▀' 3='█'
+
+# ── Renderer ──────────────────────────────────────────────────────────────────
+
+def nibbles_to_bits(nibbles):
+    """Convert a list of nibbles to a flat list of bits, MSB first."""
+    bits = []
+    for n in nibbles:
+        for i in (3, 2, 1, 0):
+            bits.append((n >> i) & 1)
+    return bits
+
+
+def int_to_nibbles(n, count):
+    """Extract count nibbles from integer n, MSB first"""
+    return [
+        (n >> (4 * shift)) & 0xF
+        for shift in reversed(range(count))
+    ]
+
+
+# ── Schema types ──────────────────────────────────────────────────────────────
+
+@dataclasses.dataclass
+class Part:
+    name: str
+    nibbles: list
+    bit_range: list
+    label: str
+
+
+@dataclasses.dataclass
+class AddressSchema:
+    type: str
+    input: str
+    nibbles: list
+    parts: list
+
+
+# ── Address → nibbles (unified schema) ────────────────────────────────────────
+
+_MAC_RE = re.compile(
+    r'^([0-9a-fA-F]{2})[:\-]'
+    r'([0-9a-fA-F]{2})[:\-]'
+    r'([0-9a-fA-F]{2})[:\-]'
+    r'([0-9a-fA-F]{2})[:\-]'
+    r'([0-9a-fA-F]{2})[:\-]'
+    r'([0-9a-fA-F]{2})$'
+)
+
+
+def detect_type(raw):
+    """Guess address type from string format"""
+    raw = raw.strip()
+    if _MAC_RE.match(raw):
+        return "mac"
+    try:
+        ipaddress.IPv4Address(raw)
+        return "ipv4"
+    except ValueError:
+        pass
+    try:
+        ipaddress.IPv6Address(raw)
+        return "ipv6"
+    except ValueError:
+        pass
+    raise ValueError(f"Cannot detect address type for: {raw!r}")
+
+
+def _parse_ip_nibbles(raw, cls, nibble_count):
+    """Helper for IPv4/IPv6: parses, normalises, extracts nibbles"""
+    obj = cls(raw)
+    return str(obj), int_to_nibbles(int(obj), nibble_count)
+
+
+def _parse_ipv6(raw):
+    normalised, all_nibbles = _parse_ip_nibbles(raw, ipaddress.IPv6Address, 32)
+    return AddressSchema(
+        type="ipv6",
+        input=normalised,
+        nibbles=all_nibbles,
+        parts=[
+            Part(name="net",  nibbles=all_nibbles[:16], bit_range=[0, 64],   label="network"),
+            Part(name="host", nibbles=all_nibbles[16:], bit_range=[64, 128], label="host"),
+        ],
+    )
+
+
+def _parse_ipv4(raw):
+    normalised, all_nibbles = _parse_ip_nibbles(raw, ipaddress.IPv4Address, 8)
+    parts = [
+        Part(
+            name=f"octet{i}",
+            nibbles=all_nibbles[i*2 : i*2+2],
+            bit_range=[i * 8, (i + 1) * 8],
+            label=f"octet {i}",
+        )
+        for i in range(4)
+    ]
+    return AddressSchema(
+        type="ipv4",
+        input=normalised,
+        nibbles=all_nibbles,
+        parts=parts,
+    )
+
+
+def _parse_mac(raw):
+    m = _MAC_RE.match(raw)
+    if not m:
+        raise ValueError(f"Invalid MAC address: {raw!r}")
+    octets = [int(g, 16) for g in m.groups()]
+    n = 0
+    for b in octets:
+        n = (n << 8) | b
+    all_nibbles = int_to_nibbles(n, 12)
+    normalised = ":".join(f"{b:02x}" for b in octets)
+    return AddressSchema(
+        type="mac",
+        input=normalised,
+        nibbles=all_nibbles,
+        parts=[
+            Part(name="oui", nibbles=all_nibbles[:6], bit_range=[0, 24],  label="OUI"),
+            Part(name="nic", nibbles=all_nibbles[6:], bit_range=[24, 48], label="NIC"),
+        ],
+    )
+
+
+_PARSERS = {"ipv6": _parse_ipv6, "ipv4": _parse_ipv4, "mac": _parse_mac}
+
+
+def addr_to_nibbles(addr, addr_type="auto"):
+    """Parses an addr string and return an AddressSchema."""
+    raw = addr.strip()
+
+    if addr_type == "auto":
+        addr_type = detect_type(raw)
+
+    if addr_type not in _PARSERS:
+        raise ValueError(f"Unknown address type: {addr_type!r}")
+    return _PARSERS[addr_type](raw)
+
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+DEFAULT_WIDTH = {"ipv6": 8, "ipv4": 4, "mac": 6}
+TYPE_CHOICES = ["auto", "ipv6", "ipv4", "mac"]
+LAYOUT_CHOICES = ["auto", "grid", "split", "inline", "barcode"]
+OUTPUT_CHOICES = ["text", "json"]
+
+
+def render_grid(nibbles, width, charset, invert=False):
+    """Render nibbles as scanline pairs using halfblock characters.
+
+    Converts nibbles to a flat bitstream, groups into scanlines of
+    `width` bits, pairs adjacent scanlines (top-bottom), and maps
+    each (top_bit, bottom_bit) pair to a halfblock character.
+    """
+    bits = nibbles_to_bits(nibbles)
+
+    # Pad to fill complete scanline pairs
+    pair_size = width * 2
+    remainder = len(bits) % pair_size
+    if remainder:
+        bits = bits + [0] * (pair_size - remainder)
+
+    # Group into scanlines
+    scanlines = [bits[i:i+width] for i in range(0, len(bits), width)]
+
+    # Pad to even number of scanlines
+    if len(scanlines) % 2:
+        scanlines.append([0] * width)
+
+    rows = []
+    for i in range(0, len(scanlines), 2):
+        top = scanlines[i]
+        bot = scanlines[i + 1]
+        row = ''
+        for t, b in zip(top, bot):
+            idx = t * 2 + b
+            row += charset[3 - idx if invert else idx]
+        rows.append(row)
+    return rows
+
+# ── Formatter ─────────────────────────────────────────────────────────────────
+
+def format_text(part_rows, layout, scale):
+    """
+    part_rows: list of (part_name, [rendered_row_strings])
+    layout:  "split" → side-by-side for 2-part addresses, else stacked
+    """
+    lines = []
+    if layout == "split" and len(part_rows) == 2:
+        # side-by-side
+        left  = part_rows[0][1]
+        right = part_rows[1][1]
+        left_w  = len(left[0]) if left else 0
+        right_w = len(right[0]) if right else 0
+        max_len = max(len(left), len(right))
+        left = left + [" " * left_w]  * (max_len - len(left))
+        right = right + [" " * right_w] * (max_len - len(right))
+        for l, r in zip(left, right):
+            row = l + "  " + r
+            for _ in range(scale):
+                lines.append(row)
+    else:
+        for _name, rows in part_rows:
+            for row in rows:
+                for _ in range(scale):
+                    lines.append(row)
+    return '\n'.join(lines)
+
+
+def format_json(schema, part_rows):
+    parts_out = []
+    for name, rows in part_rows:
+        entry = {"name": name, "rows": rows}
+        part = next((p for p in schema.parts if p.name == name), None)
+        if part:
+            entry["bit_range"] = part.bit_range
+            entry["label"] = part.label
+        parts_out.append(entry)
+    return json.dumps({
+        "type":    schema.type,
+        "address": schema.input,
+        "parts":   parts_out,
+    }, ensure_ascii=False)
+
+# ── Input handling ────────────────────────────────────────────────────────────
+
+def parse_addr(raw, addr_type="auto"):
+    """Validate a raw address string. Returns (normalised_str, resolved_type)"""
+    raw = raw.strip()
+    if addr_type == "auto":
+        addr_type = detect_type(raw)
+    # full parse to validate
+    addr_to_nibbles(raw, addr_type)
+    return raw, addr_type
+
+
+def random_addr(addr_type="ipv6"):
+    """Generate a random address string of the given type"""
+    if addr_type == "ipv6":
+        return str(ipaddress.IPv6Address(random.getrandbits(128)))
+    if addr_type == "ipv4":
+        return str(ipaddress.IPv4Address(random.getrandbits(32)))
+    if addr_type == "mac":
+        octets = [random.randint(0, 255) for _ in range(6)]
+        return ":".join(f"{b:02x}" for b in octets)
+    raise ValueError(f"Cannot generate random address for type: {addr_type!r}")
+
+
+# ── Core render pipeline ──────────────────────────────────────────────────────
+
+def render_address(addr, addr_type="auto", charset=CHARSET_DEFAULT, invert=False,
+            scale=1, layout="auto", width="auto", output="text", show_bits=False):
+    schema = addr_to_nibbles(addr, addr_type)
+    atype = schema.type
+
+    # Resolve layout
+    if layout == "auto":
+        layout = "split" if len(schema.parts) == 2 else "grid"
+
+    # Resolve width
+    if width == "auto":
+        if layout == "inline":
+            total_bits = len(schema.nibbles) * 4
+            width = total_bits // 2
+        elif layout == "barcode":
+            total_bits = len(schema.nibbles) * 4
+            width = max(total_bits // 4, 1)
+        else:
+            width = DEFAULT_WIDTH[atype]
+
+    if show_bits:
+        for part in schema.parts:
+            bits = nibbles_to_bits(part.nibbles)
+            print(f"{part.name} bits: {''.join(str(b) for b in bits)}", file=sys.stderr)
+
+    # inline/barcode, render all nibbles as one block
+    if layout in ("inline", "barcode"):
+        rows = render_grid(schema.nibbles, width, charset, invert=invert)
+        part_rows = [("all", rows)]
+    else:
+        part_rows = []
+        for part in schema.parts:
+            rows = render_grid(part.nibbles, width, charset, invert=invert)
+            part_rows.append((part.name, rows))
+
+    if output == "json":
+        return format_json(schema, part_rows)
+    else:
+        return format_text(part_rows, layout, scale)

hexicon-0.1.0/src/hexicon/cli.py

@@ -0,0 +1,145 @@
+"""Command-line interface for hexicon"""
+
+import argparse
+import io
+import sys
+
+from hexicon._core import (
+    LAYOUT_CHOICES,
+    OUTPUT_CHOICES,
+    TYPE_CHOICES,
+    parse_addr,
+    random_addr,
+    render_address,
+)
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="hexicon",
+        description="Render a human-readable identicon for an IPv6 address.",
+    )
+
+    src = parser.add_mutually_exclusive_group(required=True)
+    src.add_argument(
+        "address", nargs="?", metavar="ADDRESS",
+        help="Address to render (IPv6, IPv4, or MAC). Use '-' to read from stdin.",
+    )
+    src.add_argument(
+        "--random", action="store_true",
+        help="Generate and render a random address.",
+    )
+
+    parser.add_argument(
+        "--type", choices=TYPE_CHOICES, default="auto",
+        dest="addr_type",
+        help="Address type (default: auto-detect).",
+    )
+
+    parser.add_argument(
+        "--invert", action="store_true",
+        help="Invert filled and empty pixels.",
+    )
+    parser.add_argument(
+        "--scale", type=int, default=1, metavar="N",
+        help="Repeat each row N times (default: 1).",
+    )
+    parser.add_argument(
+        "--layout", choices=LAYOUT_CHOICES,
+        default="auto",
+        help="Layout mode (default: auto). grid=stacked, split=side-by-side, "
+             "inline=single row, barcode=wide strip.",
+    )
+    parser.add_argument(
+        "--width", default="auto", metavar="N|auto",
+        help="Bits per scanline row (default: auto, uses type-appropriate width).",
+    )
+    parser.add_argument(
+        "--output", choices=OUTPUT_CHOICES, default="text",
+        help="Output format (default: text).",
+    )
+    parser.add_argument(
+        "--no-newline", action="store_true",
+        help="Suppress trailing newline (useful for piping).",
+    )
+    parser.add_argument(
+        "--show-bits", action="store_true",
+        help="Print raw nibble values to stderr before rendering.",
+    )
+
+    return parser
+
+
+def emit(text, no_newline=False):
+    if no_newline:
+        print(text, end="")
+    else:
+        print(text)
+
+
+def main():
+    # ensure UTF8 output for cp1252 terminals
+    if isinstance(sys.stdout, io.TextIOWrapper):
+        sys.stdout.reconfigure(encoding="utf-8")
+    if isinstance(sys.stderr, io.TextIOWrapper):
+        sys.stderr.reconfigure(encoding="utf-8")
+
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.width != "auto":
+        try:
+            width = int(args.width)
+        except ValueError:
+            parser.error("--width must be a positive integer or 'auto'")
+        if width < 1:
+            parser.error("--width must be a positive integer or 'auto'")
+    else:
+        width = "auto"
+
+    opts = dict(
+        addr_type = args.addr_type,
+        invert    = args.invert,
+        scale     = args.scale,
+        layout    = args.layout,
+        width     = width,
+        output    = args.output,
+        show_bits = args.show_bits,
+    )
+
+    if args.scale < 1:
+        parser.error("--scale must be a positive integer")
+
+    if args.random:
+        addr = random_addr(args.addr_type if args.addr_type != "auto" else "ipv6")
+        if args.output == "text":
+            print(f"# {addr}", file=sys.stderr)
+        result = render_address(addr, **opts)
+        emit(result, args.no_newline)
+        return
+
+    # Stdin batch mode
+    if args.address == "-":
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                addr, _ = parse_addr(line, args.addr_type)
+            except ValueError as e:
+                print(f"hexicon: {e}", file=sys.stderr)
+                continue
+            result = render_address(addr, **opts)
+            emit(result, args.no_newline)
+            if not args.no_newline:
+                print()          # blank separator between addresses
+        return
+
+    # normal single address mode
+    try:
+        addr, _ = parse_addr(args.address, args.addr_type)
+    except ValueError as e:
+        parser.error(str(e))
+
+    result = render_address(addr, **opts)
+    emit(result, args.no_newline)

hexicon-0.1.0/tests/test_hexicon.py

@@ -0,0 +1,313 @@
+"""Edge-case test battery for hexicon."""
+
+import json
+import unittest
+
+from hexicon import (
+    addr_to_nibbles,
+    detect_type,
+    int_to_nibbles,
+    render_address,
+    random_addr,
+    render_grid,
+    CHARSET_DEFAULT,
+    DEFAULT_WIDTH,
+    LAYOUT_CHOICES,
+    TYPE_CHOICES,
+    OUTPUT_CHOICES,
+)
+
+
+# ── Schema & detection ────────────────────────────────────────────────────────
+
+class TestDetectType(unittest.TestCase):
+    def test_ipv6_full(self):
+        self.assertEqual(detect_type("2001:0db8::1"), "ipv6")
+
+    def test_ipv6_loopback(self):
+        self.assertEqual(detect_type("::1"), "ipv6")
+
+    def test_ipv6_all_zeros(self):
+        self.assertEqual(detect_type("::"), "ipv6")
+
+    def test_ipv4_basic(self):
+        self.assertEqual(detect_type("192.168.0.1"), "ipv4")
+
+    def test_mac_colon(self):
+        self.assertEqual(detect_type("aa:bb:cc:dd:ee:ff"), "mac")
+
+    def test_mac_hyphen(self):
+        self.assertEqual(detect_type("AA-BB-CC-DD-EE-FF"), "mac")
+
+    def test_ipv4_mapped_ipv6_is_ipv6(self):
+        # ::ffff:192.168.0.1 should be detected as IPv6, *not* IPv4
+        self.assertEqual(detect_type("::ffff:192.168.0.1"), "ipv6")
+
+    def test_garbage_raises(self):
+        with self.assertRaises(ValueError):
+            detect_type("not-an-address")
+
+
+# ── IPv6 edge cases ──────────────────────────────────────────────────────────
+
+class TestIPv6Nibbles(unittest.TestCase):
+    def test_compressed_loopback(self):
+        schema = addr_to_nibbles("::1")
+        self.assertEqual(schema.type, "ipv6")
+        self.assertEqual(len(schema.nibbles), 32)
+        # Last nibble should be 1, rest 0
+        self.assertEqual(schema.nibbles[-1], 1)
+        self.assertTrue(all(n == 0 for n in schema.nibbles[:-1]))
+
+    def test_compressed_prefix(self):
+        schema = addr_to_nibbles("fe80::1")
+        self.assertEqual(len(schema.nibbles), 32)
+        self.assertEqual(schema.nibbles[:4], [0xf, 0xe, 8, 0])
+
+    def test_all_zeros(self):
+        schema = addr_to_nibbles("::")
+        self.assertEqual(schema.nibbles, [0] * 32)
+
+    def test_all_ones(self):
+        schema = addr_to_nibbles("ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff")
+        self.assertEqual(schema.nibbles, [0xf] * 32)
+
+    def test_ipv4_mapped(self):
+        """::ffff:192.168.0.1 is a valid IPv6 address with 32 nibbles."""
+        schema = addr_to_nibbles("::ffff:192.168.0.1")
+        self.assertEqual(schema.type, "ipv6")
+        self.assertEqual(len(schema.nibbles), 32)
+        # The last 8 nibbles encode 192.168.0.1 = c0.a8.00.01
+        self.assertEqual(schema.nibbles[-8:], [0xc, 0x0, 0xa, 0x8, 0x0, 0x0, 0x0, 0x1])
+
+    def test_parts_metadata(self):
+        schema = addr_to_nibbles("2001:db8::1")
+        net = schema.parts[0]
+        host = schema.parts[1]
+        self.assertEqual(net.bit_range, [0, 64])
+        self.assertEqual(net.label, "network")
+        self.assertEqual(host.bit_range, [64, 128])
+        self.assertEqual(host.label, "host")
+
+
+# ── IPv4 edge cases ──────────────────────────────────────────────────────────
+
+class TestIPv4Nibbles(unittest.TestCase):
+    def test_basic(self):
+        schema = addr_to_nibbles("192.168.0.1")
+        self.assertEqual(schema.type, "ipv4")
+        self.assertEqual(len(schema.nibbles), 8)
+        # 192 = 0xC0, 168 = 0xA8, 0 = 0x00, 1 = 0x01
+        self.assertEqual(schema.nibbles, [0xc, 0x0, 0xa, 0x8, 0x0, 0x0, 0x0, 0x1])
+
+    def test_all_zeros(self):
+        schema = addr_to_nibbles("0.0.0.0")
+        self.assertEqual(schema.nibbles, [0] * 8)
+
+    def test_all_max(self):
+        schema = addr_to_nibbles("255.255.255.255")
+        self.assertEqual(schema.nibbles, [0xf] * 8)
+
+    def test_four_parts(self):
+        schema = addr_to_nibbles("10.20.30.40")
+        self.assertEqual(len(schema.parts), 4)
+        for i, part in enumerate(schema.parts):
+            self.assertEqual(part.name, f"octet{i}")
+            self.assertEqual(len(part.nibbles), 2)
+            self.assertEqual(part.bit_range, [i * 8, (i + 1) * 8])
+            self.assertEqual(part.label, f"octet {i}")
+
+
+# ── MAC edge cases ───────────────────────────────────────────────────────────
+
+class TestMACNibbles(unittest.TestCase):
+    def test_lowercase(self):
+        schema = addr_to_nibbles("aa:bb:cc:dd:ee:ff")
+        self.assertEqual(schema.type, "mac")
+        self.assertEqual(len(schema.nibbles), 12)
+        self.assertEqual(schema.input, "aa:bb:cc:dd:ee:ff")
+
+    def test_uppercase(self):
+        schema = addr_to_nibbles("AA:BB:CC:DD:EE:FF")
+        self.assertEqual(schema.input, "aa:bb:cc:dd:ee:ff")  # normalised
+
+    def test_mixed_case(self):
+        schema = addr_to_nibbles("Aa:bB:Cc:dD:Ee:fF")
+        self.assertEqual(schema.input, "aa:bb:cc:dd:ee:ff")
+
+    def test_hyphen_delimiter(self):
+        schema = addr_to_nibbles("11-22-33-44-55-66")
+        self.assertEqual(schema.type, "mac")
+        self.assertEqual(schema.input, "11:22:33:44:55:66")
+
+    def test_all_zeros(self):
+        schema = addr_to_nibbles("00:00:00:00:00:00")
+        self.assertEqual(schema.nibbles, [0] * 12)
+
+    def test_all_max(self):
+        schema = addr_to_nibbles("ff:ff:ff:ff:ff:ff")
+        self.assertEqual(schema.nibbles, [0xf] * 12)
+
+    def test_parts_metadata(self):
+        schema = addr_to_nibbles("aa:bb:cc:dd:ee:ff")
+        oui = schema.parts[0]
+        nic = schema.parts[1]
+        self.assertEqual(oui.bit_range, [0, 24])
+        self.assertEqual(oui.label, "OUI")
+        self.assertEqual(nic.bit_range, [24, 48])
+        self.assertEqual(nic.label, "NIC")
+
+
+# ── Width flag ───────────────────────────────────────────────────────────────
+
+class TestWidthFlag(unittest.TestCase):
+    def test_default_width_ipv6(self):
+        result = render_address("::1", width="auto")
+        lines = result.strip().split("\n")
+        self.assertTrue(len(lines) > 0)
+
+    def test_explicit_width_1(self):
+        addr = "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"
+        result = render_address(addr, width=1, layout="grid")
+        lines = result.split("\n")
+        self.assertEqual(len(lines), 32)
+        for line in lines:
+            self.assertEqual(len(line), 2)
+
+    def test_explicit_width_full_row(self):
+        addr = "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"
+        result = render_address(addr, width=16, layout="grid")
+        lines = result.split("\n")
+        self.assertEqual(len(lines), 2)  # net part + host part
+        for line in lines:
+            self.assertEqual(len(line), 32)
+
+    def test_width_ipv4(self):
+        result = render_address("10.0.0.1", width=2, layout="grid")
+        lines = result.strip().split("\n")
+        self.assertEqual(len(lines), 4)
+
+
+# ── Layout modes ─────────────────────────────────────────────────────────────
+
+class TestLayoutModes(unittest.TestCase):
+    def test_grid_stacks_parts(self):
+        result = render_address("2001:db8::1", layout="grid")
+        lines = result.strip().split("\n")
+        # grid: net 4 rows + host 4 rows = 8 rows
+        self.assertEqual(len(lines), 8)
+
+    def test_split_side_by_side(self):
+        result = render_address("2001:db8::1", layout="split")
+        lines = result.strip().split("\n")
+        # split: 4 rows, each is  net_row + "  " + host_row
+        self.assertEqual(len(lines), 4)
+        for line in lines:
+            self.assertIn("  ", line)
+
+    def test_inline_single_row(self):
+        addr = "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"
+        result = render_address(addr, layout="inline")
+        lines = result.split("\n")
+        # inline: all 32 nibbles in one row → 64 chars
+        self.assertEqual(len(lines), 1)
+        self.assertEqual(len(lines[0]), 64)
+
+    def test_barcode_two_rows(self):
+        addr = "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"
+        result = render_address(addr, layout="barcode")
+        lines = result.split("\n")
+        # barcode: width = 32//2 = 16 → 2 rows of 32 chars each
+        self.assertEqual(len(lines), 2)
+        self.assertEqual(len(lines[0]), 32)
+
+    def test_auto_ipv6_is_split(self):
+        r_auto = render_address("::1", layout="auto")
+        r_split = render_address("::1", layout="split")
+        self.assertEqual(r_auto, r_split)
+
+    def test_auto_ipv4_is_split(self):
+        """IPv4 also has >1 parts, but split only works for exactly 2 parts.
+        With 4 parts auto resolves to grid (since len(parts) != 2)."""
+        r_auto  = render_address("10.0.0.1", layout="auto")
+        r_grid  = render_address("10.0.0.1", layout="grid")
+        # IPv4 has 4 parts so auto → grid (not split)
+        self.assertEqual(r_auto, r_grid)
+
+    def test_auto_mac_is_split(self):
+        r_auto  = render_address("aa:bb:cc:dd:ee:ff", layout="auto")
+        r_split = render_address("aa:bb:cc:dd:ee:ff", layout="split")
+        self.assertEqual(r_auto, r_split)
+
+    def test_split_falls_back_for_4_parts(self):
+        """If layout=split but there are 4 parts, format_text stacks them."""
+        result = render_address("10.0.0.1", layout="split")
+        lines = result.strip().split("\n")
+        # 4 parts with width=4: each has 2 nib / 4 = 1 row → 4 rows stacked
+        self.assertEqual(len(lines), 4)
+
+
+# ── JSON output ──────────────────────────────────────────────────────────────
+
+class TestJSONOutput(unittest.TestCase):
+    def test_ipv6_json_has_metadata(self):
+        raw = render_address("2001:db8::1", output="json")
+        data = json.loads(raw)
+        self.assertEqual(data["type"], "ipv6")
+        self.assertIn("parts", data)
+        for part in data["parts"]:
+            self.assertIn("bit_range", part)
+            self.assertIn("label", part)
+
+    def test_ipv4_json_has_metadata(self):
+        raw = render_address("10.0.0.1", output="json")
+        data = json.loads(raw)
+        self.assertEqual(data["type"], "ipv4")
+        self.assertEqual(len(data["parts"]), 4)
+        for i, part in enumerate(data["parts"]):
+            self.assertEqual(part["bit_range"], [i * 8, (i + 1) * 8])
+
+    def test_mac_json_has_metadata(self):
+        raw = render_address("aa:bb:cc:dd:ee:ff", output="json")
+        data = json.loads(raw)
+        self.assertEqual(data["type"], "mac")
+        self.assertEqual(data["parts"][0]["label"], "OUI")
+        self.assertEqual(data["parts"][1]["label"], "NIC")
+
+
+# ── Scale stress ─────────────────────────────────────────────────────────────
+
+class TestScaleStress(unittest.TestCase):
+    def test_large_scale(self):
+        """--scale 100 should not crash and should multiply rows."""
+        result = render_address("::1", scale=100)
+        lines = result.split("\n")
+        # split layout: 4 visual rows * 100 = 400 lines
+        self.assertEqual(len(lines), 400)
+
+    def test_scale_1(self):
+        r1 = render_address("::1", scale=1)
+        self.assertEqual(len(r1.split("\n")), 4)
+
+
+# ── Random address generation ───────────────────────────────────────────────
+
+class TestRandomAddr(unittest.TestCase):
+    def test_random_ipv6_valid(self):
+        addr = random_addr("ipv6")
+        schema = addr_to_nibbles(addr, "ipv6")
+        self.assertEqual(len(schema.nibbles), 32)
+
+    def test_random_ipv4_valid(self):
+        addr = random_addr("ipv4")
+        schema = addr_to_nibbles(addr, "ipv4")
+        self.assertEqual(len(schema.nibbles), 8)
+
+    def test_random_mac_valid(self):
+        addr = random_addr("mac")
+        schema = addr_to_nibbles(addr, "mac")
+        self.assertEqual(len(schema.nibbles), 12)
+
+
+if __name__ == "__main__":
+    unittest.main()