silasyn-uid 1.0.0__tar.gz

silasyn_uid-1.0.0/LICENSE.md

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

silasyn_uid-1.0.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: silasyn-uid
+Version: 1.0.0
+Summary: Official zero-dependency Python client for Silasyn UID Studio Pro with automatic offline fallback.
+Author-email: Silasyn <support@silasyn.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Dynamic: license-file
+
+Silasyn UID Studio Pro - Python Client
+
+
+
+Official, zero-dependency Python client for generating secure, customizable unique identifiers using the Silasyn UID Studio Pro API.
+
+
+
+Features
+
+
+
+Zero Dependencies: Built entirely on Python's native standard libraries (urllib, json, uuid, secrets, time). No need to install requests.
+
+
+
+Automatic Offline Fallback: If the API endpoint at silasyn.com is unreachable (due to network, firewall, or DNS issues), the client automatically switches to a high-precision local generation engine to guarantee 100% uptime.
+
+
+
+Highly Customizable: Supports UUIDv4, UUIDv7 (Time-ordered), NanoID, Hexadecimal, Pure Numeric, and Custom pools with prefixes, suffixes, custom casings, and formatting.
+
+
+
+Installation
+
+
+
+Install the package from PyPI:
+
+
+
+pip install silasyn-uid
+
+
+
+
+
+Quick Start
+
+
+
+from silasyn\_uid import UIDStudio
+
+
+
+\# 1. Generate standard UUIDv4
+
+uuids = UIDStudio.uuid4(count=2)
+
+print(uuids)
+
+
+
+\# 2. Generate Time-ordered UUIDv7
+
+uuid7s = UIDStudio.uuid7(count=1)
+
+print(uuid7s)
+
+
+
+\# 3. Generate NanoIDs with a prefix
+
+nanoids = UIDStudio.nanoid(count=3, length=12, prefix="user\_")
+
+print(nanoids)
+
+
+
+\# 4. Generate custom hexadecimal keys
+
+custom\_keys = UIDStudio.custom(pool="ABCDEF1234567890", count=2, length=16, hyphens=True)
+
+print(custom\_keys)
+
+
+
+
+
+Configuration Parameters
+
+
+
+The core generate method accepts the following arguments:
+
+
+
+Parameter
+
+
+
+Type
+
+
+
+Default
+
+
+
+Description
+
+
+
+format\_type
+
+
+
+str
+
+
+
+"uuid4"
+
+
+
+Options: "uuid4", "uuid7", "nanoid", "hex", "numeric", "custom"
+
+
+
+count
+
+
+
+int
+
+
+
+1
+
+
+
+Number of identifiers to generate (Max: 5000)
+
+
+
+length
+
+
+
+int
+
+
+
+21
+
+
+
+Overall length of generated string (ignored for UUIDs)
+
+
+
+prefix
+
+
+
+str
+
+
+
+""
+
+
+
+Optional string to prepend
+
+
+
+suffix
+
+
+
+str
+
+
+
+""
+
+
+
+Optional string to append
+
+
+
+hyphens
+
+
+
+bool
+
+
+
+True
+
+
+
+Group characters into blocks separated by hyphens
+
+
+
+casing
+
+
+
+str
+
+
+
+"mixed"
+
+
+
+Set character case: "mixed", "lower", "upper"
+
+
+
+custom\_pool
+
+
+
+str
+
+
+
+""
+
+
+
+Alphanumeric pool used only when format\_type="custom"
+
+
+
+License
+
+
+
+Copyright © 2026 Silasyn. All rights reserved.
+
+Distributed under the MIT License. See LICENSE for details.
+

silasyn_uid-1.0.0/README.md

