lysqlnb 0.1.0__tar.gz

lysqlnb-0.1.0/LICENCE

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

lysqlnb-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: lysqlnb
+Version: 0.1.0
+Summary: A library for reading and validating SQL notebook files.
+Keywords: notebook,sql
+Author: Leyton Addison-Roach
+Author-email: Leyton Addison-Roach <git@laddisonroach.com>
+License-Expression: MIT
+License-File: LICENCE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/leyts/lysqlnb
+Project-URL: Issues, https://github.com/leyts/lysqlnb/issues
+Description-Content-Type: text/markdown
+
+# lysqlnb
+
+A library for reading and validating SQL notebook files (`.sqlnb`).
+
+> [!WARNING]
+> This project is a work in progress and is not yet ready for use. The API is unstable and subject to breaking changes.
+
+## Installation
+
+```shell
+pip install lysqlnb
+```
+
+## Background
+
+The data models are based on the VS Code [NotebookSerializer API](https://code.visualstudio.com/api/extension-guides/notebook#serializer).
+
+## Usage
+
+```python
+>>> from pathlib import Path
+>>> from lysqlnb import NotebookData
+>>> notebook = NotebookData.from_file(Path("path/to/notebook.sqlnb"))
+>>> print(notebook.model_dump_json(indent=2))
+{
+  "cells": [
+    {
+      "kind": 1,
+      "value": "# This is Markdown.",
+      "language_id": "markdown"
+    },
+    {
+      "kind": 2,
+      "value": "SELECT * FROM departments;",
+      "language_id": "oracle-sql"
+    }
+  ]
+}
+```
+
+## Requirements
+
+Python 3.14+
+
+## Licence
+
+[MIT](LICENCE)

lysqlnb-0.1.0/README.md

@@ -0,0 +1,47 @@
+# lysqlnb
+
+A library for reading and validating SQL notebook files (`.sqlnb`).
+
+> [!WARNING]
+> This project is a work in progress and is not yet ready for use. The API is unstable and subject to breaking changes.
+
+## Installation
+
+```shell
+pip install lysqlnb
+```
+
+## Background
+
+The data models are based on the VS Code [NotebookSerializer API](https://code.visualstudio.com/api/extension-guides/notebook#serializer).
+
+## Usage
+
+```python
+>>> from pathlib import Path
+>>> from lysqlnb import NotebookData
+>>> notebook = NotebookData.from_file(Path("path/to/notebook.sqlnb"))
+>>> print(notebook.model_dump_json(indent=2))
+{
+  "cells": [
+    {
+      "kind": 1,
+      "value": "# This is Markdown.",
+      "language_id": "markdown"
+    },
+    {
+      "kind": 2,
+      "value": "SELECT * FROM departments;",
+      "language_id": "oracle-sql"
+    }
+  ]
+}
+```
+
+## Requirements
+
+Python 3.14+
+
+## Licence
+
+[MIT](LICENCE)

lysqlnb-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "lysqlnb"
+version = "0.1.0"
+description = "A library for reading and validating SQL notebook files."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENCE"]
+authors = [
+    { name = "Leyton Addison-Roach", email = "git@laddisonroach.com" },
+]
+requires-python = ">=3.14"
+keywords = ["notebook", "sql"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.12.5",
+    "pyyaml>=6.0.3",
+]
+
+[project.urls]
+Repository = "https://github.com/leyts/lysqlnb"
+Issues = "https://github.com/leyts/lysqlnb/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-datadir>=1.8.0",
+    "ruff>=0.15.2",
+    "ty>=0.0.18",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 79
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = 20
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "W191",
+    "E111",
+    "E114",
+    "E117",
+    "D206",
+    "D300",
+    "Q000",
+    "Q001",
+    "Q002",
+    "Q003",
+    "COM812",
+    "COM819",
+    "TD",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = [
+    "ANN201",
+    "D100",
+    "D103",
+    "D104",
+    "PLR2004",
+    "S101",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

lysqlnb-0.1.0/src/lysqlnb/__init__.py

@@ -0,0 +1,17 @@
+"""lysqlnb — a library for reading and validating SQL notebook files."""
+
+from lysqlnb.exceptions import NotebookParseError
+from lysqlnb.models import (
+    NotebookCellData,
+    NotebookCellKind,
+    NotebookCellLanguage,
+    NotebookData,
+)
+
+__all__ = [
+    "NotebookCellData",
+    "NotebookCellKind",
+    "NotebookCellLanguage",
+    "NotebookData",
+    "NotebookParseError",
+]

lysqlnb-0.1.0/src/lysqlnb/exceptions.py

@@ -0,0 +1,5 @@
+"""Custom exceptions for lysqlnb."""
+
+
+class NotebookParseError(Exception):
+    """Raised when a notebook file cannot be parsed."""

lysqlnb-0.1.0/src/lysqlnb/models.py

@@ -0,0 +1,92 @@
+"""Notebook data models and parsing."""
+
+from enum import IntEnum, StrEnum
+from typing import TYPE_CHECKING, Any
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from lysqlnb.exceptions import NotebookParseError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class NotebookCellKind(IntEnum):
+    """A notebook cell kind.
+
+    Attributes:
+        MARKUP: Formatted source that is used for display.
+        CODE: Source that can be executed and that produces output.
+    """
+
+    MARKUP = 1
+    CODE = 2
+
+
+class NotebookCellLanguage(StrEnum):
+    """Language identifier for a notebook cell.
+
+    Attributes:
+        MARKDOWN: Markdown markup language.
+        ORACLE_SQL: Oracle SQL dialect.
+    """
+
+    MARKDOWN = "markdown"
+    ORACLE_SQL = "oracle-sql"
+
+
+class NotebookCellData(BaseModel):
+    """Raw representation of a notebook cell.
+
+    Attributes:
+        kind: The kind of cell data.
+        value: The source value of this cell data — either
+            source code or formatted text.
+        language_id: The language identifier of the source
+            value of this cell data.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    kind: NotebookCellKind
+    value: str
+    language_id: NotebookCellLanguage = Field(alias="languageId")
+
+
+class NotebookData(BaseModel):
+    """Raw representation of a notebook.
+
+    Attributes:
+        cells: The cell data of this notebook.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    cells: list[NotebookCellData]
+
+    @classmethod
+    def from_file(cls, path: Path) -> NotebookData:
+        """Create a notebook from a file.
+
+        Args:
+            path: Path to the notebook file.
+
+        Returns:
+            A validated notebook data object.
+
+        Raises:
+            NotebookParseError: If the file contains invalid YAML or
+                does not conform to the notebook schema.
+        """
+        try:
+            raw: Any = yaml.safe_load(path.read_text(encoding="utf-8"))
+        except yaml.YAMLError as e:
+            msg = f"Invalid YAML: {e}"
+            raise NotebookParseError(msg) from e
+
+        try:
+            return cls.model_validate(raw)
+        except ValidationError as e:
+            msg = f"Invalid notebook structure: {e}"
+            raise NotebookParseError(msg) from e