macadress 1.0.0__tar.gz

macadress-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store

macadress-1.0.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this package are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-09-02
+
+### Added
+
+- `Client` and `AsyncClient` with `vendor()`, `lookup()`, `batch()`, `search_vendors()`, `health()` and a raw `request()` escape hatch.
+- Typed dataclass results: `MacResult`, `BatchItem`, `Device`, `Meta`, `VendorBlock`, `VendorSearchResult`, each with a `raw` dict and (on `MacResult`) a `get("dotted.path")` accessor.
+- `str` enums (`BlockType`, `TransmissionType`, `AdministrationType`, `RandomizationConfidence`, `DeviceCategory`); unknown values pass through as plain strings.
+- Exception hierarchy under `MacadressError`: `APIError`, `InvalidMACError`, `AuthenticationError`, `RateLimitError` (`retry_after`), `QuotaExceededError`, `TransportError`, `ConfigurationError`.
+- One runtime dependency, `httpx`. `py.typed`; ships type information.
+
+[Unreleased]: https://github.com/sapisos/macadress-python/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/sapisos/macadress-python/releases/tag/v1.0.0

macadress-1.0.0/LICENSE

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

macadress-1.0.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.5
+Name: macadress
+Version: 1.0.0
+Summary: Official Python client for the macadress.com MAC address and OUI vendor lookup API.
+Project-URL: Homepage, https://macadress.com
+Project-URL: Documentation, https://macadress.com/docs
+Project-URL: Source, https://github.com/sapisos/macadress-python
+Project-URL: Issues, https://github.com/sapisos/macadress-python/issues
+Project-URL: Changelog, https://github.com/sapisos/macadress-python/blob/main/CHANGELOG.md
+Author: ApisOS FZE
+License: MIT
+License-File: LICENSE
+Keywords: api-client,ieee,mac-address,mac-vendor,macadress,oui,sdk,vendor-lookup
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Internet
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# macadress
+
+Official Python client for the [macadress.com](https://macadress.com) MAC address
+and OUI vendor lookup API.
+
+- Vendor name, OUI, IEEE block, country, address type, EUI-64 / IPv6 link-local, randomization confidence, device guess
+- Keyless vendor-name lookup, plus keyed single / batch / directory-search calls
+- Typed dataclass results with a `raw` escape hatch, typed exceptions per failure mode
+- Sync `Client` and async `AsyncClient` from the same API, one dependency (`httpx`)
+
+```python
+from macadress import Client
+
+mac = Client("mk_live_xxx")
+
+mac.vendor("00:03:93:AB:12:34")            # "Apple, Inc."   (no API key required)
+mac.lookup("00:03:93:AB:12:34").country    # "US"
+```
+
+## Install
+
+```bash
+pip install macadress
+```
+
+Requires Python 3.10+.
+
+## Getting a key
+
+`vendor()` needs no key. Everything else does. A free key (1,000 lookups a day) is
+instant at [macadress.com/signup](https://macadress.com/signup); see
+[pricing](https://macadress.com/pricing) for more.
+
+## Usage
+
+### Create a client
+
+```python
+from macadress import Client
+
+mac = Client("mk_live_xxx")
+
+# keyless: only vendor() will work
+anon = Client()
+
+# options
+mac = Client(
+    "mk_live_xxx",
+    base_url="https://api.macadress.com",   # change only for a self-hosted deployment
+    timeout=10.0,
+    headers={"X-Trace": "my-app"},
+)
+
+# reuse / close
+with Client("mk_live_xxx") as mac:
+    ...
+```
+
+### `vendor()` - name only, no key
+
+Returns `None` when the address is valid but has no vendor to report
+(unregistered, private, or locally administered / randomized).
+
+```python
+mac.vendor("00:03:93:AB:12:34")   # "Apple, Inc."
+mac.vendor("02:1a:2b:3c:4d:5e")   # None
+```
+
+`:`, `-`, `.` and space grouping are all accepted, as is a bare 12-hex string.
+
+### `lookup()` - full analysis
+
+```python
+r = mac.lookup("3C:22:FB:12:34:56")
+
+r.organization              # str | None
+r.vendor_lookup_reliable    # bool  (False for a private block / LAA)
+r.oui                       # "3C:22:FB"
+r.matched_prefix            # full matched block at its real width
+r.block_type                # BlockType.MA_L (compares equal to "MA-L")
+r.country                   # "US" | None
+r.administration_type       # AdministrationType.UNIVERSALLY_ADMINISTERED | ...
+r.potentially_randomized    # bool
+r.randomization_confidence  # RandomizationConfidence.NONE | POSSIBLE | LIKELY
+r.eui64                     # "3E:22:FB:FF:FE:12:34:56" | None
+r.ipv6_link_local           # "fe80::3e22:fbff:fe12:3456" | None
+r.device.category           # DeviceCategory.UNKNOWN (usually)
+r.explanation               # plain-English summary
+r.meta.database_version     # "2026-08-30"
+```
+
+Any field not covered by an attribute is still reachable:
+
+```python
+r.get("vendor_location.city")   # dotted path into r.raw, default None
+r.raw                           # the decoded payload as given
+```
+
+### `batch()` - up to 100 at once
+
+Results come back in input order; check each item.
+
+```python
+for item in mac.batch(["00:03:93:00:00:00", "3C:22:FB:00:00:00", "bad"]):
+    if item.failed:
+        print(item.input, "->", item.error)
+    else:
+        print(item.input, "->", item.organization)
+```
+
+Raises `ValueError` (no request made) if the iterable is empty or has more than
+`macadress.MAX_BATCH_SIZE` (100) entries.
+
+### `search_vendors()` - the directory
+
+```python
+result = mac.search_vendors("Cisco", country="US", limit=20)
+
+result.total   # total matches, ignoring the limit
+for block in result:
+    print(block.block_type, block.organization, block.country)
+```
+
+### `health()`
+
+```python
+mac.health()   # bool, keyless, uncounted; a transport failure is False
+```
+
+### Async
+
+`AsyncClient` mirrors `Client` method for method:
+
+```python
+import asyncio
+from macadress import AsyncClient
+
+async def main():
+    async with AsyncClient("mk_live_xxx") as mac:
+        print(await mac.vendor("00:03:93:AB:12:34"))
+        r = await mac.lookup("3C:22:FB:12:34:56")
+        print(r.organization)
+
+asyncio.run(main())
+```
+
+## Errors
+
+Every failure is a `MacadressError`.
+
+| Class | When |
+|---|---|
+| `InvalidMACError` | HTTP 400, the input did not parse |
+| `AuthenticationError` | HTTP 401, missing or invalid API key |
+| `RateLimitError` | HTTP 429, per-minute rate exceeded. `.retry_after` (seconds) when sent |
+| `QuotaExceededError` | HTTP 429, billing-cycle quota spent. Subclass of `RateLimitError` |
+| `APIError` | any other 4xx/5xx, or an unreadable response |
+| `TransportError` | never reached the API: DNS, connection, TLS, timeout (`__cause__` is the httpx error) |
+| `ConfigurationError` | bad client options (raised before any request) |
+
+Each carries `.status_code`, `.request_id` and `.body` where available.
+
+```python
+from macadress import Client, RateLimitError, MacadressError
+
+try:
+    r = mac.lookup(value)
+except RateLimitError as exc:
+    time.sleep(exc.retry_after or 5)
+except MacadressError as exc:
+    log.warning("macadress %s: %s (%s)", exc.status_code, exc, exc.request_id)
+```
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+
+pytest
+mypy
+ruff check .
+```
+
+The version lives in `src/macadress/_version.py`; keep `CHANGELOG.md` and the
+release tag in step with it.
+
+## Links
+
+- API reference: <https://macadress.com/docs>
+- Issues: <https://github.com/sapisos/macadress-python/issues>
+
+## License
+
+MIT, see [LICENSE](LICENSE). A product of [ApisOS FZE](https://apisos.com).

macadress-1.0.0/README.md

@@ -0,0 +1,195 @@
+# macadress
+
+Official Python client for the [macadress.com](https://macadress.com) MAC address
+and OUI vendor lookup API.
+
+- Vendor name, OUI, IEEE block, country, address type, EUI-64 / IPv6 link-local, randomization confidence, device guess
+- Keyless vendor-name lookup, plus keyed single / batch / directory-search calls
+- Typed dataclass results with a `raw` escape hatch, typed exceptions per failure mode
+- Sync `Client` and async `AsyncClient` from the same API, one dependency (`httpx`)
+
+```python
+from macadress import Client
+
+mac = Client("mk_live_xxx")
+
+mac.vendor("00:03:93:AB:12:34")            # "Apple, Inc."   (no API key required)
+mac.lookup("00:03:93:AB:12:34").country    # "US"
+```
+
+## Install
+
+```bash
+pip install macadress
+```
+
+Requires Python 3.10+.
+
+## Getting a key
+
+`vendor()` needs no key. Everything else does. A free key (1,000 lookups a day) is
+instant at [macadress.com/signup](https://macadress.com/signup); see
+[pricing](https://macadress.com/pricing) for more.
+
+## Usage
+
+### Create a client
+
+```python
+from macadress import Client
+
+mac = Client("mk_live_xxx")
+
+# keyless: only vendor() will work
+anon = Client()
+
+# options
+mac = Client(
+    "mk_live_xxx",
+    base_url="https://api.macadress.com",   # change only for a self-hosted deployment
+    timeout=10.0,
+    headers={"X-Trace": "my-app"},
+)
+
+# reuse / close
+with Client("mk_live_xxx") as mac:
+    ...
+```
+
+### `vendor()` - name only, no key
+
+Returns `None` when the address is valid but has no vendor to report
+(unregistered, private, or locally administered / randomized).
+
+```python
+mac.vendor("00:03:93:AB:12:34")   # "Apple, Inc."
+mac.vendor("02:1a:2b:3c:4d:5e")   # None
+```
+
+`:`, `-`, `.` and space grouping are all accepted, as is a bare 12-hex string.
+
+### `lookup()` - full analysis
+
+```python
+r = mac.lookup("3C:22:FB:12:34:56")
+
+r.organization              # str | None
+r.vendor_lookup_reliable    # bool  (False for a private block / LAA)
+r.oui                       # "3C:22:FB"
+r.matched_prefix            # full matched block at its real width
+r.block_type                # BlockType.MA_L (compares equal to "MA-L")
+r.country                   # "US" | None
+r.administration_type       # AdministrationType.UNIVERSALLY_ADMINISTERED | ...
+r.potentially_randomized    # bool
+r.randomization_confidence  # RandomizationConfidence.NONE | POSSIBLE | LIKELY
+r.eui64                     # "3E:22:FB:FF:FE:12:34:56" | None
+r.ipv6_link_local           # "fe80::3e22:fbff:fe12:3456" | None
+r.device.category           # DeviceCategory.UNKNOWN (usually)
+r.explanation               # plain-English summary
+r.meta.database_version     # "2026-08-30"
+```
+
+Any field not covered by an attribute is still reachable:
+
+```python
+r.get("vendor_location.city")   # dotted path into r.raw, default None
+r.raw                           # the decoded payload as given
+```
+
+### `batch()` - up to 100 at once
+
+Results come back in input order; check each item.
+
+```python
+for item in mac.batch(["00:03:93:00:00:00", "3C:22:FB:00:00:00", "bad"]):
+    if item.failed:
+        print(item.input, "->", item.error)
+    else:
+        print(item.input, "->", item.organization)
+```
+
+Raises `ValueError` (no request made) if the iterable is empty or has more than
+`macadress.MAX_BATCH_SIZE` (100) entries.
+
+### `search_vendors()` - the directory
+
+```python
+result = mac.search_vendors("Cisco", country="US", limit=20)
+
+result.total   # total matches, ignoring the limit
+for block in result:
+    print(block.block_type, block.organization, block.country)
+```
+
+### `health()`
+
+```python
+mac.health()   # bool, keyless, uncounted; a transport failure is False
+```
+
+### Async
+
+`AsyncClient` mirrors `Client` method for method:
+
+```python
+import asyncio
+from macadress import AsyncClient
+
+async def main():
+    async with AsyncClient("mk_live_xxx") as mac:
+        print(await mac.vendor("00:03:93:AB:12:34"))
+        r = await mac.lookup("3C:22:FB:12:34:56")
+        print(r.organization)
+
+asyncio.run(main())
+```
+
+## Errors
+
+Every failure is a `MacadressError`.
+
+| Class | When |
+|---|---|
+| `InvalidMACError` | HTTP 400, the input did not parse |
+| `AuthenticationError` | HTTP 401, missing or invalid API key |
+| `RateLimitError` | HTTP 429, per-minute rate exceeded. `.retry_after` (seconds) when sent |
+| `QuotaExceededError` | HTTP 429, billing-cycle quota spent. Subclass of `RateLimitError` |
+| `APIError` | any other 4xx/5xx, or an unreadable response |
+| `TransportError` | never reached the API: DNS, connection, TLS, timeout (`__cause__` is the httpx error) |
+| `ConfigurationError` | bad client options (raised before any request) |
+
+Each carries `.status_code`, `.request_id` and `.body` where available.
+
+```python
+from macadress import Client, RateLimitError, MacadressError
+
+try:
+    r = mac.lookup(value)
+except RateLimitError as exc:
+    time.sleep(exc.retry_after or 5)
+except MacadressError as exc:
+    log.warning("macadress %s: %s (%s)", exc.status_code, exc, exc.request_id)
+```
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+
+pytest
+mypy
+ruff check .
+```
+
+The version lives in `src/macadress/_version.py`; keep `CHANGELOG.md` and the
+release tag in step with it.
+
+## Links
+
+- API reference: <https://macadress.com/docs>
+- Issues: <https://github.com/sapisos/macadress-python/issues>
+
+## License
+
+MIT, see [LICENSE](LICENSE). A product of [ApisOS FZE](https://apisos.com).

macadress-1.0.0/examples/01_vendor_name.py

@@ -0,0 +1,12 @@
+"""Vendor name only, no API key. Run: python examples/01_vendor_name.py 00:03:93:AB:12:34"""
+
+import sys
+
+from macadress import Client
+
+mac = sys.argv[1] if len(sys.argv) > 1 else "00:03:93:AB:12:34"
+
+with Client() as client:
+    name = client.vendor(mac)
+
+print(name if name is not None else f"{mac}: no vendor on record")

macadress-1.0.0/examples/02_full_lookup.py

@@ -0,0 +1,30 @@
+"""Full analysis of one address. Needs a key.
+
+Run: MACADRESS_API_KEY=mk_live_xxx python examples/02_full_lookup.py 3C:22:FB:00:00:00
+"""
+
+import os
+import sys
+
+from macadress import Client
+
+mac = sys.argv[1] if len(sys.argv) > 1 else "3C:22:FB:00:00:00"
+
+with Client(os.environ.get("MACADRESS_API_KEY", "")) as client:
+    r = client.lookup(mac)
+
+print("organization:", r.organization)
+print("oui:", r.oui)
+print("block_type:", r.block_type)
+print("country:", r.country)
+print("reliable:", r.vendor_lookup_reliable)
+print("administration:", r.administration_type)
+print("randomization:", r.randomization_confidence)
+print("eui64:", r.eui64)
+print("device:", r.device.category)
+print("database_version:", r.meta.database_version)
+print()
+print(r.explanation)
+
+# anything without a typed attribute is still reachable
+print(r.get("vendor_location.city"))

macadress-1.0.0/examples/03_batch.py

@@ -0,0 +1,19 @@
+"""Up to 100 addresses in one request. Needs a key.
+
+Run: MACADRESS_API_KEY=mk_live_xxx python examples/03_batch.py
+"""
+
+import os
+
+from macadress import Client
+
+with Client(os.environ.get("MACADRESS_API_KEY", "")) as client:
+    items = client.batch(
+        ["00:03:93:00:00:00", "3C:22:FB:00:00:00", "AC-DE-48-00:11:22", "not-a-mac"]
+    )
+
+for item in items:
+    if item.failed:
+        print(f"{item.input} -> ERROR {item.error}")
+    else:
+        print(f"{item.input} -> {item.organization or '(no vendor)'}")

macadress-1.0.0/examples/04_search_vendors.py

@@ -0,0 +1,19 @@
+"""Search the registered vendor/block directory. Needs a key.
+
+Run: MACADRESS_API_KEY=mk_live_xxx python examples/04_search_vendors.py Cisco US
+"""
+
+import os
+import sys
+
+from macadress import Client
+
+query = sys.argv[1] if len(sys.argv) > 1 else "Cisco"
+country = sys.argv[2] if len(sys.argv) > 2 else None
+
+with Client(os.environ.get("MACADRESS_API_KEY", "")) as client:
+    result = client.search_vendors(query, country=country, limit=20)
+
+print(f"{result.total} total match(es), showing {len(result)}:\n")
+for block in result:
+    print(f"{block.block_type or '?'}  {block.organization}  ({block.country or '?'})")

macadress-1.0.0/examples/05_async.py

@@ -0,0 +1,27 @@
+"""AsyncClient mirrors Client. Run: python examples/05_async.py 00:03:93:AB:12:34"""
+
+import asyncio
+import os
+import sys
+
+from macadress import AsyncClient, MacadressError, RateLimitError
+
+mac = sys.argv[1] if len(sys.argv) > 1 else "00:03:93:AB:12:34"
+
+
+async def main() -> None:
+    async with AsyncClient(os.environ.get("MACADRESS_API_KEY", "")) as client:
+        name = await client.vendor(mac)
+        print(name if name is not None else f"{mac}: no vendor on record")
+
+        try:
+            r = await client.lookup(mac)
+        except RateLimitError as exc:
+            print(f"rate limited, retry after {exc.retry_after or '?'}s")
+        except MacadressError as exc:
+            print(f"lookup needs a key: {exc}")
+        else:
+            print("organization:", r.organization)
+
+
+asyncio.run(main())

macadress-1.0.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "macadress"
+dynamic = ["version"]
+description = "Official Python client for the macadress.com MAC address and OUI vendor lookup API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "ApisOS FZE" }]
+keywords = ["macadress", "mac-address", "oui", "vendor-lookup", "mac-vendor", "ieee", "api-client", "sdk"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://macadress.com"
+Documentation = "https://macadress.com/docs"
+Source = "https://github.com/sapisos/macadress-python"
+Issues = "https://github.com/sapisos/macadress-python/issues"
+Changelog = "https://github.com/sapisos/macadress-python/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "mypy>=1.11", "ruff>=0.6"]
+
+[tool.hatch.version]
+path = "src/macadress/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/macadress"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/examples", "/CHANGELOG.md", "/README.md", "/LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "W"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/macadress"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]