sqlspec 0.36.0__cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

sqlspec/utils/uuids.py

@@ -0,0 +1,225 @@
+"""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. When uuid-utils is not installed,
+    falls back to 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 uuid-utils unavailable.
+    """
+    module = _load_uuid_utils()
+    if module is None:
+        warnings.warn(
+            "uuid-utils not installed, falling back to uuid4 for UUID v6 generation. "
+            "Install with: pip install sqlspec[uuid]",
+            UserWarning,
+            stacklevel=2,
+        )
+        return _stdlib_uuid4()
+    return cast("UUID", module.uuid6())
+
+
+def uuid7() -> "UUID":
+    """Generate a time-ordered UUID (version 7).
+
+    Uses uuid-utils when available. When uuid-utils is not installed,
+    falls back to 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 uuid-utils unavailable.
+    """
+    module = _load_uuid_utils()
+    if module is None:
+        warnings.warn(
+            "uuid-utils not installed, falling back to uuid4 for UUID v7 generation. "
+            "Install with: pip install sqlspec[uuid]",
+            UserWarning,
+            stacklevel=2,
+        )
+        return _stdlib_uuid4()
+    return cast("UUID", module.uuid7())
+
+
+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.36.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: sqlspec
+Version: 0.36.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
+Requires-Python: <4.0,>=3.10
+Requires-Dist: mypy-extensions
+Requires-Dist: rich-click>=1.9.0
+Requires-Dist: sqlglot>=19.9.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: 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'
+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; extra == 'litestar'
+Provides-Extra: msgspec
+Requires-Dist: msgspec; extra == 'msgspec'
+Provides-Extra: mypyc
+Provides-Extra: mysql-connector
+Requires-Dist: mysql-connector-python; 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: msgspec; extra == 'performance'
+Requires-Dist: sqlglot[rs]; 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: spanner
+Requires-Dist: google-cloud-spanner; extra == 'spanner'
+Provides-Extra: uuid
+Requires-Dist: uuid-utils; extra == 'uuid'
+Description-Content-Type: text/markdown
+
+# SQLSpec
+
+**Type-safe SQL execution layer for Python.**
+
+SQLSpec handles database connectivity and result mapping so you can focus on SQL. Write raw queries when you need precision, use the builder API when you need composability, or load SQL from files when you need organization. Every statement passes through a [sqlglot](https://github.com/tobymao/sqlglot)-powered AST pipeline for validation, dialect conversion, and optimization before execution. Export results as Python objects, Arrow tables, Polars or pandas DataFrames.
+
+It's not an ORM. It's the connectivity and processing layer between your application and your database that provides the right abstraction for each situation without dictating how you write SQL.
+
+## Status
+
+SQLSpec is currently in active development. The public API may change. Follow the [docs](https://sqlspec.dev/) and changelog for updates.
+
+## What You Get
+
+**Connection Management**
+
+- Connection pooling with configurable size, timeout, and lifecycle hooks
+- Sync and async support with a unified API surface
+- Adapters for PostgreSQL (psycopg, asyncpg, psqlpy), SQLite (sqlite3, aiosqlite), DuckDB, MySQL (asyncmy, mysql-connector, pymysql), Oracle, BigQuery, and ADBC-compatible databases
+
+**Query Execution**
+
+- Raw SQL strings with automatic parameter binding and dialect translation
+- SQL AST parsing via sqlglot for validation, optimization, and dialect conversion
+- Builder API for programmatic query construction without string concatenation
+- SQL file loading to keep queries organized alongside your code (named SQL queries)
+- Statement stacks for batching multiple operations with transaction control
+
+**Result Handling**
+
+- Type-safe result mapping to Pydantic, msgspec, attrs, or dataclasses
+- Apache Arrow export for zero-copy integration with pandas, Polars, and analytical tools
+- Result iteration, single-row fetch, or bulk retrieval based on your use case
+
+**Framework Integration**
+
+- Litestar plugin with dependency injection for connections, sessions, and pools
+- Starlette/FastAPI middleware for automatic transaction management
+- Flask extension with sync/async portal support
+
+**Production Features**
+
+- SQL validation and caching via sqlglot AST parsing
+- OpenTelemetry and Prometheus instrumentation hooks
+- Database event channels with native LISTEN/NOTIFY, Oracle AQ, and a portable queue fallback
+- Structured logging with correlation ID support
+- Migration CLI for schema versioning
+
+## Quick Start
+
+### Install
+
+```bash
+pip install "sqlspec"
+```
+
+### Run your first query
+
+```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!
+```
+
+That's it. Write SQL, define a schema, get typed objects back. Connection pooling, parameter binding, and result mapping are handled automatically.
+
+See the [Getting Started guide](https://sqlspec.dev/getting_started/) for installation variants, adapter selection, and advanced result mapping options.
+
+## Documentation
+
+- [Getting Started](https://sqlspec.dev/getting_started/)
+- [Usage Guides](https://sqlspec.dev/usage/)
+- [Examples Gallery](https://sqlspec.dev/examples/)
+- [API Reference](https://sqlspec.dev/reference/)
+- [CLI Reference](https://sqlspec.dev/usage/cli.html)
+
+## 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 (CLOB) handling, and real-time performance metrics.
+
+See the [usage docs](https://sqlspec.dev/usage/) for detailed guides on adapters, configuration patterns, and features like the [SQL file loader](https://sqlspec.dev/usage/loader.html).
+
+## Built With
+
+- **[sqlglot](https://github.com/tobymao/sqlglot)** - SQL parser, transpiler, and optimizer powering SQLSpec's AST pipeline
+
+## Contributing
+
+Contributions, issue reports, and adapter ideas are welcome. Review the
+[contributor guide](https://sqlspec.dev/contributing/) and follow the project
+coding standards before opening a pull request.
+
+## License
+
+SQLSpec is distributed under the MIT License.