Metadata-Version: 2.4
Name: randmac
Version: 0.2.0
Summary: randmac is a utility that generates 12-digit mac addresses
Author-email: Josh Schmelzle <josh@joshschmelzle.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/joshschmelzle/randmac
Project-URL: Repository, https://github.com/joshschmelzle/randmac
Project-URL: Changelog, https://github.com/joshschmelzle/randmac/blob/main/HISTORY.md
Project-URL: Issues, https://github.com/joshschmelzle/randmac/issues
Keywords: randmac,random mac,random mac address
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Utilities
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: build
Requires-Dist: build; extra == "build"
Requires-Dist: twine; extra == "build"
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: bumpver; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

randmac.py
==========

randmac is a utility that generates 12-digit mac addresses; either the NIC portion or full 12-digit MAC. 

By default randmac returns a random 12-digit MAC address in the locally administered address (LAA) unicast format. This means you will always see `x2`, `x6`, `xA`, or `xE` at the beginning of a MAC address generated by randmac. With `-p`, it keeps the vendor (OUI) portion of the MAC you pass in and randomizes only the NIC portion.

The output uses the same separator and lettercase as the MAC you pass in.

![](randmac20200913.gif)

# Installation

To install with pip:

`python3 -m pip install randmac`

# Requirements

Python 3.13 or greater is required.

# Supported MAC address formats

Supported formats:

 - MM:MM:MM:SS:SS:SS (colons)
 - MM-MM-MM-SS-SS-SS (hyphens/dashes)
 - MM.MM.MM.SS.SS.SS (dots/periods)
 - MMMM.MMSS.SSSS (cisco style)
 - MMMMMMSSSSSS (no separator)

where `M` stands for the manufacturer or vendor, and `S` stands for the NIC specific portion. 

# Usage

```
usage: randmac [-h] [-p] [-v] [mac]

Generates MAC addresses. By default randmac will generate a 12-digit MAC
address following the Locally Administrated Address (LAA) format. randmac only
supports 12-digit (48-bit) MAC addresses.

positional arguments:
  mac                sample MAC address that sets the output format (and the
                     vendor portion with -p)

options:
  -h, --help         show this help message and exit
  -p, --partial      randomizes the NIC portion of a MAC address
  -v, -V, --version  show program's version number and exit
```

In your own code, you can `from randmac import RandMac` and use it like `RandMac()`. If you wish to change the mac address format, pass in a sample MAC address with the target format. This means you can `from randmac import RandMac` and use it like `RandMac("0000.0000.0000")` or `RandMac("ff-ff-ff-dd-dd-dd")` to specify the delimiter format.

From a terminal (if the console scripts entry point `randmac` is in your path and executable) you can type `randmac` and press enter to generate a new 12-digit LAA address, or `randmac 00:00:00:00:00:00 -p` to generate a MAC with the same OUI, but a different NIC portion. The result will look something like `00:00:00:60:cf:6e`.

# Example usage

From Python:

```
>>> from randmac import RandMac
>>> RandMac()
'a6:9b:6b:8e:b3:42'
>>> RandMac("00:00:00:00:00:00", True)
'00:00:00:3f:8a:06'
>>> RandMac("0000.0000.0000", True)
'0000.007c.e662'
>>> RandMac("AA-BB-CC-DD-EE-FF")
'06-EB-45-84-D1-E3'
```

From CLI:

```
> randmac
fa:bf:7c:5d:65:3e
> randmac 00-00-00-00-00-00 -p
00-00-00-dd-5f-16
``` 

# License

The license for this project can be found [here](https://github.com/joshschmelzle/randmac/blob/main/LICENSE).
