Skip to content

Latest commit

 

History

History
276 lines (228 loc) · 12.7 KB

README.md

File metadata and controls

276 lines (228 loc) · 12.7 KB
Raw

Unique: UUID Generation (in Python)

"Unique": the UUID generator tool. unique.py will generate UUIDs (using a CLI) in a variey of flavours whilst unique_gui.py wraps this up in a pretty GUI. This project in availble as native python source, a windows executable and docker image.

Note: A Version 4 UUID is the default, safe and extremely random output of this tool.

Features

  • Generate UUID Versions 1, 3, 4, 5 and the "Special Nil Case"/0 (GUI 0/1/4 Only)
  • Support for DNS (FWDN), URL, OID and X.500 Namespaces (--ns)
  • Prefix UUID with URN (RFC 4122) (-u)
  • Commandline Unix-Like tool and Graphical User Interface
  • Non-Standard: Output UUID as Uppercase (-U)
  • Shorten UUIDs using Base64 Encoding (-s)
  • Platform Agnostic: Python, Docker & Windows

Background

Back in May 2016, I needed a random number generator and started learning about UUIDs. This tool started as a way to automatically generate 20 v4 UUIDs (the only one not static or engineered to a set of hardware) and has now been updated and released to hopefully demonstrate my profeciency with git, git-flow, markdown, python, ui design, ux design, tkinter, oosd, argument parsing, RegEx, Base64, Hexadecimal, Docker, and more!

What is a UUID? (from Wikipedia)

A universally unique identifier (UUID) is a 128-bit number used to identify information in computer systems. UUIDs are, for practical purposes, unique. Their uniqueness does not depend on a central registration authority or coordination between the parties generating them. Anyone can create a UUID and use it to identify something with near certainty that the identifier does not duplicate one that has already been, or will be, created to identify something else.

Further Reading:

Usage

Graphical User Interface (unique_gui.py)

Using the tkinter library, a gui is available to generate UUIDs for those not comfortable with the command line. Simply open/execute python3 unique_gui.py to be presented with the following graphical interface:

  Windows Linux macOS
Unique
Menu
Options
About

