uuid-kit 1.0.1__tar.gz

uuid_kit-1.0.1/LICENSE

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

uuid_kit-1.0.1/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: uuid-kit
+Version: 1.0.1
+Summary: Generate UUID values (v4, v7) with flexible formatting and structured output options.
+Author: Troy Tessalone
+License: MIT
+Project-URL: Homepage, https://github.com/troytessalone/uuid-kit
+Project-URL: Issues, https://github.com/troytessalone/uuid-kit/issues
+Keywords: uuid,uuidv4,uuidv7,generator,utility,formatting
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: uuid6>=2024.7.10
+Dynamic: license-file
+
+# uuid-kit
+
+Generate UUID values (v4, v7) with flexible formatting and structured output options.
+
+---
+
+## Install
+
+```bash
+pip install uuid-kit
+```
+
+---
+
+## Usage
+
+```python
+from uuid_kit import generate_uuid
+
+result = generate_uuid(
+    count=3,
+    version="v7"
+)
+
+print(result)
+```
+
+---
+
+## Output
+
+```json
+{
+  "version": "v7",
+  "count": 3,
+  "format": "standard",
+  "items": [
+    "uuid-1",
+    "uuid-2",
+    "uuid-3"
+  ]
+}
+```
+
+---
+
+## Options
+
+| Field | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| count | int | No | 1 | Number of UUIDs to generate (min 1, max 100) |
+| version | string | No | v7 | UUID version: v4 or v7 |
+| format | string | No | standard | Output format: standard, compact, uppercase, uppercase-compact |
+| prefix | string | No | "" | Text to prepend to each UUID |
+| suffix | string | No | "" | Text to append to each UUID |
+| asObjects | bool | No | False | Return structured objects instead of strings |
+
+---
+
+## Formats
+
+| Format | Example |
+|------|------|
+| standard | `123e4567-e89b-12d3-a456-426614174000` |
+| compact | `123e4567e89b12d3a456426614174000` |
+| uppercase | `123E4567-E89B-12D3-A456-426614174000` |
+| uppercase-compact | `123E4567E89B12D3A456426614174000` |
+
+---
+
+## Examples
+
+### Default (v7)
+
+```python
+generate_uuid(count=2)
+```
+
+### v4
+
+```python
+generate_uuid(count=2, version="v4")
+```
+
+### Compact format
+
+```python
+generate_uuid(count=2, format="compact")
+```
+
+### Uppercase compact with prefix and suffix
+
+```python
+generate_uuid(
+    count=2,
+    format="uppercase-compact",
+    prefix="id_",
+    suffix="_end"
+)
+```
+
+### Return objects
+
+```python
+generate_uuid(count=2, asObjects=True)
+```
+
+Example output:
+
+```json
+{
+  "version": "v7",
+  "count": 2,
+  "format": "standard",
+  "items": [
+    {
+      "uuid": "123e4567-e89b-12d3-a456-426614174000",
+      "raw": "123e4567-e89b-12d3-a456-426614174000",
+      "index": 0,
+      "timestamp": {
+        "iso": "2026-04-09T18:00:00Z",
+        "unix": 1775757600000
+      }
+    },
+    {
+      "uuid": "123e4567-e89b-12d3-a456-426614174001",
+      "raw": "123e4567-e89b-12d3-a456-426614174001",
+      "index": 1,
+      "timestamp": {
+        "iso": "2026-04-09T18:00:00Z",
+        "unix": 1775757600001
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Supported Versions
+
+- v4 = random
+- v7 = modern time-based
+
+---
+
+## Exports
+
+```python
+from uuid_kit import generate_uuid
+from uuid_kit import ALLOWED_FORMATS, ALLOWED_VERSIONS
+```
+
+---
+
+## Environment Notes
+
+Some hosted Python runtimes require you to explicitly add packages before use. In those environments, add:
+
+```bash
+uuid-kit
+uuid6
+```
+
+---
+
+## Behavior
+
+- Invalid or missing `count` defaults to 1
+- `count` is capped at 100
+- Invalid or missing `version` defaults to `v7`
+- Invalid or missing `format` defaults to `standard`
+
+---
+
+## Notes
+
+- Python standard library does not yet include native UUID v7 support
+- To enable true v7 UUIDs, install:
+
+```bash
+pip install uuid6
+```
+
+- If `uuid6` is not installed, `version="v7"` falls back internally and will not produce a true v7 UUID
+
+---
+
+## License
+
+MIT

uuid_kit-1.0.1/README.md

@@ -0,0 +1,191 @@
+# uuid-kit
+
+Generate UUID values (v4, v7) with flexible formatting and structured output options.
+
+---
+
+## Install
+
+```bash
+pip install uuid-kit
+```
+
+---
+
+## Usage
+
+```python
+from uuid_kit import generate_uuid
+
+result = generate_uuid(
+    count=3,
+    version="v7"
+)
+
+print(result)
+```
+
+---
+
+## Output
+
+```json
+{
+  "version": "v7",
+  "count": 3,
+  "format": "standard",
+  "items": [
+    "uuid-1",
+    "uuid-2",
+    "uuid-3"
+  ]
+}
+```
+
+---
+
+## Options
+
+| Field | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| count | int | No | 1 | Number of UUIDs to generate (min 1, max 100) |
+| version | string | No | v7 | UUID version: v4 or v7 |
+| format | string | No | standard | Output format: standard, compact, uppercase, uppercase-compact |
+| prefix | string | No | "" | Text to prepend to each UUID |
+| suffix | string | No | "" | Text to append to each UUID |
+| asObjects | bool | No | False | Return structured objects instead of strings |
+
+---
+
+## Formats
+
+| Format | Example |
+|------|------|
+| standard | `123e4567-e89b-12d3-a456-426614174000` |
+| compact | `123e4567e89b12d3a456426614174000` |
+| uppercase | `123E4567-E89B-12D3-A456-426614174000` |
+| uppercase-compact | `123E4567E89B12D3A456426614174000` |
+
+---
+
+## Examples
+
+### Default (v7)
+
+```python
+generate_uuid(count=2)
+```
+
+### v4
+
+```python
+generate_uuid(count=2, version="v4")
+```
+
+### Compact format
+
+```python
+generate_uuid(count=2, format="compact")
+```
+
+### Uppercase compact with prefix and suffix
+
+```python
+generate_uuid(
+    count=2,
+    format="uppercase-compact",
+    prefix="id_",
+    suffix="_end"
+)
+```
+
+### Return objects
+
+```python
+generate_uuid(count=2, asObjects=True)
+```
+
+Example output:
+
+```json
+{
+  "version": "v7",
+  "count": 2,
+  "format": "standard",
+  "items": [
+    {
+      "uuid": "123e4567-e89b-12d3-a456-426614174000",
+      "raw": "123e4567-e89b-12d3-a456-426614174000",
+      "index": 0,
+      "timestamp": {
+        "iso": "2026-04-09T18:00:00Z",
+        "unix": 1775757600000
+      }
+    },
+    {
+      "uuid": "123e4567-e89b-12d3-a456-426614174001",
+      "raw": "123e4567-e89b-12d3-a456-426614174001",
+      "index": 1,
+      "timestamp": {
+        "iso": "2026-04-09T18:00:00Z",
+        "unix": 1775757600001
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Supported Versions
+
+- v4 = random
+- v7 = modern time-based
+
+---
+
+## Exports
+
+```python
+from uuid_kit import generate_uuid
+from uuid_kit import ALLOWED_FORMATS, ALLOWED_VERSIONS
+```
+
+---
+
+## Environment Notes
+
+Some hosted Python runtimes require you to explicitly add packages before use. In those environments, add:
+
+```bash
+uuid-kit
+uuid6
+```
+
+---
+
+## Behavior
+
+- Invalid or missing `count` defaults to 1
+- `count` is capped at 100
+- Invalid or missing `version` defaults to `v7`
+- Invalid or missing `format` defaults to `standard`
+
+---
+
+## Notes
+
+- Python standard library does not yet include native UUID v7 support
+- To enable true v7 UUIDs, install:
+
+```bash
+pip install uuid6
+```
+
+- If `uuid6` is not installed, `version="v7"` falls back internally and will not produce a true v7 UUID
+
+---
+
+## License
+
+MIT

uuid_kit-1.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uuid-kit"
+version = "1.0.1"
+description = "Generate UUID values (v4, v7) with flexible formatting and structured output options."
+readme = "README.md"
+authors = [
+  { name = "Troy Tessalone" }
+]
+license = { text = "MIT" }
+requires-python = ">=3.8"
+dependencies = ["uuid6>=2024.7.10"]
+
+keywords = [
+  "uuid",
+  "uuidv4",
+  "uuidv7",
+  "generator",
+  "utility",
+  "formatting"
+]
+
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent"
+]
+
+[project.urls]
+Homepage = "https://github.com/troytessalone/uuid-kit"
+Issues = "https://github.com/troytessalone/uuid-kit/issues"

uuid_kit-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uuid_kit-1.0.1/uuid_kit/__init__.py

@@ -0,0 +1,5 @@
+# py/__init__.py
+
+from .core import ALLOWED_FORMATS, ALLOWED_VERSIONS, generate_uuid
+
+__all__ = ["generate_uuid", "ALLOWED_FORMATS", "ALLOWED_VERSIONS"]

uuid_kit-1.0.1/uuid_kit/core.py

@@ -0,0 +1,171 @@
+# py/uuid_kit/core.py
+
+import importlib
+import uuid
+
+_uuid7_fn = None
+
+try:
+    uuid6_module = importlib.import_module("uuid6")
+    _uuid7_fn = uuid6_module.uuid7
+    HAS_UUID7 = True
+except Exception:
+    HAS_UUID7 = False
+
+
+ALLOWED_FORMATS = (
+    "standard",
+    "compact",
+    "uppercase",
+    "uppercase-compact"
+)
+
+ALLOWED_VERSIONS = (
+    "v4",
+    "v7"
+)
+
+
+def get_formatter(format_value):
+    if format_value == "compact":
+        return lambda v: v.replace("-", "")
+    if format_value == "uppercase":
+        return lambda v: v.upper()
+    if format_value == "uppercase-compact":
+        return lambda v: v.replace("-", "").upper()
+    return lambda v: v
+
+
+def extract_timestamp_v7(uuid_value):
+    hex_value = uuid_value.replace("-", "")[:12]
+    ms = int(hex_value, 16)
+
+    from datetime import datetime, timezone
+
+    dt = datetime.fromtimestamp(ms / 1000, tz=timezone.utc)
+
+    return {
+        "iso": dt.isoformat().replace("+00:00", "Z"),
+        "unix": ms
+    }
+
+
+def generate_uuid(
+    count=1,
+    version="v7",
+    format="standard",
+    prefix="",
+    suffix="",
+    asObjects=False
+):
+    """
+    Generate UUID values.
+
+    :param count: number of UUIDs (min 1, max 100)
+    :param version: "v4" or "v7"
+    :param format: "standard", "compact", "uppercase", or "uppercase-compact"
+    :param prefix: string to prepend to each UUID
+    :param suffix: string to append to each UUID
+    :param asObjects: if True, return structured item objects
+    :return: dict
+    """
+
+    # ===============================
+    # VALIDATE COUNT
+    # ===============================
+    try:
+        safe_count = float(count)
+    except Exception:
+        safe_count = 1
+
+    if safe_count != safe_count or safe_count < 0:
+        safe_count = 1
+    if safe_count > 100:
+        safe_count = 100
+
+    safe_count = int(safe_count)
+
+    # ===============================
+    # VALIDATE VERSION
+    # ===============================
+    normalized_version = str(version or "v7").lower()
+    final_version = normalized_version if normalized_version in ALLOWED_VERSIONS else "v7"
+
+    # ===============================
+    # VALIDATE FORMAT
+    # ===============================
+    normalized_format = str(format or "standard").lower()
+    final_format = normalized_format if normalized_format in ALLOWED_FORMATS else "standard"
+
+    formatter = get_formatter(final_format)
+
+    # ===============================
+    # VERSION CONFIG
+    # ===============================
+    def generate_v4():
+        return str(uuid.uuid4())
+
+    def generate_v7():
+        if HAS_UUID7 and _uuid7_fn:
+            return str(_uuid7_fn())
+        return str(uuid.uuid4())
+
+    version_config = {
+        "v4": {
+            "generator": generate_v4,
+            "hasTimestamp": False,
+            "extractTimestamp": None
+        },
+        "v7": {
+            "generator": generate_v7,
+            "hasTimestamp": True,
+            "extractTimestamp": extract_timestamp_v7
+        }
+    }
+
+    generator = version_config[final_version]["generator"]
+    has_timestamp = version_config[final_version]["hasTimestamp"]
+    extract_timestamp = version_config[final_version]["extractTimestamp"]
+
+    # ===============================
+    # GENERATE
+    # ===============================
+    items = []
+
+    for i in range(safe_count):
+        raw = generator()
+
+        timestamp = None
+        if has_timestamp and extract_timestamp:
+            try:
+                timestamp = extract_timestamp(raw)
+            except Exception:
+                timestamp = None
+
+        value = formatter(raw)
+
+        if prefix:
+            value = str(prefix) + value
+        if suffix:
+            value = value + str(suffix)
+
+        if asObjects:
+            obj = {
+                "uuid": value,
+                "raw": raw,
+                "index": i
+            }
+
+            if timestamp:
+                obj["timestamp"] = timestamp
+
+            items.append(obj)
+        else:
+            items.append(value)
+
+    return {
+        "version": final_version,
+        "format": final_format,
+        "count": safe_count,
+        "items": items
+    }

uuid_kit-1.0.1/uuid_kit.egg-info/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: uuid-kit
+Version: 1.0.1
+Summary: Generate UUID values (v4, v7) with flexible formatting and structured output options.
+Author: Troy Tessalone
+License: MIT
+Project-URL: Homepage, https://github.com/troytessalone/uuid-kit
+Project-URL: Issues, https://github.com/troytessalone/uuid-kit/issues
+Keywords: uuid,uuidv4,uuidv7,generator,utility,formatting
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: uuid6>=2024.7.10
+Dynamic: license-file
+
+# uuid-kit
+
+Generate UUID values (v4, v7) with flexible formatting and structured output options.
+
+---
+
+## Install
+
+```bash
+pip install uuid-kit
+```
+
+---
+
+## Usage
+
+```python
+from uuid_kit import generate_uuid
+
+result = generate_uuid(
+    count=3,
+    version="v7"
+)
+
+print(result)
+```
+
+---
+
+## Output
+
+```json
+{
+  "version": "v7",
+  "count": 3,
+  "format": "standard",
+  "items": [
+    "uuid-1",
+    "uuid-2",
+    "uuid-3"
+  ]
+}
+```
+
+---
+
+## Options
+
+| Field | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| count | int | No | 1 | Number of UUIDs to generate (min 1, max 100) |
+| version | string | No | v7 | UUID version: v4 or v7 |
+| format | string | No | standard | Output format: standard, compact, uppercase, uppercase-compact |
+| prefix | string | No | "" | Text to prepend to each UUID |
+| suffix | string | No | "" | Text to append to each UUID |
+| asObjects | bool | No | False | Return structured objects instead of strings |
+
+---
+
+## Formats
+
+| Format | Example |
+|------|------|
+| standard | `123e4567-e89b-12d3-a456-426614174000` |
+| compact | `123e4567e89b12d3a456426614174000` |
+| uppercase | `123E4567-E89B-12D3-A456-426614174000` |
+| uppercase-compact | `123E4567E89B12D3A456426614174000` |
+
+---
+
+## Examples
+
+### Default (v7)
+
+```python
+generate_uuid(count=2)
+```
+
+### v4
+
+```python
+generate_uuid(count=2, version="v4")
+```
+
+### Compact format
+
+```python
+generate_uuid(count=2, format="compact")
+```
+
+### Uppercase compact with prefix and suffix
+
+```python
+generate_uuid(
+    count=2,
+    format="uppercase-compact",
+    prefix="id_",
+    suffix="_end"
+)
+```
+
+### Return objects
+
+```python
+generate_uuid(count=2, asObjects=True)
+```
+
+Example output:
+
+```json
+{
+  "version": "v7",
+  "count": 2,
+  "format": "standard",
+  "items": [
+    {
+      "uuid": "123e4567-e89b-12d3-a456-426614174000",
+      "raw": "123e4567-e89b-12d3-a456-426614174000",
+      "index": 0,
+      "timestamp": {
+        "iso": "2026-04-09T18:00:00Z",
+        "unix": 1775757600000
+      }
+    },
+    {
+      "uuid": "123e4567-e89b-12d3-a456-426614174001",
+      "raw": "123e4567-e89b-12d3-a456-426614174001",
+      "index": 1,
+      "timestamp": {
+        "iso": "2026-04-09T18:00:00Z",
+        "unix": 1775757600001
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Supported Versions
+
+- v4 = random
+- v7 = modern time-based
+
+---
+
+## Exports
+
+```python
+from uuid_kit import generate_uuid
+from uuid_kit import ALLOWED_FORMATS, ALLOWED_VERSIONS
+```
+
+---
+
+## Environment Notes
+
+Some hosted Python runtimes require you to explicitly add packages before use. In those environments, add:
+
+```bash
+uuid-kit
+uuid6
+```
+
+---
+
+## Behavior
+
+- Invalid or missing `count` defaults to 1
+- `count` is capped at 100
+- Invalid or missing `version` defaults to `v7`
+- Invalid or missing `format` defaults to `standard`
+
+---
+
+## Notes
+
+- Python standard library does not yet include native UUID v7 support
+- To enable true v7 UUIDs, install:
+
+```bash
+pip install uuid6
+```
+
+- If `uuid6` is not installed, `version="v7"` falls back internally and will not produce a true v7 UUID
+
+---
+
+## License
+
+MIT

uuid_kit-1.0.1/uuid_kit.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+uuid_kit/__init__.py
+uuid_kit/core.py
+uuid_kit.egg-info/PKG-INFO
+uuid_kit.egg-info/SOURCES.txt
+uuid_kit.egg-info/dependency_links.txt
+uuid_kit.egg-info/requires.txt
+uuid_kit.egg-info/top_level.txt

uuid_kit-1.0.1/uuid_kit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

uuid_kit-1.0.1/uuid_kit.egg-info/requires.txt

@@ -0,0 +1 @@
+uuid6>=2024.7.10

uuid_kit-1.0.1/uuid_kit.egg-info/top_level.txt

@@ -0,0 +1 @@
+uuid_kit