sqlspec 0.47.0__cp314-cp314-win_amd64.whl

sqlspec/utils/uuids.py

@@ -0,0 +1,241 @@
+"""UUID and ID generation utilities with optional acceleration.
+
+Provides wrapper functions for uuid3, uuid4, uuid5, uuid6, uuid7, and nanoid generation.
+Uses uuid-utils and fastnanoid packages for performance when available,
+falling back to standard library.
+
+When uuid-utils is installed:
+    - uuid3, uuid4, uuid5, uuid6, uuid7 use the faster Rust implementation
+    - uuid6 and uuid7 provide proper time-ordered UUIDs per RFC 9562
+
+When uuid-utils is NOT installed:
+    - uuid3, uuid4, uuid5 fall back silently to stdlib (equivalent output)
+    - uuid6, uuid7 fall back to uuid4 with a warning (different UUID version)
+
+When fastnanoid is installed:
+    - nanoid() uses the Rust implementation for 21-char URL-safe IDs
+
+When fastnanoid is NOT installed:
+    - nanoid() falls back to uuid4().hex with a warning (different format)
+"""
+
+import warnings
+from collections.abc import Callable
+from importlib import import_module
+from typing import Any, cast
+from uuid import NAMESPACE_DNS, NAMESPACE_OID, NAMESPACE_URL, NAMESPACE_X500, UUID
+from uuid import uuid3 as _stdlib_uuid3
+from uuid import uuid4 as _stdlib_uuid4
+from uuid import uuid5 as _stdlib_uuid5
+
+__all__ = (
+    "NAMESPACE_DNS",
+    "NAMESPACE_OID",
+    "NAMESPACE_URL",
+    "NAMESPACE_X500",
+    "NANOID_INSTALLED",
+    "UUID_UTILS_INSTALLED",
+    "nanoid",
+    "uuid3",
+    "uuid4",
+    "uuid5",
+    "uuid6",
+    "uuid7",
+)
+
+
+class _Availability:
+    """Lazy availability flag for optional dependencies."""
+
+    __slots__ = ("_loader",)
+
+    def __init__(self, loader: Callable[[], "Any | None"]) -> None:
+        self._loader = loader
+
+    def __bool__(self) -> bool:
+        return self._loader() is not None
+
+
+def _load_uuid_utils() -> "Any | None":
+    """Load uuid-utils when available."""
+    try:
+        module = import_module("uuid_utils")
+    except Exception:
+        return None
+    return module
+
+
+def _load_nanoid() -> "Any | None":
+    """Load fastnanoid when available."""
+    try:
+        module = import_module("fastnanoid")
+    except Exception:
+        return None
+    return module
+
+
+def _convert_namespace(namespace: "Any", module: "Any | None") -> "Any":
+    """Convert namespace to uuid-utils UUID when available."""
+    if module is None:
+        return namespace
+    uuid_cls = module.UUID
+    if isinstance(namespace, uuid_cls):
+        return namespace
+    return uuid_cls(str(namespace))
+
+
+def _nanoid_impl() -> str:
+    return _stdlib_uuid4().hex
+
+
+UUID_UTILS_INSTALLED = _Availability(_load_uuid_utils)
+NANOID_INSTALLED = _Availability(_load_nanoid)
+
+
+def uuid3(name: str, namespace: "UUID | None" = None) -> "UUID":
+    """Generate a deterministic UUID (version 3) using MD5 hash.
+
+    Uses uuid-utils for performance when available, falls back to
+    standard library uuid.uuid3() silently (equivalent output).
+
+    Args:
+        name: The name to hash within the namespace.
+        namespace: The namespace UUID. Defaults to NAMESPACE_DNS if not provided.
+
+    Returns:
+        A deterministic UUID based on namespace and name.
+    """
+    module = _load_uuid_utils()
+    namespace_value = NAMESPACE_DNS if namespace is None else namespace
+    if module is None:
+        return _stdlib_uuid3(namespace_value, name)
+    # The uuid-utils module is loaded dynamically, so Mypy treats it as Any.
+    # We cast the return value to UUID to satisfy the return type annotation.
+    return cast("UUID", module.uuid3(_convert_namespace(namespace_value, module), name))
+
+
+def uuid4() -> "UUID":
+    """Generate a random UUID (version 4).
+
+    Uses uuid-utils for performance when available, falls back to
+    standard library uuid.uuid4() silently (equivalent output).
+
+    Returns:
+        A randomly generated UUID.
+    """
+    module = _load_uuid_utils()
+    if module is None:
+        return _stdlib_uuid4()
+    return cast("UUID", module.uuid4())
+
+
+def uuid5(name: str, namespace: "UUID | None" = None) -> "UUID":
+    """Generate a deterministic UUID (version 5) using SHA-1 hash.
+
+    Uses uuid-utils for performance when available, falls back to
+    standard library uuid.uuid5() silently (equivalent output).
+
+    Args:
+        name: The name to hash within the namespace.
+        namespace: The namespace UUID. Defaults to NAMESPACE_DNS if not provided.
+
+    Returns:
+        A deterministic UUID based on namespace and name.
+    """
+    module = _load_uuid_utils()
+    namespace_value = NAMESPACE_DNS if namespace is None else namespace
+    if module is None:
+        return _stdlib_uuid5(namespace_value, name)
+    return cast("UUID", module.uuid5(_convert_namespace(namespace_value, module), name))
+
+
+def uuid6() -> "UUID":
+    """Generate a time-ordered UUID (version 6).
+
+    Uses uuid-utils when available, falls back to Python 3.14+ native
+    uuid.uuid6() or uuid4() with a warning.
+
+    UUIDv6 is lexicographically sortable by timestamp, making it
+    suitable for database primary keys. It is a reordering of UUIDv1
+    fields to improve database performance.
+
+    Returns:
+        A time-ordered UUID, or a random UUID if time-ordered generation unavailable.
+    """
+    module = _load_uuid_utils()
+    if module is not None:
+        return cast("UUID", module.uuid6())
+
+    # Try Python 3.14+ native support
+    import uuid as _uuid_mod
+
+    native_uuid6 = getattr(_uuid_mod, "uuid6", None)
+    if native_uuid6 is not None:
+        return cast("UUID", native_uuid6())
+
+    warnings.warn(
+        "uuid-utils not installed and Python < 3.14, falling back to uuid4 for UUID v6 generation. "
+        "Install with: pip install sqlspec[uuid]",
+        UserWarning,
+        stacklevel=2,
+    )
+    return _stdlib_uuid4()
+
+
+def uuid7() -> "UUID":
+    """Generate a time-ordered UUID (version 7).
+
+    Uses uuid-utils when available, falls back to Python 3.14+ native
+    uuid.uuid7() or uuid4() with a warning.
+
+    UUIDv7 is the recommended time-ordered UUID format per RFC 9562,
+    providing millisecond precision timestamps. It is designed for
+    modern distributed systems and database primary keys.
+
+    Returns:
+        A time-ordered UUID, or a random UUID if time-ordered generation unavailable.
+    """
+    module = _load_uuid_utils()
+    if module is not None:
+        return cast("UUID", module.uuid7())
+
+    # Try Python 3.14+ native support
+    import uuid as _uuid_mod
+
+    native_uuid7 = getattr(_uuid_mod, "uuid7", None)
+    if native_uuid7 is not None:
+        return cast("UUID", native_uuid7())
+
+    warnings.warn(
+        "uuid-utils not installed and Python < 3.14, falling back to uuid4 for UUID v7 generation. "
+        "Install with: pip install sqlspec[uuid]",
+        UserWarning,
+        stacklevel=2,
+    )
+    return _stdlib_uuid4()
+
+
+def nanoid() -> str:
+    """Generate a Nano ID.
+
+    Uses fastnanoid for performance when available. When fastnanoid is
+    not installed, falls back to uuid4().hex with a warning.
+
+    Nano IDs are URL-safe, compact 21-character identifiers suitable
+    for use as primary keys or short identifiers. The default alphabet
+    uses A-Za-z0-9_- characters.
+
+    Returns:
+        A 21-character Nano ID string, or 32-character UUID hex if
+        fastnanoid unavailable.
+    """
+    module = _load_nanoid()
+    if module is None:
+        warnings.warn(
+            "fastnanoid not installed, falling back to uuid4.hex for Nano ID generation. "
+            "Install with: pip install sqlspec[nanoid]",
+            UserWarning,
+            stacklevel=2,
+        )
+        return _nanoid_impl()
+    return cast("str", module.generate())

