mquery-toolkit 0.1.0__tar.gz

mquery_toolkit-0.1.0/LICENSE

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

mquery_toolkit-0.1.0/NOTICE

@@ -0,0 +1,9 @@
+Unofficial project, not affiliated with Microsoft. The bundled JavaScript
+components retain their copyright and MIT permission notices in
+`mquery_toolkit/THIRD_PARTY_NOTICES.txt`.
+The test corpus includes a short Power Query M let-expression example from the
+Microsoft M language specification:
+https://learn.microsoft.com/en-us/powerquery-m/m-spec-let
+
+The vendored DataConnectors samples remain Copyright (c) Microsoft Corporation
+and are redistributed under the MIT License included beside those fixtures.

mquery_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: mquery-toolkit
+Version: 0.1.0
+Summary: Unofficial offline tooling for Power Query M source (parse, format, check, rename) via Microsoft's official parser and formatter
+Author: Gopal Bagaswar
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GopalGB/mquery-toolkit
+Project-URL: Repository, https://github.com/GopalGB/mquery-toolkit
+Project-URL: Issues, https://github.com/GopalGB/mquery-toolkit/issues
+Keywords: power-query,m-language,power-bi,fabric,linter,formatter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: fabric
+Requires-Dist: pyarrow>=14; extra == "fabric"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Dynamic: license-file
+
+# mquery-toolkit
+
+Offline command-line and Python tooling for Power Query M source: parse, format,
+lint (`check`), and safely rename a `let` binding.
+
+> **Unofficial.** Not affiliated with or endorsed by Microsoft. Not an M runtime -
+> it parses and formats M source text; it does not evaluate queries.
+
+## Install
+
+```bash
+pip install mquery-toolkit
+```
+
+Requires **Node.js 22 or newer** on `PATH`, or point `MQUERY_NODE` at a Node
+binary. The Microsoft parser and formatter packages are bundled inside the
+wheel (`_bridge.cjs`) - no `npm install` needed.
+
+## Quick start
+
+```bash
+# Parse to deterministic JSON (tokens, root kind, bindings/references)
+mquery parse query.pq
+
+# Format - dry run prints a unified diff, nothing is written
+mquery format query.pq
+
+# Format and write in place (atomic replace, preserves mode/newline/encoding)
+mquery format query.pq --write
+
+# Lint, machine-readable output; exit code 2 if any diagnostic is severity=error
+mquery check query.pq --json
+
+# Rename one top-level let binding - dry run first
+mquery rename query.pq --old OldName --new NewName
+```
+
+## Python API
+
+```python
+from mquery_toolkit import check, format_source, parse, rename, update_file
+
+parsed = parse(source_text)  # dict: tokens, rootKind, analysis
+formatted = format_source(source_text)  # formatted M source, same encoding
+diagnostics = check(source_text, "query.pq")  # list[Diagnostic]
+renamed = rename(source_text, "OldName", "NewName")
+
+# File-level edit with the same dry-run/--write safety model as the CLI
+diff = update_file(path, format_source)  # dry run: unified diff
+diff = update_file(path, format_source, write=True)  # atomic write
+```
+
+## Diagnostics
+
+| Code | Severity | Meaning |
+|---|---|---|
+| `M_PARSE_ERROR` | error | source does not parse |
+| `M001` | error | duplicate `let` binding name |
+| `M002` | warning | `Web.Contents` called with a non-literal (dynamic) URL |
+| `M003` | warning | credential-like literal (`password`/`token`/`secret` = `"..."`) |
+| `M004` | warning | `let` binding unreachable from the result |
+| `M005` | warning | unresolved unqualified reference |
+| `M006` | info | source-function inventory (`*.Contents` dependency) |
+
+`M002` and `M003` are conservative text-pattern checks on the raw source, not
+AST checks; expect occasional false positives inside comments or strings.
+Every matching occurrence is reported, one diagnostic per call site or
+literal.
+
+`check --json` emits stable objects; `check` without `--json` prints
+`file:line:column: severity code: message` per diagnostic. The CLI exits `2`
+when any diagnostic has severity `error`, `0` otherwise.
+
+## Safety model
+
+- **Dry-run by default.** Every edit command (`format`, `rename`,
+  `replace-source`) prints a unified diff and touches nothing unless `--write`
+  is passed.
+- **`--write` is an atomic replace**: the file is written to a sibling temp
+  file, `fsync`'d, `chmod`'d to match the original, then moved into place with
+  `os.replace`.
+- **Layout is preserved**: UTF-8 encoding, a leading BOM (present in every
+  Power Query SDK connector file), newline convention (`\n` vs `\r\n`),
+  final-newline state, and file mode all round-trip unchanged.
+- **Refuses symlinks and hardlinks** - writes require a regular, single-link
+  file.
+- **Detects concurrent change**: the source is snapshotted before the
+  transform and re-checked immediately before the atomic replace - this final
+  snapshot check, not the lock, is the guarantee against lost updates; a
+  change in that microsecond window raises `SafeWriteError`.
+- **Advisory lock while writing only** - a `--write` call takes a
+  cross-process advisory lock (`fcntl`/`msvcrt`) for the duration of the
+  write and removes the lock file afterward, best-effort. It only serialises
+  cooperating `mquery` processes and is not a correctness guarantee: because
+  the lock file is removed after use, a waiting process and a freshly
+  started one can end up locking different inodes. Dry-run calls take no
+  lock and create no lock file.
+- This is **not mandatory locking** - no OS provides a portable mandatory
+  lock, and the advisory lock is not itself the correctness guard. Use
+  source control or external exclusive ownership for concurrent editors.
+
+## Limits
+
+- Input and output are capped at **10 MiB**.
+- The Node subprocess is bounded to a **30 second** timeout.
+- Supported extensions: `.pq`, `.m`, `.pqm`, and any `*.query.pq` file.
+- `rename` scope: exactly **one unquoted top-level `let` binding**. It refuses
+  quoted identifiers (`#"..."`), record literals, lambda expressions, and
+  non-ASCII source.
+- `Retry-After` on the Fabric adapter must be whole seconds; HTTP-date values
+  are rejected.
+
+## Optional adapters
+
+- **`fabric` extra** (`pip install "mquery-toolkit[fabric]"`) - a Fabric
+  Execute Query client that takes a caller-provided bearer token and an
+  injected HTTP transport. It never manages credentials itself and is fully
+  mocked in tests (no network access in the test suite).
+- **`pqtest`** - a bounded wrapper around a user-installed Microsoft PQTest
+  executable, Windows-only, pinned to version `2.155.2`. It never downloads a
+  binary; it only validates and runs one already on disk.
+
+## What it is not
+
+- Not an M language runtime or evaluator.
+- Not a Power BI or Fabric client, and it does not manage credentials.
+- Not a general-purpose file editor - it only touches files with a supported
+  extension and only through the safety model above.
+- Not a replacement for Microsoft's own parser/formatter - it vendors and
+  calls them directly rather than reimplementing M syntax.
+
+## Development
+
+```bash
+git clone https://github.com/GopalGB/mquery-toolkit
+cd mquery-toolkit
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,fabric]"
+npm ci --ignore-scripts
+
+pytest -q --cov=mquery_toolkit --cov-fail-under=80
+mypy src
+ruff check .
+ruff format --check .
+npm test
+python -m build
+```
+
+## License
+
+MIT - see `LICENSE`. Bundled Microsoft packages
+(`@microsoft/powerquery-parser`, `@microsoft/powerquery-formatter`) and their
+dependencies are also MIT; see `THIRD_PARTY_NOTICES.txt` and `NOTICE`.

