Metadata-Version: 2.4
Name: mac-vendors-client
Version: 1.0.0
Summary: Lightweight offline MAC -> vendor lookup against an exported SQLite database
Project-URL: Homepage, https://github.com/mac-vendors/mac-vendors-client
Project-URL: Repository, https://github.com/mac-vendors/mac-vendors-client.git
Author-email: LizardSystems <support@lizardsystems.com>
License-Expression: MIT
Keywords: ieee,lookup,mac-address,offline,oui,vendor
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.12
Provides-Extra: dev
Requires-Dist: mypy>=1.13.0; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# mac-vendors-client

Lightweight, **offline** MAC address -> vendor lookups against a pre-built
SQLite database export.

- **Zero dependencies** - reads the export via the standard library `sqlite3`.
- **Fast** - range/bits index lookup, no network, no per-call cost.
- **Read-only** - opens the export file read-only; never modifies it.

Use it when you have a downloaded SQLite export and want fast, local lookups
with no network calls. For live queries against the hosted API, use the online
SDK ([`mac-vendors-sdk`](https://pypi.org/project/mac-vendors-sdk/)) instead.

## Install

```bash
pip install mac-vendors-client
```

## Usage

```python
from mac_vendors_client import MacVendorsClient

with MacVendorsClient("vendors.db") as client:
    match = client.lookup("00:50:56:AA:BB:CC")
    if match:
        print(match.organization_name)   # "VMware, Inc."
        print(match.assignment, match.bits)

    # Name only
    name = client.lookup_name("00-50-56-aa-bb-cc")

    # Batch (invalid entries map to None instead of raising)
    results = client.lookup_batch(["0050.56AA.BBCC", "FF:FF:FF:00:00:00"])

    # Export metadata
    info = client.info()
    print(info.exported_at, info.total_records)
```

MAC input accepts any common format (`:`/`-`/`.` separators or bare hex), and
a shorter prefix such as a 6-hex OUI. The most specific (largest-`bits`) match
wins when prefixes overlap (e.g. an MA-S assignment inside an MA-L block).

## The export contract

The export is a SQLite database with this schema:

```sql
CREATE TABLE mac_addresses (
    id INTEGER PRIMARY KEY,
    assignment TEXT NOT NULL,
    organization_name TEXT,
    organization_address TEXT,
    range_begin INTEGER NOT NULL,   -- 48-bit MAC range start
    range_end   INTEGER NOT NULL,   -- 48-bit MAC range end
    bits INTEGER NOT NULL           -- 24 / 28 / 36
);
CREATE TABLE metadata (key TEXT PRIMARY KEY, value TEXT);  -- updated_at, exported_at, total_records
```

A lookup resolves a MAC `M` to the row where
`range_begin <= int(M) <= range_end`, ordered by `bits DESC` (most specific
first).

## License

MIT
