hexicon 0.1.0__py3-none-any.whl

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/__main__.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+hexicon/__init__.py,sha256=8tf51ciIPo3aRoGHZJqsHiFqAqQXebD99PmW67K3UxI,784
+hexicon/__main__.py,sha256=FSvg-4kY7YZpcDHpO2O1qfhrxd71X8eHYHY4figN02s,91
+hexicon/_core.py,sha256=YzOu8JoYBnKiA9s47WExFttgHd0XUAKuP5cV6IBUoRo,10076
+hexicon/cli.py,sha256=OgJJ6xTRXVWXA3S8gbE-4HWU7zc2e8wZM5TRhzi0kec,4165
+hexicon-0.1.0.dist-info/METADATA,sha256=BI4CZ9ru2ADlUocpQh_5GM4jQpX2zWdqfyM2IfJTNEo,4296
+hexicon-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hexicon-0.1.0.dist-info/entry_points.txt,sha256=rcrUa5lFjMpBoNEpw5FLRKjuxM4fDoMQTgoVJs9Qa_s,45
+hexicon-0.1.0.dist-info/licenses/LICENSE,sha256=6GMdiHGZ5zQ6lGYe_XIV1blfmJkndxotU7HgbGxETVM,1063
+hexicon-0.1.0.dist-info/RECORD,,

hexicon-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hexicon-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hexicon = hexicon.cli:main

hexicon-0.1.0.dist-info/licenses/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.