mquery_toolkit-0.1.0/README.md

@@ -0,0 +1,153 @@
+# mquery-toolkit
+
+Offline command-line and Python tooling for Power Query M source: parse, format,
+lint (`check`), and safely rename a `let` binding.
+
+> **Unofficial.** Not affiliated with or endorsed by Microsoft. Not an M runtime -
+> it parses and formats M source text; it does not evaluate queries.
+
+## Install
+
+```bash
+pip install mquery-toolkit
+```
+
+Requires **Node.js 22 or newer** on `PATH`, or point `MQUERY_NODE` at a Node
+binary. The Microsoft parser and formatter packages are bundled inside the
+wheel (`_bridge.cjs`) - no `npm install` needed.
+
+## Quick start
+
+```bash
+# Parse to deterministic JSON (tokens, root kind, bindings/references)
+mquery parse query.pq
+
+# Format - dry run prints a unified diff, nothing is written
+mquery format query.pq
+
+# Format and write in place (atomic replace, preserves mode/newline/encoding)
+mquery format query.pq --write
+
+# Lint, machine-readable output; exit code 2 if any diagnostic is severity=error
+mquery check query.pq --json
+
+# Rename one top-level let binding - dry run first
+mquery rename query.pq --old OldName --new NewName
+```
+
+## Python API
+
+```python
+from mquery_toolkit import check, format_source, parse, rename, update_file
+
+parsed = parse(source_text)  # dict: tokens, rootKind, analysis
+formatted = format_source(source_text)  # formatted M source, same encoding
+diagnostics = check(source_text, "query.pq")  # list[Diagnostic]
+renamed = rename(source_text, "OldName", "NewName")
+
+# File-level edit with the same dry-run/--write safety model as the CLI
+diff = update_file(path, format_source)  # dry run: unified diff
+diff = update_file(path, format_source, write=True)  # atomic write
+```
+
+## Diagnostics
+
+| Code | Severity | Meaning |
+|---|---|---|
+| `M_PARSE_ERROR` | error | source does not parse |
+| `M001` | error | duplicate `let` binding name |
+| `M002` | warning | `Web.Contents` called with a non-literal (dynamic) URL |
+| `M003` | warning | credential-like literal (`password`/`token`/`secret` = `"..."`) |
+| `M004` | warning | `let` binding unreachable from the result |
+| `M005` | warning | unresolved unqualified reference |
+| `M006` | info | source-function inventory (`*.Contents` dependency) |
+
+`M002` and `M003` are conservative text-pattern checks on the raw source, not
+AST checks; expect occasional false positives inside comments or strings.
+Every matching occurrence is reported, one diagnostic per call site or
+literal.
+
+`check --json` emits stable objects; `check` without `--json` prints
+`file:line:column: severity code: message` per diagnostic. The CLI exits `2`
+when any diagnostic has severity `error`, `0` otherwise.
+
+## Safety model
+
+- **Dry-run by default.** Every edit command (`format`, `rename`,
+  `replace-source`) prints a unified diff and touches nothing unless `--write`
+  is passed.
+- **`--write` is an atomic replace**: the file is written to a sibling temp
+  file, `fsync`'d, `chmod`'d to match the original, then moved into place with
+  `os.replace`.
+- **Layout is preserved**: UTF-8 encoding, a leading BOM (present in every
+  Power Query SDK connector file), newline convention (`\n` vs `\r\n`),
+  final-newline state, and file mode all round-trip unchanged.
+- **Refuses symlinks and hardlinks** - writes require a regular, single-link
+  file.
+- **Detects concurrent change**: the source is snapshotted before the
+  transform and re-checked immediately before the atomic replace - this final
+  snapshot check, not the lock, is the guarantee against lost updates; a
+  change in that microsecond window raises `SafeWriteError`.
+- **Advisory lock while writing only** - a `--write` call takes a
+  cross-process advisory lock (`fcntl`/`msvcrt`) for the duration of the
+  write and removes the lock file afterward, best-effort. It only serialises
+  cooperating `mquery` processes and is not a correctness guarantee: because
+  the lock file is removed after use, a waiting process and a freshly
+  started one can end up locking different inodes. Dry-run calls take no
+  lock and create no lock file.
+- This is **not mandatory locking** - no OS provides a portable mandatory
+  lock, and the advisory lock is not itself the correctness guard. Use
+  source control or external exclusive ownership for concurrent editors.
+
+## Limits
+
+- Input and output are capped at **10 MiB**.
+- The Node subprocess is bounded to a **30 second** timeout.
+- Supported extensions: `.pq`, `.m`, `.pqm`, and any `*.query.pq` file.
+- `rename` scope: exactly **one unquoted top-level `let` binding**. It refuses
+  quoted identifiers (`#"..."`), record literals, lambda expressions, and
+  non-ASCII source.
+- `Retry-After` on the Fabric adapter must be whole seconds; HTTP-date values
+  are rejected.
+
+## Optional adapters
+
+- **`fabric` extra** (`pip install "mquery-toolkit[fabric]"`) - a Fabric
+  Execute Query client that takes a caller-provided bearer token and an
+  injected HTTP transport. It never manages credentials itself and is fully
+  mocked in tests (no network access in the test suite).
+- **`pqtest`** - a bounded wrapper around a user-installed Microsoft PQTest
+  executable, Windows-only, pinned to version `2.155.2`. It never downloads a
+  binary; it only validates and runs one already on disk.
+
+## What it is not
+
+- Not an M language runtime or evaluator.
+- Not a Power BI or Fabric client, and it does not manage credentials.
+- Not a general-purpose file editor - it only touches files with a supported
+  extension and only through the safety model above.
+- Not a replacement for Microsoft's own parser/formatter - it vendors and
+  calls them directly rather than reimplementing M syntax.
+
+## Development
+
+```bash
+git clone https://github.com/GopalGB/mquery-toolkit
+cd mquery-toolkit
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,fabric]"
+npm ci --ignore-scripts
+
+pytest -q --cov=mquery_toolkit --cov-fail-under=80
+mypy src
+ruff check .
+ruff format --check .
+npm test
+python -m build
+```
+
+## License
+
+MIT - see `LICENSE`. Bundled Microsoft packages
+(`@microsoft/powerquery-parser`, `@microsoft/powerquery-formatter`) and their
+dependencies are also MIT; see `THIRD_PARTY_NOTICES.txt` and `NOTICE`.