@@ -0,0 +1,240 @@
+Silasyn UID Studio Pro - Python Client
+
+
+
+Official, zero-dependency Python client for generating secure, customizable unique identifiers using the Silasyn UID Studio Pro API.
+
+
+
+Features
+
+
+
+Zero Dependencies: Built entirely on Python's native standard libraries (urllib, json, uuid, secrets, time). No need to install requests.
+
+
+
+Automatic Offline Fallback: If the API endpoint at silasyn.com is unreachable (due to network, firewall, or DNS issues), the client automatically switches to a high-precision local generation engine to guarantee 100% uptime.
+
+
+
+Highly Customizable: Supports UUIDv4, UUIDv7 (Time-ordered), NanoID, Hexadecimal, Pure Numeric, and Custom pools with prefixes, suffixes, custom casings, and formatting.
+
+
+
+Installation
+
+
+
+Install the package from PyPI:
+
+
+
+pip install silasyn-uid
+
+
+
+
+
+Quick Start
+
+
+
+from silasyn\_uid import UIDStudio
+
+
+
+\# 1. Generate standard UUIDv4
+
+uuids = UIDStudio.uuid4(count=2)
+
+print(uuids)
+
+
+
+\# 2. Generate Time-ordered UUIDv7
+
+uuid7s = UIDStudio.uuid7(count=1)
+
+print(uuid7s)
+
+
+
+\# 3. Generate NanoIDs with a prefix
+
+nanoids = UIDStudio.nanoid(count=3, length=12, prefix="user\_")
+
+print(nanoids)
+
+
+
+\# 4. Generate custom hexadecimal keys
+
+custom\_keys = UIDStudio.custom(pool="ABCDEF1234567890", count=2, length=16, hyphens=True)
+
+print(custom\_keys)
+
+
+
+
+
+Configuration Parameters
+
+
+
+The core generate method accepts the following arguments:
+
+
+
+Parameter
+
+
+
+Type
+
+
+
+Default
+
+
+
+Description
+
+
+
+format\_type
+
+
+
+str
+
+
+
+"uuid4"
+
+
+
+Options: "uuid4", "uuid7", "nanoid", "hex", "numeric", "custom"
+
+
+
+count
+
+
+
+int
+
+
+
+1
+
+
+
+Number of identifiers to generate (Max: 5000)
+
+
+
+length
+
+
+
+int
+
+
+
+21
+
+
+
+Overall length of generated string (ignored for UUIDs)
+
+
+
+prefix
+
+
+
+str
+
+
+
+""
+
+
+
+Optional string to prepend
+
+
+
+suffix
+
+
+
+str
+
+
+
+""
+
+
+
+Optional string to append
+
+
+
+hyphens
+
+
+
+bool
+
+
+
+True
+
+
+
+Group characters into blocks separated by hyphens
+
+
+
+casing
+
+
+
+str
+
+
+
+"mixed"
+
+
+
+Set character case: "mixed", "lower", "upper"
+
+
+
+custom\_pool
+
+
+
+str
+
+
+
+""
+
+
+
+Alphanumeric pool used only when format\_type="custom"
+
+
+
+License
+
+
+
+Copyright © 2026 Silasyn. All rights reserved.
+
+Distributed under the MIT License. See LICENSE for details.
+

silasyn_uid-1.0.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "silasyn-uid"
+version = "1.0.0"
+authors = [
+  { name = "Silasyn", email = "support@silasyn.com" }
+]
+description = "Official zero-dependency Python client for Silasyn UID Studio Pro with automatic offline fallback."
+readme = "README.md"
+requires-python = ">=3.7"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[tool.setuptools]
+py-modules = ["silasyn_uid"]

silasyn_uid-1.0.0/setup.cfg

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

silasyn_uid-1.0.0/silasyn_uid.egg-info/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: silasyn-uid
+Version: 1.0.0
+Summary: Official zero-dependency Python client for Silasyn UID Studio Pro with automatic offline fallback.
+Author-email: Silasyn <support@silasyn.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Dynamic: license-file
+
+Silasyn UID Studio Pro - Python Client
+
+
+
+Official, zero-dependency Python client for generating secure, customizable unique identifiers using the Silasyn UID Studio Pro API.
+
+
+
+Features
+
+
+
+Zero Dependencies: Built entirely on Python's native standard libraries (urllib, json, uuid, secrets, time). No need to install requests.
+
+
+
+Automatic Offline Fallback: If the API endpoint at silasyn.com is unreachable (due to network, firewall, or DNS issues), the client automatically switches to a high-precision local generation engine to guarantee 100% uptime.
+
+
+
+Highly Customizable: Supports UUIDv4, UUIDv7 (Time-ordered), NanoID, Hexadecimal, Pure Numeric, and Custom pools with prefixes, suffixes, custom casings, and formatting.
+
+
+
+Installation
+
+
+
+Install the package from PyPI:
+
+
+
+pip install silasyn-uid
+
+
+
+
+
+Quick Start
+
+
+
+from silasyn\_uid import UIDStudio
+
+
+
+\# 1. Generate standard UUIDv4
+
+uuids = UIDStudio.uuid4(count=2)
+
+print(uuids)
+
+
+
+\# 2. Generate Time-ordered UUIDv7
+
+uuid7s = UIDStudio.uuid7(count=1)
+
+print(uuid7s)
+
+
+
+\# 3. Generate NanoIDs with a prefix
+
+nanoids = UIDStudio.nanoid(count=3, length=12, prefix="user\_")
+
+print(nanoids)
+
+
+
+\# 4. Generate custom hexadecimal keys
+
+custom\_keys = UIDStudio.custom(pool="ABCDEF1234567890", count=2, length=16, hyphens=True)
+
+print(custom\_keys)
+
+
+
+
+
+Configuration Parameters
+
+
+
+The core generate method accepts the following arguments:
+
+
+
+Parameter
+
+
+
+Type
+
+
+
+Default
+
+
+
+Description
+
+
+
+format\_type
+
+
+
+str
+
+
+
+"uuid4"
+
+
+
+Options: "uuid4", "uuid7", "nanoid", "hex", "numeric", "custom"
+
+
+
+count
+
+
+
+int
+
+
+
+1
+
+
+
+Number of identifiers to generate (Max: 5000)
+
+
+
+length
+
+
+
+int
+
+
+
+21
+
+
+
+Overall length of generated string (ignored for UUIDs)
+
+
+
+prefix
+
+
+
+str
+
+
+
+""
+
+
+
+Optional string to prepend
+
+
+
+suffix
+
+
+
+str
+
+
+
+""
+
+
+
+Optional string to append
+
+
+
+hyphens
+
+
+
+bool
+
+
+
+True
+
+
+
+Group characters into blocks separated by hyphens
+
+
+
+casing
+
+
+
+str
+
+
+
+"mixed"
+
+
+
+Set character case: "mixed", "lower", "upper"
+
+
+
+custom\_pool
+
+
+
+str
+
+
+
+""
+
+
+
+Alphanumeric pool used only when format\_type="custom"
+
+
+
+License
+
+
+
+Copyright © 2026 Silasyn. All rights reserved.
+
+Distributed under the MIT License. See LICENSE for details.
+

