Metadata-Version: 2.4
Name: mactools
Version: 2.0.0
Summary: MAC Address-focused library similar to ipaddress
Author: Michael Buckley
License-Expression: MIT
Project-URL: Homepage, https://github.com/Michael-C-Buckley/mactools
Project-URL: Repository, https://github.com/Michael-C-Buckley/mactools
Project-URL: Issues, https://github.com/Michael-C-Buckley/mactools/issues
Keywords: python,networking,network,mac,oui,ieee
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: bandit; extra == "dev"
Requires-Dist: basedpyright; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# MacTools

MacTools is a MAC-centric library for network handling and automation. MAC
address parsing is deterministic and offline; registry lookup and registry
updates are separate, explicit operations.

## Installation

This is a publicly available library on PyPI and can be installed with:

`pip install mactools`

## Features

### MacAddress

MAC object similar to Python's `ipaddress` library.  Performs validation on
creation and allows quick and easy format changing for the user.  Accepts
EUI-48 and EUI-64 formats.

#### Usage

Built-in `MacAddress` attributes allow for conversion between the common formats
of either delimiters, decimal, or binary. Such as:

```python
from mactools import MacAddress
mac = MacAddress('00:11:22:AA:BB:CC')

# returns the MAC without an delimiters or spaces (001122AABBCC)
mac.clean

# returns the MAC with period delimiters (0011.22AA.BBCC)
mac.period

# returns the decimal/numeric form (73596058572)
mac.decimal

# returns the OUI (00:11:22)
mac.oui
```

The full format list includes: clean, colon, period, hyphen, space, oui,
decimal, binary

#### IPv6 Support

This library has some methods for simplifying IPv6 SLAAC-based address creation:

```python
# returns the IPv6 Suffix/Interface ID in EUI-64 per RFC 4291 (0211:22ff:feaa:bbcc)
mac.eui64_suffix

# returns the Link-local address (fe80::0211:22ff:feaa:bbcc)
mac.link_local_address

# returns a Global Unicast Address as `ipaddress.IPv6Address`
mac.get_global_address('2001:db8::/64')
```

Integer input takes an explicit EUI width when EUI-64 is intended:

```python
MacAddress(1)          # 00:00:00:00:00:01 (EUI-48 default)
MacAddress(1, eui=64)  # 00:00:00:00:00:00:00:01
```

### OUI Registry

The library contains a registry of OUI (MA-L, MA-M, and MA-S) info obtained from IEEE,
and bundled at build time.
Organization information can be obtained, if it exists.

Basic usage involves creating a resolver:

```python
from mactools import MacAddress, OUIResolver

mac = MacAddress("24:6D:5E:BB:99:CC")
resolver = OUIResolver.default()
record = resolver.lookup(mac)

if record is not None:
    print(record.organization)
```

Lookup uses the newest valid user snapshot, then falls back to a registry bundled
with the installed package when that distribution provides one. A source-only
installation without a bundled snapshot must be refreshed explicitly once. It
never refreshes on a miss. Returned `OUIRecord` instances are immutable.

Special classifications such as broadcast, multicast, and locally administered
addresses are available through `resolver.vendor_for(mac)`.

#### Explicit Updates

Registry refresh is the only network-enabled operation:

```python
from mactools import RegistryUpdater

result = RegistryUpdater().refresh()
print(result.record_count, result.snapshot_path)
```

The updater downloads only from the configured IEEE HTTPS endpoints, enforces a
timeout and response-size limit, validates every CSV record, compiles a new
SQLite snapshot, verifies its integrity, and atomically promotes it. A failed
refresh leaves the previous snapshot untouched. Mutable data is stored in the
current user's OS cache directory rather than in `site-packages` or a shared
temporary directory.

The old `get_oui_cache()` and `update_ieee_files()` helpers remain temporarily as
deprecated compatibility wrappers. They no longer cause address construction or
module imports to perform updates.

## License

This project is under the MIT license (see the LICENSE file for full text).
