sqlnbfmt 0.1.9__tar.gz → 0.3.0__tar.gz

{sqlnbfmt-0.1.9 → sqlnbfmt-0.3.0}/PKG-INFO

@@ -1,19 +1,24 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: sqlnbfmt
-Version: 0.1.9
+Version: 0.3.0
 Summary: A tool to format SQL code in Jupyter notebooks.
 Author-email: Qing <qingye779@gmail.com>
 License: MIT
+Project-URL: Homepage, https://github.com/flyersworder/sqlnbfmt
+Project-URL: Repository, https://github.com/flyersworder/sqlnbfmt
+Project-URL: Changelog, https://github.com/flyersworder/sqlnbfmt/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/flyersworder/sqlnbfmt/issues
+Keywords: sql,jupyter,notebook,formatter,sqlglot,pre-commit
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: astor>=0.8.1
-Requires-Dist: black>=24.10.0
 Requires-Dist: nbformat>=5.10.4
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: sqlglot>=25.27.0
+Dynamic: license-file
 
 # sqlnbfmt
 
@@ -21,16 +26,20 @@ Requires-Dist: sqlglot>=25.27.0
 [![License](https://img.shields.io/pypi/l/sqlnbfmt.svg)](https://github.com/flyersworder/sqlnbfmt/blob/main/LICENSE)
 [![Python Versions](https://img.shields.io/pypi/pyversions/sqlnbfmt.svg)](https://pypi.org/project/sqlnbfmt/)
 
+> **Quick start:** `pip install sqlnbfmt && sqlnbfmt notebook.ipynb`
+
 A SQL formatter designed specifically for Jupyter Notebooks. `sqlnbfmt` automatically formats SQL queries embedded in code cells, including both Python strings and SQL magic cells (`%%sql`), helping you maintain clean and consistent code.
 
 ## Features
 
-- 🎯 **Smart SQL Detection**: Automatically identifies and formats SQL queries in code cells and magic SQL cells
-- 🌳 **AST-Powered**: Uses Abstract Syntax Tree parsing for accurate SQL string identification
-- 🔒 **Safe Formatting**: Preserves query parameters (e.g., `%s`, `?`) and SQL comments
-- ⚙️ **Highly Configurable**: Customize formatting through YAML configuration
-- 🔄 **Pre-commit Ready**: Seamlessly integrates with pre-commit hooks
-- 📦 **Zero Dependencies**: Minimal installation footprint
+- **Zero-config**: Works out of the box with sensible defaults — no config file needed
+- **Smart SQL Detection**: Automatically identifies and formats SQL queries in code cells and magic SQL cells
+- **AST-Powered**: Uses Abstract Syntax Tree parsing for accurate SQL string identification
+- **Safe Formatting**: Preserves Python comments, query parameters (e.g., `%s`, `?`), and SQL comments
+- **CI-Friendly**: `--check` mode exits non-zero when formatting is needed; `--diff` shows what would change
+- **Skip Hints**: Add `# sqlnbfmt: skip` to any cell to exclude it from formatting
+- **Pre-commit Ready**: Seamlessly integrates with pre-commit hooks
+- **Lightweight**: Only three runtime dependencies (sqlglot, nbformat, pyyaml)
 
 ## Installation
 
@@ -47,9 +56,23 @@ Format a single notebook:
 sqlnbfmt path/to/your_notebook.ipynb
 ```
 
-Format all notebooks in a directory:
+Check formatting without modifying files (useful in CI):
+```bash
+sqlnbfmt --check path/to/your_notebook.ipynb
+```
+
+Show a diff of what would change:
 ```bash
-sqlnbfmt path/to/notebooks/
+sqlnbfmt --diff path/to/your_notebook.ipynb
+```
+
+### Skipping Cells
+
+Add a `# sqlnbfmt: skip` comment anywhere in a cell to skip formatting:
+
+```python
+# sqlnbfmt: skip
+query = "select * from my_special_table where id = 1"
 ```
 
 ### Pre-commit Integration
@@ -63,17 +86,15 @@ pip install pre-commit
 ```yaml
 repos:
   - repo: https://github.com/flyersworder/sqlnbfmt
-    rev: v0.1.1
+    rev: v0.3.0
     hooks:
       - id: sqlnbfmt
-        name: sqlnbfmt
         types: [jupyter]
-        args: [--config, config.yaml, --dialect, postgres]
 ```
-Please fun the following command in your CMD for help:
 
-```bash
-sqlnbfmt -h
+All arguments are optional. To specify a dialect or custom config:
+```yaml
+        args: [--dialect, postgres, --config, config.yaml]
 ```
 
 3. Install the hook:
@@ -86,8 +107,21 @@ pre-commit install
 pre-commit run --all-files
 ```
 
+### CI Usage
+
+Use `--check` in GitHub Actions to enforce formatting:
+
+```yaml
+- name: Check SQL notebook formatting
+  run: |
+    pip install sqlnbfmt
+    sqlnbfmt --check **/*.ipynb
+```
+
 ## Configuration
 
+`sqlnbfmt` works without any configuration file. A `config.yaml` is only needed to override defaults.
+
 Create a `config.yaml` file to customize formatting behavior. [Here](https://github.com/flyersworder/sqlnbfmt/blob/main/config.yaml) is a template.
 
 ### Configuration Options
@@ -95,8 +129,8 @@ Create a `config.yaml` file to customize formatting behavior. [Here](https://git
 | Option | Description | Default |
 |--------|-------------|---------|
 | `sql_keywords` | SQL keywords to recognize and format | Common SQL keywords |
-| `function_names` | Python functions containing SQL code | `[]` |
-| `sql_decorators` | Decorators indicating SQL code | `[]` |
+| `function_names` | Python functions containing SQL code | `read_sql`, `execute`, etc. |
+| `sql_decorators` | Decorators indicating SQL code | `query`, `sql_query`, etc. |
 | `single_line_threshold` | Maximum length before splitting SQL | 80 |
 | `indent_width` | Number of spaces for indentation | 4 |
 
@@ -125,6 +159,19 @@ ORDER BY
 """)
 ```
 
+## Troubleshooting
+
+**SQL not being formatted?**
+- Ensure the string contains at least 2 SQL keywords or a recognizable pattern like `SELECT...FROM`
+- Check that the function name is in the recognized list (use `--config` to add custom ones)
+
+**Comments being modified?**
+- Python comments (`#`) are preserved. SQL comments (`--`) inside strings are converted to `/* */` block comments by sqlglot.
+
+**Pre-commit hook fails?**
+- Make sure the `rev` matches the installed version
+- Run `pre-commit autoupdate` to get the latest version
+
 ## Contributing
 
 We welcome contributions! Here's how to get started:
@@ -146,6 +193,13 @@ source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 pytest
 ```
 
+4. Add eval cases: see `tests/eval/generate_fixtures.py` for examples. Run `python tests/eval/generate_fixtures.py` to regenerate fixtures.
+
+5. Install dev pre-commit hooks:
+```bash
+pre-commit install
+```
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

sqlnbfmt-0.1.9/sqlnbfmt.egg-info/PKG-INFO → sqlnbfmt-0.3.0/README.md

@@ -1,36 +1,23 @@
-Metadata-Version: 2.2
-Name: sqlnbfmt
-Version: 0.1.9
-Summary: A tool to format SQL code in Jupyter notebooks.
-Author-email: Qing <qingye779@gmail.com>
-License: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: astor>=0.8.1
-Requires-Dist: black>=24.10.0
-Requires-Dist: nbformat>=5.10.4
-Requires-Dist: pyyaml>=6.0.2
-Requires-Dist: sqlglot>=25.27.0
-
 # sqlnbfmt
 
 [![PyPI](https://img.shields.io/pypi/v/sqlnbfmt.svg)](https://pypi.org/project/sqlnbfmt/)
 [![License](https://img.shields.io/pypi/l/sqlnbfmt.svg)](https://github.com/flyersworder/sqlnbfmt/blob/main/LICENSE)
 [![Python Versions](https://img.shields.io/pypi/pyversions/sqlnbfmt.svg)](https://pypi.org/project/sqlnbfmt/)
 
+> **Quick start:** `pip install sqlnbfmt && sqlnbfmt notebook.ipynb`
+
 A SQL formatter designed specifically for Jupyter Notebooks. `sqlnbfmt` automatically formats SQL queries embedded in code cells, including both Python strings and SQL magic cells (`%%sql`), helping you maintain clean and consistent code.
 
 ## Features
 
-- 🎯 **Smart SQL Detection**: Automatically identifies and formats SQL queries in code cells and magic SQL cells
-- 🌳 **AST-Powered**: Uses Abstract Syntax Tree parsing for accurate SQL string identification
-- 🔒 **Safe Formatting**: Preserves query parameters (e.g., `%s`, `?`) and SQL comments
-- ⚙️ **Highly Configurable**: Customize formatting through YAML configuration
-- 🔄 **Pre-commit Ready**: Seamlessly integrates with pre-commit hooks
-- 📦 **Zero Dependencies**: Minimal installation footprint
+- **Zero-config**: Works out of the box with sensible defaults — no config file needed
+- **Smart SQL Detection**: Automatically identifies and formats SQL queries in code cells and magic SQL cells
+- **AST-Powered**: Uses Abstract Syntax Tree parsing for accurate SQL string identification
+- **Safe Formatting**: Preserves Python comments, query parameters (e.g., `%s`, `?`), and SQL comments
+- **CI-Friendly**: `--check` mode exits non-zero when formatting is needed; `--diff` shows what would change
+- **Skip Hints**: Add `# sqlnbfmt: skip` to any cell to exclude it from formatting
+- **Pre-commit Ready**: Seamlessly integrates with pre-commit hooks
+- **Lightweight**: Only three runtime dependencies (sqlglot, nbformat, pyyaml)
 
 ## Installation
 
@@ -47,9 +34,23 @@ Format a single notebook:
 sqlnbfmt path/to/your_notebook.ipynb
 ```
 
-Format all notebooks in a directory:
+Check formatting without modifying files (useful in CI):
 ```bash
-sqlnbfmt path/to/notebooks/
+sqlnbfmt --check path/to/your_notebook.ipynb
+```
+
+Show a diff of what would change:
+```bash
+sqlnbfmt --diff path/to/your_notebook.ipynb
+```
+
+### Skipping Cells
+
+Add a `# sqlnbfmt: skip` comment anywhere in a cell to skip formatting:
+
+```python
+# sqlnbfmt: skip
+query = "select * from my_special_table where id = 1"
 ```
 
 ### Pre-commit Integration
@@ -63,17 +64,15 @@ pip install pre-commit
 ```yaml
 repos:
   - repo: https://github.com/flyersworder/sqlnbfmt
-    rev: v0.1.1
+    rev: v0.3.0
     hooks:
       - id: sqlnbfmt
-        name: sqlnbfmt
         types: [jupyter]
-        args: [--config, config.yaml, --dialect, postgres]
 ```
-Please fun the following command in your CMD for help:
 
-```bash
-sqlnbfmt -h
+All arguments are optional. To specify a dialect or custom config:
+```yaml
+        args: [--dialect, postgres, --config, config.yaml]
 ```
 
 3. Install the hook:
@@ -86,8 +85,21 @@ pre-commit install
 pre-commit run --all-files
 ```
 
+### CI Usage
+
+Use `--check` in GitHub Actions to enforce formatting:
+
+```yaml
+- name: Check SQL notebook formatting
+  run: |
+    pip install sqlnbfmt
+    sqlnbfmt --check **/*.ipynb
+```
+
 ## Configuration
 
+`sqlnbfmt` works without any configuration file. A `config.yaml` is only needed to override defaults.
+
 Create a `config.yaml` file to customize formatting behavior. [Here](https://github.com/flyersworder/sqlnbfmt/blob/main/config.yaml) is a template.
 
 ### Configuration Options
@@ -95,8 +107,8 @@ Create a `config.yaml` file to customize formatting behavior. [Here](https://git
 | Option | Description | Default |
 |--------|-------------|---------|
 | `sql_keywords` | SQL keywords to recognize and format | Common SQL keywords |
-| `function_names` | Python functions containing SQL code | `[]` |
-| `sql_decorators` | Decorators indicating SQL code | `[]` |
+| `function_names` | Python functions containing SQL code | `read_sql`, `execute`, etc. |
+| `sql_decorators` | Decorators indicating SQL code | `query`, `sql_query`, etc. |
 | `single_line_threshold` | Maximum length before splitting SQL | 80 |
 | `indent_width` | Number of spaces for indentation | 4 |
 
@@ -125,6 +137,19 @@ ORDER BY
 """)
 ```
 
+## Troubleshooting
+
+**SQL not being formatted?**
+- Ensure the string contains at least 2 SQL keywords or a recognizable pattern like `SELECT...FROM`
+- Check that the function name is in the recognized list (use `--config` to add custom ones)
+
+**Comments being modified?**
+- Python comments (`#`) are preserved. SQL comments (`--`) inside strings are converted to `/* */` block comments by sqlglot.
+
+**Pre-commit hook fails?**
+- Make sure the `rev` matches the installed version
+- Run `pre-commit autoupdate` to get the latest version
+
 ## Contributing
 
 We welcome contributions! Here's how to get started:
@@ -146,6 +171,13 @@ source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 pytest
 ```
 
+4. Add eval cases: see `tests/eval/generate_fixtures.py` for examples. Run `python tests/eval/generate_fixtures.py` to regenerate fixtures.
+
+5. Install dev pre-commit hooks:
+```bash
+pre-commit install
+```
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

{sqlnbfmt-0.1.9 → sqlnbfmt-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlnbfmt"
-version = "0.1.9"
+version = "0.3.0"
 description = "A tool to format SQL code in Jupyter notebooks."
 authors = [
   { name = "Qing", email = "qingye779@gmail.com" }
@@ -8,21 +8,31 @@ authors = [
 license = { text = "MIT" }
 readme = "README.md"
 requires-python = ">=3.12"
+keywords = ["sql", "jupyter", "notebook", "formatter", "sqlglot", "pre-commit"]
 classifiers = [
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.12"
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13"
 ]
 dependencies = [
-    "astor>=0.8.1",
-    "black>=24.10.0",
     "nbformat>=5.10.4",
     "pyyaml>=6.0.2",
     "sqlglot>=25.27.0",
 ]
 
-[tool.uv]
-dev-dependencies = [
+[project.urls]
+Homepage = "https://github.com/flyersworder/sqlnbfmt"
+Repository = "https://github.com/flyersworder/sqlnbfmt"
+Changelog = "https://github.com/flyersworder/sqlnbfmt/blob/main/CHANGELOG.md"
+Issues = "https://github.com/flyersworder/sqlnbfmt/issues"
+
+[project.scripts]
+sqlnbfmt = "sqlnbfmt.formatter:main"
+
+[dependency-groups]
+dev = [
     "pytest-cov>=5.0.0",
+    "pytest-timeout>=2.3.1",
     "pytest>=8.3.3",
 ]
 
@@ -30,13 +40,13 @@ dev-dependencies = [
 requires = ["setuptools>=61.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
-[project.scripts]
-sqlnbfmt = "sqlnbfmt.formatter:main"
-
 [tool.pytest.ini_options]
 markers = [
     "integration: mark a test as an integration test."
 ]
 
+[tool.ruff]
+extend-exclude = ["tests/eval/*/"]
+
 [tool.setuptools.package-data]
 sqlnbfmt = [".pre-commit-hooks.yaml"]