The following Menu options are availble:

  • File
    • New: Clear-down the UUIDs in the current tool, ready for new generation
    • Open: Open a text (.txt/.uuid) file, useful for appending UUIDs
    • Save: Save the current UUIDs to a text (.txt/.uuid) file
    • Save As..: Save the current UUIDs to a new text (.txt/.uuid) file
    • Quit
  • Generate
    • Version 1 UUID: Generare a Version 1 (Datetime & MAC Address) UUID
    • Version 4 UUID: Generate a Version 4 UUID (based on RNG)
    • Special Nil UUID: Generate a Nil UUID (0's)
  • Tools
    • Options: Open the Options popup
  • Help
    • About: Opens a popup window with author/version information

The following Keyboard Shortcuts are available:

  • CTRL + N: Clear-down the UUIDs in the current tool,ready for new generation
  • CTRL + O: Open a text (.txt/.uuid) file,useful for appending UUIDs
  • CTRL + S: Save the current UUIDs to a text (.txt``````.uuid) file
  • CTRL + 0: Generate a Nil UUID (0's)
  • CTRL + 1: Generare a Version 1 (Datetime & MAC Address)UUID
  • CTRL + 4: Generate a Version 4 UUID (based on RNG)
  • F1: Opens a popup window with author/version information
  • F9: Open the Options popup
  • ALT + F4: Exit/Quit

Command Line / Bash (unique.py)

Summary

The following arguments are compatible with the respective UUID-version generation.

Version Switch Specifics Additional Options (Bold = Mandatory)
0 / Nil -v 0 Special Nil UUID -q, -u, -U, -s
1 -v 1 Datetime and MAC address -q, -u, -U, -s
4 -v 4 Random Data -q, -u, -U, -s
3 -v 3 Namespace & Name-based --ns, -n, -q, -u, -U, -s
5 -v 5 Namespace & Name-based --ns, -n, -q, -u, -U, -s

Usage Examples (Windows)

The following code block uses shorthand arguments, the tool provides the facility to use both short (e.g. -q) and long (e.g. --quantity) arguments interchangebly. Windows can natively execute .py files if Python is installed. If you are using the independant released exexutable; simply substitute the extensions in the following examples to .exe.

# UUIDv4
>./unique.py
27fd1448-3c0d-4d73-94c4-9f16dd9e0c16

# 5 x UUIDv4
>./unique.py -q 5
32ec9ca1-2a84-40c9-afa4-f67a7a8c3156
039ee9f1-c5a0-4d85-805a-89b84974a6c7
b6a4587d-a3de-4e4c-8d84-a3fad6b14192
91bd7bf0-8b6e-46af-ad01-7f91ca66aa25
4085c90e-b195-40fb-b31e-e5faf76eb34a

# 2 x UUIDv1 with URN prefix
>./unique.py -v 1 -q 2 -u
urn:uuid:7ed04b31-f14c-11ea-ac52-e4b31802edf0
urn:uuid:7ed0c3d9-f14c-11ea-aabd-e4b31802edf0

# Special Nil UUID
>./unique.py -q 1 -v 0
00000000-0000-0000-0000-000000000000

# UUIDv5 for "python.org" Fully qualified domain name
>./unique.py -v 5 --ns dns -n "python.org"
886313e1-3b8a-5372-9b90-0c9aee199e5d

# Uppercase UUIDv3 for "http://adambonner.co.uk" URL with URN prefix
>./unique.py -U -v 3 -n "http://adambonner.co.uk" --ns url -u
urn:uuid:1FDC56DF-BB86-3F0D-9356-8612ABA227FF

Usage Example (Linux)

# UUIDv4
$ python3 unique.py
31c2c13c-60c9-4883-8f12-16ede5022da4

# 3x UUIDv1 encoded as Base64
$ python3 unique.py -v 1 -q 3 --short
EHuMMPxlEeqNuc2jzUq+xw==
EHuMMfxlEeqNuc2jzUq+xw==
EHuMMvxlEeqNuc2jzUq+xw==

Display Help

Using the -h (--help) argument on either Windows or Linux displays the following information:

usage: unique.py [-h] [-v <VERSION>] [-q <QUANTITY>] [--ns <NAMESPACE>] [-n <NAME>] [-u | -U | -s]

Generate a number of version specific UUIDs.

optional arguments:
  -h, --help            show this help message and exit
  -v <VERSION>, --version <VERSION>
                        Specify output UUID version (0, 1, 3, 4, or 5)
  -q <QUANTITY>, --quantity <QUANTITY>
                        Specify output quanitity (1 - 65536)
  --ns <NAMESPACE>, --namespace <NAMESPACE>
                        UUID v3 or v5 namespace
  -n <NAME>, --name <NAME>
                        Specify UUID v3 or v4 name
  -u, --urn             Specify URN standard prefix
  -U, --uppercase       Non-standard uppercase UUID string
  -s, --short           Shortened UUID using Base64 Encoding

Docker (docker run --rm -it uuid:latest)

The project's Dockerfile can be utilised to create a platform independant container image; supporting the generation of UUIDs in cloud (e.g. Kubernetes/OpenShift) environments. Getting unique to work with docker requires two steps, first create the docker image, then run it in the docker service

Build Docker Image

#Use Docker to Build Image, you may need elevated privilages/"root"
$ docker build . -t uuid

Run Docker Image (Examples)

# UUIDv4
$ docker run --rm -it uuid:latest

# 5 x UUIDv4
$ docker run --rm -it uuid:latest -q 5
32ec9ca1-2a84-40c9-afa4-f67a7a8c3156
039ee9f1-c5a0-4d85-805a-89b84974a6c7
b6a4587d-a3de-4e4c-8d84-a3fad6b14192
91bd7bf0-8b6e-46af-ad01-7f91ca66aa25
4085c90e-b195-40fb-b31e-e5faf76eb34a

# Display Help
$ docker run --rm -it uuid:latest --help

Ubuntu 20.04 LTS Bash Example

Installation / Prerequisites / Dependencies

Note: The Docker (CLI-only) version of this project is inherently platform independant. This readme doesn't discuss that technology. Get started here.

Unique is build with utilising the following Python 3 libraries:

  • uuid
  • codecs
  • re
  • argparse
  • tk/tkinter (including: messagebox, simpledialog, filedialog)
  • logging
  • pyinstaller

To utilise unique on multiple platforms Python 3 is required.

Windows:

# Install Python3 using Chocolatey
choco install python -y

# Restart Windows Terminal / PowerShell
echo "close this window"

# Use pip to Install PyInstaller
pip install pyinstaller

Linux:

# Install Python 3
sudo apt-get install python3

# Install tkinter
sudo apt-get install python3-tk

Other Software

The following software was used to create this project:

Miscellaneous

Project Icon

The following project icon was created with paint.net. Using a screenshot of Powershell executing the creation of 20 Version 1 UUIDs. 4 image resolutions where then produced and compiled into the single compressed .ico format.
256x256 48x48 32x32 16x16

Known Limitations

The following are known limitations and probably wont get fixed. Feel free to raise a pull request if you can help:

  • Limited to the 4 predefined UUID v3/v5 namespaces (URL, DNS, OID, X.500)
  • Unicode support is untested

Special Thanks

Thanks to these great projects I was able to figure out how to use tkinter for the GUI.

Roadmap

Unique is a hobby project with no guarantees. I've been thinking about adding the following functionaity somewhere down the line though!:

  • CLI: Support for more than UUIDv4
  • CLI: Make code more Unix-like (no boilerplate on execution)
  • CLI: Parameterise the number of returned UUIDs
  • CLI: Special Nil UUID
  • CLI: Support for standard UUID URN prefix
  • CLI: Support for non-standard uppercase UUID
  • CLI: Auto-generated help
  • Redo the Icon
  • CLI: Adding support for uuid namespaces, enabling UUIDv3 and UUIDv5
  • Dockerise the commandline tool
  • GUI: Add a Graphical User Interface
  • GUI: Utilise a tools/options panel/frame/window
  • GUI: Enable File: New/Open/Save/Save As.../Exit in the GUI
  • GUI: Add Iconography to the Menu Bar
  • GUI: Enable Keyboard Shortcuts in the GUI
  • GUI: Highlight Current Line
  • GUI: Highlight Regex Version
  • GUI: Add (floating?) File Information Pane
  • GUI: Add UUIDv3 and UUIDv5
  • GUI: Dark Mode
  • GUI: Dockerise the GUI (as Web Application?)
  • CLI: Encode UUIDs in Base64 to reduce character length
  • CLI: Decode Base64 encoded UUID
  • CLI: Reverse-Engineer UUID: Version
  • CLI: Reverse-Engineer UUID: Date/Time
  • CLI: Reverse-Engineer UUID: MAC Address
  • GUI: Encode UUIDs in Base64 to reduce character length
  • GUI: Decode Base64 encoded UUID
  • GUI: Reverse-Engineer UUID: Version
  • GUI: Reverse-Engineer UUID: Date/Time
  • GUI: Reverse-Engineer UUID: MAC Address
  • Creating a Windows Installer