sqlspec-0.47.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: sqlspec
+Version: 0.47.0
+Summary: SQL Experiments in Python
+Project-URL: Discord, https://discord.gg/litestar
+Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/
+Project-URL: Source, https://github.com/litestar-org/sqlspec
+Author-email: Cody Fincher <cody@litestar.dev>
+Maintainer-email: Litestar Developers <hello@litestar.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.10
+Requires-Dist: mypy-extensions
+Requires-Dist: rich-click>=1.9.0
+Requires-Dist: sqlglot>=30.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: typing-extensions
+Provides-Extra: adbc
+Requires-Dist: adbc-driver-manager; extra == 'adbc'
+Requires-Dist: pyarrow; extra == 'adbc'
+Provides-Extra: adk
+Requires-Dist: google-adk; extra == 'adk'
+Provides-Extra: aiomysql
+Requires-Dist: aiomysql; extra == 'aiomysql'
+Provides-Extra: aioodbc
+Requires-Dist: aioodbc; extra == 'aioodbc'
+Provides-Extra: aiosqlite
+Requires-Dist: aiosqlite; extra == 'aiosqlite'
+Provides-Extra: alloydb
+Requires-Dist: google-cloud-alloydb-connector; extra == 'alloydb'
+Provides-Extra: asyncmy
+Requires-Dist: asyncmy; extra == 'asyncmy'
+Provides-Extra: asyncpg
+Requires-Dist: asyncpg; extra == 'asyncpg'
+Provides-Extra: attrs
+Requires-Dist: attrs; extra == 'attrs'
+Requires-Dist: cattrs; extra == 'attrs'
+Provides-Extra: bigquery
+Requires-Dist: google-cloud-bigquery; extra == 'bigquery'
+Requires-Dist: google-cloud-storage; extra == 'bigquery'
+Provides-Extra: cloud-sql
+Requires-Dist: cloud-sql-python-connector; extra == 'cloud-sql'
+Provides-Extra: cockroachdb
+Requires-Dist: asyncpg; extra == 'cockroachdb'
+Requires-Dist: psycopg[binary,pool]; extra == 'cockroachdb'
+Provides-Extra: duckdb
+Requires-Dist: duckdb; extra == 'duckdb'
+Requires-Dist: pytz; extra == 'duckdb'
+Provides-Extra: fastapi
+Requires-Dist: fastapi; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask; extra == 'flask'
+Provides-Extra: fsspec
+Requires-Dist: fsspec; extra == 'fsspec'
+Provides-Extra: litestar
+Requires-Dist: litestar>=2.22.0; extra == 'litestar'
+Provides-Extra: msgspec
+Requires-Dist: msgspec; extra == 'msgspec'
+Provides-Extra: mypyc
+Requires-Dist: sqlglot[c]>=30.0.0; extra == 'mypyc'
+Provides-Extra: mysql-connector
+Requires-Dist: mysql-connector-python; (python_version < '3.12') and extra == 'mysql-connector'
+Requires-Dist: mysql-connector-python<9.7.0; (python_version >= '3.12') and extra == 'mysql-connector'
+Provides-Extra: nanoid
+Requires-Dist: fastnanoid>=0.4.1; extra == 'nanoid'
+Provides-Extra: obstore
+Requires-Dist: obstore; extra == 'obstore'
+Provides-Extra: opentelemetry
+Requires-Dist: opentelemetry-instrumentation; extra == 'opentelemetry'
+Provides-Extra: oracledb
+Requires-Dist: oracledb; extra == 'oracledb'
+Provides-Extra: orjson
+Requires-Dist: orjson; extra == 'orjson'
+Provides-Extra: pandas
+Requires-Dist: pandas; extra == 'pandas'
+Requires-Dist: pyarrow; extra == 'pandas'
+Provides-Extra: performance
+Requires-Dist: librt>=0.10.0; extra == 'performance'
+Requires-Dist: msgspec; extra == 'performance'
+Provides-Extra: polars
+Requires-Dist: polars; extra == 'polars'
+Requires-Dist: pyarrow; extra == 'polars'
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client; extra == 'prometheus'
+Provides-Extra: psqlpy
+Requires-Dist: psqlpy; extra == 'psqlpy'
+Provides-Extra: psycopg
+Requires-Dist: psycopg[binary,pool]; extra == 'psycopg'
+Provides-Extra: pydantic
+Requires-Dist: pydantic; extra == 'pydantic'
+Requires-Dist: pydantic-extra-types; extra == 'pydantic'
+Provides-Extra: pymssql
+Requires-Dist: pymssql; extra == 'pymssql'
+Provides-Extra: pymysql
+Requires-Dist: pymysql; extra == 'pymysql'
+Provides-Extra: sanic
+Requires-Dist: sanic; extra == 'sanic'
+Provides-Extra: spanner
+Requires-Dist: google-cloud-spanner; extra == 'spanner'
+Provides-Extra: starlette
+Requires-Dist: starlette; extra == 'starlette'
+Provides-Extra: uuid
+Requires-Dist: uuid-utils; extra == 'uuid'
+Description-Content-Type: text/markdown
+
+# SQLSpec
+
+[![PyPI](https://img.shields.io/pypi/v/sqlspec)](https://pypi.org/project/sqlspec/)
+[![Python](https://img.shields.io/pypi/pyversions/sqlspec)](https://pypi.org/project/sqlspec/)
+[![License](https://img.shields.io/pypi/l/sqlspec)](https://github.com/litestar-org/sqlspec/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-sqlspec.dev-blue)](https://sqlspec.dev/)
+
+SQLSpec is a SQL execution layer for Python. You write the SQL -- as strings, through a builder API, or loaded from files -- and SQLSpec handles connections, parameter binding, SQL injection prevention, dialect translation, and mapping results back to typed Python objects. It uses [sqlglot](https://github.com/tobymao/sqlglot) under the hood to parse, validate, and optimize your queries before they hit the database.
+
+It works with PostgreSQL (asyncpg, psycopg, psqlpy), SQLite (sqlite3, aiosqlite), DuckDB, MySQL (asyncmy, mysql-connector, pymysql), Oracle (oracledb), CockroachDB, BigQuery, Spanner, and anything ADBC-compatible. Sync or async, same API. It also includes a built-in storage layer, native and bridged Arrow support for all drivers, and integrations for Litestar, FastAPI, Flask, Sanic, and Starlette.
+
+## Quick Start
+
+```bash
+pip install sqlspec
+```
+
+```python
+from pydantic import BaseModel
+from sqlspec import SQLSpec
+from sqlspec.adapters.sqlite import SqliteConfig
+
+class Greeting(BaseModel):
+    message: str
+
+spec = SQLSpec()
+db = spec.add_config(SqliteConfig(connection_config={"database": ":memory:"}))
+
+with spec.provide_session(db) as session:
+    greeting = session.select_one(
+        "SELECT 'Hello, SQLSpec!' AS message",
+        schema_type=Greeting,
+    )
+    print(greeting.message)  # Output: Hello, SQLSpec!
+```
+
+Write SQL, define a schema, get typed objects back. Or use the query builder -- they're interchangeable:
+
+```python
+from sqlspec import sql
+
+# Builder API -- same driver, same result mapping
+users = session.select(
+    sql.select("id", "name", "email")
+       .from_("users")
+       .where("active = :active")
+       .order_by("name")
+       .limit(10),
+    {"active": True},
+    schema_type=User,
+)
+```
+
+## Features
+
+- **Connection pooling** -- sync and async adapters with a unified API across all supported drivers
+- **Parameter binding and dialect translation** -- powered by sqlglot, with a fluent query builder and `.sql` file loader
+- **Result mapping** -- map rows to Pydantic, msgspec, attrs, or dataclass models, or export to Arrow tables for pandas and Polars
+- **Storage layer** -- read and write Arrow tables to local files, fsspec, or object stores
+- **Framework integrations** -- Litestar plugin with DI, Starlette/FastAPI/Sanic middleware, Flask extension
+- **Observability** -- OpenTelemetry and Prometheus instrumentation, structured logging with correlation IDs
+- **Event channels** -- LISTEN/NOTIFY, Oracle AQ, and a portable polling fallback
+- **Migrations** -- schema versioning CLI built on Alembic
+
+## Documentation
+
+- [Getting Started](https://sqlspec.dev/getting_started/) -- installation, adapter selection, first steps
+- [Usage Guides](https://sqlspec.dev/usage/) -- adapters, configuration, SQL file loader, and more
+- [Examples Gallery](https://sqlspec.dev/examples/) -- working code for common patterns
+- [API Reference](https://sqlspec.dev/reference/) -- full API docs
+- [CLI Reference](https://sqlspec.dev/usage/cli.html) -- migration and management commands
+
+## Playground
+
+Want to try it without installing anything? The [interactive playground](https://sqlspec.dev/playground) runs SQLSpec in your browser with a sandboxed Python runtime.
+
+## Reference Applications
+
+- **[PostgreSQL + Vertex AI Demo](https://github.com/cofin/postgres-vertexai-demo)** -- Vector search with pgvector and real-time chat using Litestar and Google ADK. Shows connection pooling, migrations, type-safe result mapping, vector embeddings, and response caching.
+- **[Oracle + Vertex AI Demo](https://github.com/cofin/oracledb-vertexai-demo)** -- Oracle 23ai vector search with semantic similarity using HNSW indexes. Demonstrates NumPy array conversion, large object handling, and real-time performance metrics.
+
+## Contributing
+
+Contributions are welcome -- whether that's bug reports, new adapter ideas, or pull requests. Take a look at the [contributor guide](https://sqlspec.dev/contributing/) to get started.
+
+## License
+
+MIT