silasyn_uid-1.0.0/silasyn_uid.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+LICENSE.md
+README.md
+pyproject.toml
+silasyn_uid.py
+silasyn_uid.egg-info/PKG-INFO
+silasyn_uid.egg-info/SOURCES.txt
+silasyn_uid.egg-info/dependency_links.txt
+silasyn_uid.egg-info/top_level.txt

silasyn_uid-1.0.0/silasyn_uid.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

silasyn_uid-1.0.0/silasyn_uid.egg-info/top_level.txt

@@ -0,0 +1 @@
+silasyn_uid

silasyn_uid-1.0.0/silasyn_uid.py

@@ -0,0 +1,194 @@
+"""
+Silasyn UID Studio Pro - Official Python Client
+Copyright (c) 2026 Silasyn. All rights reserved.
+
+A lightweight, zero-dependency wrapper for the Silasyn UID generation API.
+Includes a robust offline fallback generator to guarantee 100% uptime.
+"""
+
+import urllib.request
+import urllib.parse
+import json
+import uuid
+import secrets
+import time
+from typing import List
+
+class UIDStudio:
+    """
+    Client for interacting with the Silasyn UID API.
+    Automatically falls back to secure local generation when offline.
+    """
+    BASE_URL = "https://silasyn.com/uid/api.php"
+
+    @classmethod
+    def generate(
+        cls,
+        format_type: str = "uuid4",
+        count: int = 1,
+        length: int = 21,
+        prefix: str = "",
+        suffix: str = "",
+        hyphens: bool = True,
+        casing: str = "mixed",
+        custom_pool: str = ""
+    ) -> List[str]:
+        """
+        Core method to generate UIDs via the Silasyn API.
+        Falls back to local generation if network query fails.
+        """
+        params = {
+            "format": format_type,
+            "count": count,
+            "length": length,
+            "prefix": prefix,
+            "suffix": suffix,
+            "hyphens": "true" if hyphens else "false",
+            "casing": casing,
+        }
+        
+        if custom_pool and format_type == "custom":
+            params["customPool"] = custom_pool
+
+        query_string = urllib.parse.urlencode(params)
+        url = f"{cls.BASE_URL}?{query_string}"
+
+        try:
+            req = urllib.request.Request(url, headers={'User-Agent': 'Silasyn-Python-Client/1.0'})
+            # Set a 3-second timeout so offline scripts don't hang indefinitely
+            with urllib.request.urlopen(req, timeout=3.0) as response:
+                if response.status != 200:
+                    raise ConnectionError(f"HTTP Error {response.status}: {response.reason}")
+                
+                response_text = response.read().decode('utf-8')
+                data = json.loads(response_text)
+                
+                if data.get("success"):
+                    return data.get("data", [])
+                else:
+                    raise ValueError("API response status returned failed.")
+                    
+        except Exception as e:
+            # Seamlessly switch to offline generation if DNS or network fails
+            print(f"[Silasyn API Warning] Offline or Connection Failed ({e}). Using local fallback...")
+            return cls._generate_locally(
+                format_type, count, length, prefix, suffix, hyphens, casing, custom_pool
+            )
+
+    @classmethod
+    def _generate_locally(
+        cls,
+        format_type: str,
+        count: int,
+        length: int,
+        prefix: str,
+        suffix: str,
+        hyphens: bool,
+        casing: str,
+        custom_pool: str
+    ) -> List[str]:
+        """
+        Backup local generation engine to maintain identical client behavior offline.
+        """
+        local_data = []
+        for _ in range(count):
+            core = ""
+            if format_type == "uuid4":
+                u = str(uuid.uuid4())
+                core = u if hyphens else u.replace("-", "")
+                
+            elif format_type == "uuid7":
+                # Local high-precision UUIDv7 logic matching PHP layout
+                ms = int(time.time() * 1000)
+                time_hex = f"{ms:012x}"
+                r1 = secrets.token_hex(2)[:3]
+                r2 = secrets.token_hex(6)
+                r2_val = int(r2[:3], 16) | 0x800
+                r2_part1 = f"{r2_val:03x}"
+                r2_part2 = r2[3:]
+                u = f"{time_hex[:8]}-{time_hex[8:]}-7{r1}-{r2_part1}-{r2_part2}"
+                core = u if hyphens else u.replace("-", "")
+                
+            else:
+                # Map formatting pools
+                if format_type == "numeric":
+                    pool = "0123456789"
+                elif format_type == "hex":
+                    pool = "0123456789abcdef"
+                elif format_type == "nanoid":
+                    pool = "_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+                elif format_type == "custom":
+                    pool = custom_pool if custom_pool else "ABCDEF0123456789"
+                else:
+                    pool = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+                if format_type not in ["numeric", "nanoid", "custom"]:
+                    if casing == "lower":
+                        pool = pool.lower()
+                    elif casing == "upper":
+                        pool = pool.upper()
+
+                # De-duplicate character pool preserving order
+                pool = "".join(sorted(set(pool), key=pool.index))
+                
+                # Construct characters
+                chars = []
+                for i in range(length):
+                    if hyphens and i > 0 and i % 4 == 0 and i != length and format_type != "nanoid":
+                        chars.append("-")
+                    chars.append(secrets.choice(pool))
+                core = "".join(chars)
+
+                if format_type == "custom":
+                    if casing == "lower":
+                        core = core.lower()
+                    elif casing == "upper":
+                        core = core.upper()
+
+            local_data.append(f"{prefix}{core}{suffix}")
+        return local_data
+
+    # --- Convenience Methods ---
+
+    @classmethod
+    def uuid4(cls, count: int = 1, hyphens: bool = True, prefix: str = "") -> List[str]:
+        return cls.generate(format_type="uuid4", count=count, hyphens=hyphens, prefix=prefix)
+
+    @classmethod
+    def uuid7(cls, count: int = 1, hyphens: bool = True, prefix: str = "") -> List[str]:
+        return cls.generate(format_type="uuid7", count=count, hyphens=hyphens, prefix=prefix)
+
+    @classmethod
+    def nanoid(cls, count: int = 1, length: int = 21, prefix: str = "") -> List[str]:
+        return cls.generate(format_type="nanoid", count=count, length=length, hyphens=False, prefix=prefix)
+
+    @classmethod
+    def hex(cls, count: int = 1, length: int = 16, hyphens: bool = True, prefix: str = "") -> List[str]:
+        return cls.generate(format_type="hex", count=count, length=length, hyphens=hyphens, prefix=prefix)
+
+    @classmethod
+    def custom(cls, pool: str, count: int = 1, length: int = 16, hyphens: bool = False, prefix: str = "") -> List[str]:
+        return cls.generate(format_type="custom", custom_pool=pool, count=count, length=length, hyphens=hyphens, prefix=prefix)
+
+
+# ==========================================
+# Example Usage (Runs only if executed directly)
+# ==========================================
+if __name__ == "__main__":
+    print("Testing Silasyn UID Studio Pro API...\n")
+
+    # 1. Generate a standard UUIDv4
+    uuids = UIDStudio.uuid4(count=2)
+    print(f"UUIDv4: {uuids}")
+
+    # 2. Generate Time-ordered UUIDv7
+    uuid7s = UIDStudio.uuid7(count=1)
+    print(f"UUIDv7: {uuid7s}")
+
+    # 3. Generate NanoIDs with a prefix
+    nanoids = UIDStudio.nanoid(count=3, length=12, prefix="user_")
+    print(f"NanoID: {nanoids}")
+
+    # 4. Generate custom hexadecimal keys
+    custom_keys = UIDStudio.custom(pool="ABCDEF1234567890", count=2, length=16, hyphens=True)
+    print(f"Custom Hex: {custom_keys}")