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
