Refactor formatters to standalone module and prepare v1.0.0 release - #1
Merged
Merged
Conversation
Turn the tool into a polished, publishable package with tests and CI/CD. Packaging: - Rename PyPI distribution to `kql-cli` (the `kq` name is taken on PyPI by an unrelated project); the installed command stays `kq`. - Add a real LICENSE file and fix placeholder author metadata. - Single-source the version from src/kq/__init__.py via hatch dynamic version. - Bump to 1.0.0; drop the redundant License classifier now that the SPDX license expression is used. - Anchor the .gitignore `queries/` rule to the repo root so it no longer excludes the bundled src/kq/queries package data from builds. Code: - Extract output formatters into an Azure-free `formatters` module so they are unit-testable without the Kusto SDK; client re-exports for compat. - De-duplicate the repeated "no cluster/database" CLI messages into constants. Tests & CI/CD: - Add a pytest suite covering formatters, query rendering, and config precedence (21 tests). - Add GitHub Actions CI (ruff lint + pytest on Python 3.9-3.13 + build check). - Add a tag-triggered release workflow that publishes to PyPI via Trusted Publishing (OIDC, no stored tokens). Docs: - README: fix the install command, add CI/PyPI/license badges, document the package-vs-command naming, and add development + releasing sections. - Add CHANGELOG.md. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B777V3WPGhuCdFuZiHYds4
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request prepares the repository for its first public release (v1.0.0) under the package name kql-cli. Key changes include refactoring the output formatters into a dedicated, Azure-free module (src/kq/formatters.py) to enable isolated unit testing, adding a comprehensive test suite, and updating project metadata, documentation, and CI configurations. Feedback is provided on the manual CSV formatting implementation in src/kq/formatters.py, recommending the use of Python's built-in csv module to robustly handle edge cases like double quotes in headers and carriage returns.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Address review feedback on src/kq/formatters.py: the hand-rolled CSV writer had two RFC 4180 correctness gaps — a double quote inside a column header was emitted unescaped, and a cell containing a bare carriage return (\r without \n) was not quoted. Delegate to the stdlib csv module, which handles every quoting edge case and is well optimized. Output shape is preserved: headers stay fully quoted (QUOTE_ALL), row cells use minimal quoting, and there is no trailing newline. Add tests for the two fixed edge cases plus the no-trailing-newline contract. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B777V3WPGhuCdFuZiHYds4
The 3.9/3.10 CI jobs failed on test_csv_quotes_bare_carriage_return: Python < 3.11's csv.writer does not quote a field containing a bare "\r" when the line terminator is "\n" (it only quotes characters that appear in the line terminator), whereas 3.11+ always quotes "\r"/"\n". Rather than emit CRLF (which would regress the tool's LF output), escalate a row to QUOTE_ALL when any cell contains "\r". CSV output is now RFC 4180 correct and byte-identical across all supported Python versions, while plain rows keep minimal quoting and LF line endings. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B777V3WPGhuCdFuZiHYds4
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR extracts output formatters into a dedicated Azure-free module, adds comprehensive test coverage, and prepares the project for its first public release on PyPI as
kql-cli.Key Changes
Code Organization
src/kq/formatters.py: Extractedformat_table(),format_json(), andformat_csv()fromclient.pyinto a standalone module with no Azure SDK dependencies, enabling unit testing in isolationclient.py: Maintains backward compatibility by re-exporting formatters with explicit__all__tests/conftest.pywithFakeResultTableandFakeColumnfixtures to mock Azure Kusto result objectsTest Coverage
tests/test_formatters.py(77 lines): Comprehensive tests for all three formatters covering:tests/test_config.py: Configuration resolution and query-path precedencetests/test_registry.py: Query parameter rendering and validationRelease Preparation
0.1.0→1.0.0insrc/kq/__init__.pypyproject.toml:kql-cli(PyPI name) while command remainskq__init__.pyruffandbuildto dev dependencies.github/workflows/ci.yml: Lint + test matrix (Python 3.9–3.13).github/workflows/release.yml: Trusted Publishing (OIDC) to PyPI on version tagsCHANGELOG.md: First release notes with feature summaryLICENSE: MIT license fileREADME.md: Enhanced with badges, installation clarification, and development/release instructions.gitignorerefinements andtests/__init__.pyCode Quality
ruffwith E, F, I, UP, B rule setscli.py,auth.py)MAX_TABLE_ROWS=50,MAX_CELL_WIDTH=30) in formatters moduleNotable Implementation Details
.columns,.rows_count,.to_dict()) rather than importing Azure types, enabling pure-Python testingmax_rowslimitisoformat()for datetime serialization via a customdefaulthandlerhttps://claude.ai/code/session_01B777V3WPGhuCdFuZiHYds4