mquery_toolkit-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mquery-toolkit"
+version = "0.1.0"
+description = "Unofficial offline tooling for Power Query M source (parse, format, check, rename) via Microsoft's official parser and formatter"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "Gopal Bagaswar" }]
+keywords = ["power-query", "m-language", "power-bi", "fabric", "linter", "formatter"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.optional-dependencies]
+fabric = ["pyarrow>=14"]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "mypy>=1.10",
+    "ruff>=0.5",
+    "build>=1.2",
+    "twine>=6.1",
+    "pip-audit>=2.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/GopalGB/mquery-toolkit"
+Repository = "https://github.com/GopalGB/mquery-toolkit"
+Issues = "https://github.com/GopalGB/mquery-toolkit/issues"
+
+[project.scripts]
+mquery = "mquery_toolkit.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mquery_toolkit = ["_bridge.cjs", "THIRD_PARTY_NOTICES.txt", "py.typed"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["mquery_toolkit"]

mquery_toolkit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mquery_toolkit-0.1.0/src/mquery_toolkit/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,34 @@
+Bundled JavaScript dependencies
+===============================
+
+@microsoft/powerquery-parser 2.0.0 and 0.19.0
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+@microsoft/powerquery-formatter 1.0.0
+Copyright (c) Microsoft Corporation.
+
+grapheme-splitter 1.0.4
+Copyright (c) 2015 Orlin Georgiev
+
+performance-now 2.1.0
+Copyright (c) 2013 Braveg1rl
+
+All components above are licensed under the MIT License:
+
+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.

mquery_toolkit-0.1.0/src/mquery_toolkit/__init__.py

@@ -0,0 +1,35 @@
+"""Typed offline tooling for Power Query M source."""
+
+from .core import (
+    AdapterError,
+    Diagnostic,
+    MQueryError,
+    NodeError,
+    ParseError,
+    RenameRefusal,
+    SafeWriteError,
+    check,
+    dependencies,
+    format_source,
+    parse,
+    rename,
+    replace_source,
+    update_file,
+)
+
+__all__ = [
+    "AdapterError",
+    "Diagnostic",
+    "MQueryError",
+    "NodeError",
+    "ParseError",
+    "RenameRefusal",
+    "SafeWriteError",
+    "check",
+    "dependencies",
+    "format_source",
+    "parse",
+    "rename",
+    "replace_source",
+    "update_file",
+]