nl2sql-adapter-sdk 0.1.2__tar.gz → 0.2.0__tar.gz

nl2sql_adapter_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: nl2sql-adapter-sdk
+Version: 0.2.0
+Summary: The contracts a database adapter for the nl2sql engine implements; depends on pydantic only
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nadeem4/nl2sql
+Project-URL: Documentation, https://nadeem4.github.io/nl2sql/
+Project-URL: Source, https://github.com/nadeem4/nl2sql
+Project-URL: Issues, https://github.com/nadeem4/nl2sql/issues
+Project-URL: Demo, https://nadeem4nk-nl2sql-demo.hf.space
+Keywords: nl2sql,text-to-sql,sql,database,adapter,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+
+# nl2sql-adapter-sdk
+
+The contracts a database adapter for the
+[nl2sql engine](https://github.com/nadeem4/nl2sql) implements. It depends on
+pydantic and the standard library only, so an adapter built against it inherits
+nothing else.
+
+- `DatasourceAdapterProtocol`: `capabilities()`, `connect()`,
+  `fetch_schema_snapshot()`, `execute(request)` and `get_dialect()`, which
+  returns a sqlglot dialect name such as `postgres` or `tsql`.
+- `AdapterRequest`, `ResultFrame` and `ResultError`: what the engine sends an
+  adapter and what it gets back.
+- `SchemaSnapshot` and the table, column and foreign-key contracts an adapter
+  describes its schema with.
+
+An adapter is published as an `nl2sql.adapters` entry point, and the engine
+finds it there; it never imports an adapter by name.
+
+```bash
+pip install nl2sql-adapter-sdk
+```
+
+Writing an adapter:
+[Adapter development](https://nadeem4.github.io/nl2sql/adapters/development/).
+Try the engine without installing anything: <https://nadeem4nk-nl2sql-demo.hf.space>.

nl2sql_adapter_sdk-0.2.0/README.md

@@ -0,0 +1,25 @@
+# nl2sql-adapter-sdk
+
+The contracts a database adapter for the
+[nl2sql engine](https://github.com/nadeem4/nl2sql) implements. It depends on
+pydantic and the standard library only, so an adapter built against it inherits
+nothing else.
+
+- `DatasourceAdapterProtocol`: `capabilities()`, `connect()`,
+  `fetch_schema_snapshot()`, `execute(request)` and `get_dialect()`, which
+  returns a sqlglot dialect name such as `postgres` or `tsql`.
+- `AdapterRequest`, `ResultFrame` and `ResultError`: what the engine sends an
+  adapter and what it gets back.
+- `SchemaSnapshot` and the table, column and foreign-key contracts an adapter
+  describes its schema with.
+
+An adapter is published as an `nl2sql.adapters` entry point, and the engine
+finds it there; it never imports an adapter by name.
+
+```bash
+pip install nl2sql-adapter-sdk
+```
+
+Writing an adapter:
+[Adapter development](https://nadeem4.github.io/nl2sql/adapters/development/).
+Try the engine without installing anything: <https://nadeem4nk-nl2sql-demo.hf.space>.

nl2sql_adapter_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nl2sql-adapter-sdk"
+version = "0.2.0" # x-release-please-version
+description = "The contracts a database adapter for the nl2sql engine implements; depends on pydantic only"
+readme = "README.md"
+license = "MIT"
+keywords = ["nl2sql", "text-to-sql", "sql", "database", "adapter", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries",
+]
+requires-python = ">=3.12"
+dependencies = [
+    # ConfigDict (contracts.py, schema.py) is pydantic v2 only; the old
+    # >=1.10 floor advertised an install that cannot import.
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/nadeem4/nl2sql"
+Documentation = "https://nadeem4.github.io/nl2sql/"
+Source = "https://github.com/nadeem4/nl2sql"
+Issues = "https://github.com/nadeem4/nl2sql/issues"
+Demo = "https://nadeem4nk-nl2sql-demo.hf.space"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["nl2sql_adapter_sdk*"]

{nl2sql_adapter_sdk-0.1.2 → nl2sql_adapter_sdk-0.2.0}/src/nl2sql_adapter_sdk/__init__.py

@@ -2,7 +2,7 @@
 
 from .capabilities import DatasourceCapability
 from .contracts import AdapterRequest, ResultError, ResultFrame
-from .protocols import DatasourceAdapterProtocol
+from .protocols import DatasourceAdapterProtocol, SqlRenderingAdapterProtocol
 from .schema import (
     TableRef,
     ColumnStatistics,
@@ -23,6 +23,7 @@ __all__ = [
     "ResultError",
     "ResultFrame",
     "DatasourceAdapterProtocol",
+    "SqlRenderingAdapterProtocol",
     "TableRef",
     "ColumnStatistics",
     "ColumnMetadata",

nl2sql_adapter_sdk-0.2.0/src/nl2sql_adapter_sdk/capabilities.py

@@ -0,0 +1,8 @@
+from enum import Enum
+
+
+class DatasourceCapability(str, Enum):
+    """Capability flags for datasource adapters."""
+
+    SUPPORTS_SQL = "supports_sql"
+    SUPPORTS_REST = "supports_rest"

{nl2sql_adapter_sdk-0.1.2 → nl2sql_adapter_sdk-0.2.0}/src/nl2sql_adapter_sdk/protocols.py

@@ -32,10 +32,33 @@ class DatasourceAdapterProtocol(Protocol):
         ...
 
     def get_dialect(self) -> str:
-        """Return the normalized dialect string (SQL adapters)."""
+        """Return the sqlglot dialect name the engine renders SQL in (SQL adapters).
+
+        It must be a name ``sqlglot.Dialect.get_or_raise`` accepts, such as
+        ``postgres``, ``tsql``, ``mysql``, ``duckdb`` or ``sqlite``, not the
+        SQLAlchemy dialect name (``postgresql``, ``mssql``).
+        """
         ...
 
 
     def test_connection(self) -> bool:
         """Test if the connection to the datasource can be established."""
         ...
+
+
+@runtime_checkable
+class SqlRenderingAdapterProtocol(Protocol):
+    """Optional hook: render the engine's finished SQL for this database.
+
+    The engine builds each query as a sqlglot expression tree and, when the
+    adapter has ``render_sql``, hands it the tree to render. Without the hook
+    the engine renders ``expression.sql(dialect=adapter.get_dialect())``, so
+    existing adapters keep working. Override it only to rewrite what sqlglot
+    cannot express for the database, and keep the result types every adapter
+    returns: a date part (``DATE_PART``) is an INTEGER, and a truncated date
+    (``DATE_TRUNC``) is an ISO date string ``YYYY-MM-DD``.
+    """
+
+    def render_sql(self, expression: Any) -> str:
+        """Return the SQL text for ``expression`` (a ``sqlglot.exp.Expression``)."""
+        ...

nl2sql_adapter_sdk-0.2.0/src/nl2sql_adapter_sdk.egg-info/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: nl2sql-adapter-sdk
+Version: 0.2.0
+Summary: The contracts a database adapter for the nl2sql engine implements; depends on pydantic only
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nadeem4/nl2sql
+Project-URL: Documentation, https://nadeem4.github.io/nl2sql/
+Project-URL: Source, https://github.com/nadeem4/nl2sql
+Project-URL: Issues, https://github.com/nadeem4/nl2sql/issues
+Project-URL: Demo, https://nadeem4nk-nl2sql-demo.hf.space
+Keywords: nl2sql,text-to-sql,sql,database,adapter,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+
+# nl2sql-adapter-sdk
+
+The contracts a database adapter for the
+[nl2sql engine](https://github.com/nadeem4/nl2sql) implements. It depends on
+pydantic and the standard library only, so an adapter built against it inherits
+nothing else.
+
+- `DatasourceAdapterProtocol`: `capabilities()`, `connect()`,
+  `fetch_schema_snapshot()`, `execute(request)` and `get_dialect()`, which
+  returns a sqlglot dialect name such as `postgres` or `tsql`.
+- `AdapterRequest`, `ResultFrame` and `ResultError`: what the engine sends an
+  adapter and what it gets back.
+- `SchemaSnapshot` and the table, column and foreign-key contracts an adapter
+  describes its schema with.
+
+An adapter is published as an `nl2sql.adapters` entry point, and the engine
+finds it there; it never imports an adapter by name.
+
+```bash
+pip install nl2sql-adapter-sdk
+```
+
+Writing an adapter:
+[Adapter development](https://nadeem4.github.io/nl2sql/adapters/development/).
+Try the engine without installing anything: <https://nadeem4nk-nl2sql-demo.hf.space>.

{nl2sql_adapter_sdk-0.1.2 → nl2sql_adapter_sdk-0.2.0}/src/nl2sql_adapter_sdk.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+README.md
 pyproject.toml
 src/nl2sql_adapter_sdk/__init__.py
 src/nl2sql_adapter_sdk/capabilities.py

nl2sql_adapter_sdk-0.2.0/src/nl2sql_adapter_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+pydantic>=2.0

nl2sql_adapter_sdk-0.1.2/PKG-INFO

@@ -1,6 +0,0 @@
-Metadata-Version: 2.4
-Name: nl2sql-adapter-sdk
-Version: 0.1.2
-Summary: Shared adapter contracts for NL2SQL
-Requires-Python: >=3.9
-Requires-Dist: pydantic>=1.10

nl2sql_adapter_sdk-0.1.2/pyproject.toml

@@ -1,19 +0,0 @@
-[build-system]
-requires = ["setuptools>=64", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "nl2sql-adapter-sdk"
-version = "0.1.2" # x-release-please-version
-description = "Shared adapter contracts for NL2SQL"
-requires-python = ">=3.9"
-dependencies = [
-    "pydantic>=1.10",
-]
-
-[tool.setuptools]
-package-dir = {"" = "src"}
-
-[tool.setuptools.packages.find]
-where = ["src"]
-include = ["nl2sql_adapter_sdk*"]

nl2sql_adapter_sdk-0.1.2/src/nl2sql_adapter_sdk/capabilities.py

@@ -1,13 +0,0 @@
-from enum import Enum
-
-
-class DatasourceCapability(str, Enum):
-    """Capability flags for datasource adapters."""
-
-    SUPPORTS_SQL = "supports_sql"
-    SUPPORTS_REST = "supports_rest"
-    SUPPORTS_GRAPHQL = "supports_graphql"
-    SUPPORTS_LAKE = "supports_lake"
-    SUPPORTS_SCHEMA_INTROSPECTION = "supports_schema_introspection"
-    SUPPORTS_DRY_RUN = "supports_dry_run"
-    SUPPORTS_COST_ESTIMATE = "supports_cost_estimate"

nl2sql_adapter_sdk-0.1.2/src/nl2sql_adapter_sdk.egg-info/PKG-INFO

@@ -1,6 +0,0 @@
-Metadata-Version: 2.4
-Name: nl2sql-adapter-sdk
-Version: 0.1.2
-Summary: Shared adapter contracts for NL2SQL
-Requires-Python: >=3.9
-Requires-Dist: pydantic>=1.10

nl2sql_adapter_sdk-0.1.2/src/nl2sql_adapter_sdk.egg-info/requires.txt

@@ -1 +0,0 @@
-pydantic>=1.10