✨ add `EncodeOptions.comma_compact_nulls` #31

techouse · 2025-10-16T20:10:58Z

This pull request introduces a new option, comma_compact_nulls, to the encoding logic for lists using the COMMA format. This option allows users to omit None values from lists when encoding, resulting in more compact query strings. The change is documented, implemented in the encoding logic, and covered with new unit tests.

Feature: Comma List Encoding Improvements

Added a new comma_compact_nulls option to EncodeOptions, allowing omission of None entries in lists when using the COMMA format. This results in cleaner output (e.g., [True, False, None, True] becomes true,false,true). [1] [2]
Updated the encoding logic in _encode to filter out None values when comma_compact_nulls is enabled, and to ensure round-trip behavior is preserved when both comma_round_trip and comma_compact_nulls are set. [1] [2] [3]
Modified function signatures and internal calls to propagate the new comma_compact_nulls parameter throughout the encoding process. [1] [2] [3] [4] [5]

Documentation Updates

Documented the new comma_compact_nulls option in both README.rst and docs/README.rst, including usage examples and expected output. [1] [2]

Testing

Added comprehensive unit tests to cover the new behavior, including cases for skipping None entries, omitting keys when all entries are None, and preserving round-trip markers.

Summary by CodeRabbit

New Features
- Added comma_compact_nulls encoding option to omit None entries when using COMMA list format (e.g., [True, False, None, True] → true,false,true).
Documentation
- Added guidance for the new comma_compact_nulls option in the encoding section.
- Added an "Other ports" reference table.
Tests
- Added tests covering comma_compact_nulls behavior, round-trip interaction, filtering, and nested list scenarios.

…at.COMMA`

…list serialization

…` option

coderabbitai · 2025-10-16T20:11:24Z

Walkthrough

A new comma_compact_nulls EncodeOptions flag was added and threaded through the encoding pipeline to optionally omit None entries from COMMA-formatted lists; documentation and tests were updated to describe and verify the behavior.

Changes

Cohort / File(s)	Summary
Documentation `README.rst`, `docs/README.rst`	Documented the new `comma_compact_nulls` option and added an "Other ports" table entry in docs.
Configuration `src/qs_codec/models/encode_options.py`	Added public field `comma_compact_nulls: bool = False` to `EncodeOptions` with docstring limiting it to `ListFormat.COMMA`.
Encoding Logic `src/qs_codec/encode.py`	Threaded `comma_compact_nulls` into `encode()` → `_encode()`; in COMMA mode build `comma_items`, optionally filter out `None` when flag is true, track `comma_effective_length`, and propagate the flag to recursive calls. Adjusted single-item round-trip logic to consider effective length.
Tests `tests/unit/encode_test.py`	Updated internal `_encode` invocations to include `comma_compact_nulls=False` where appropriate and added tests validating null compaction, key omission when filtering, round-trip marker behavior, and token generation with `comma_compact_nulls`.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant Client
    participant encode as encode()
    participant _encode as _encode()
    participant Filter as NullFilter
    participant Join as JoinItems
    Client->>encode: call with EncodeOptions(comma_compact_nulls=True)
    encode->>_encode: enter list branch (comma mode), pass flag
    _encode->>_encode: build comma_items [T,F,None,T]
    alt comma_compact_nulls == true
        _encode->>Filter: remove None -> [T,F,T]
    else comma_compact_nulls == false
        _encode->>_encode: keep placeholders -> [T,F, ,T]
    end
    _encode->>Join: normalize / encode items
    Join->>encode: obj_keys_value ("true,false,true" or with empty slots)
    encode->>Client: serialized output

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

test

Poem

🐇 I hopped through lists with nimble paws,
Dropping None without a pause.
Commas tidy, slots made slim,
True,false,true — a cleaner hymn.
— from a rabbit who loves neat code 🌿

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "add `EncodeOptions.comma_compact_nulls`" directly and clearly describes the main change in the changeset. The title is specific and concise, accurately identifying the new feature being added to the EncodeOptions class. The emoji usage is appropriate for a feature addition. The title is not vague or misleading and would help teammates understand the primary change when scanning commit history.
Description Check	✅ Passed	The PR description provides substantive coverage of the changes, including a clear summary of the new feature, implementation details with links to specific code sections, documentation updates, and testing information. While the description does not strictly follow the template's structured format (missing explicit "Type of change" checkboxes, a dedicated "How Has This Been Tested" section with reproduction steps, and a checklist), the content is mostly complete and provides sufficient context for understanding and reviewing the pull request. The description is neither vague nor generic, offering specific details about the feature's purpose and behavior.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feat/comma_compact_nulls

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bf0b94e and 228aabd.

📒 Files selected for processing (1)

src/qs_codec/models/encode_options.py (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

src/qs_codec/models/encode_options.py

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

GitHub Check: Codacy Static Code Analysis

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

codacy-production · 2025-10-16T20:12:26Z

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ +0.00% (target: -1.00%)	✅ 100.00%

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (`92304f6`)	1150	1150	100.00%
Head commit (`bf0b94e`)	1162 (+12)	1162 (+12)	100.00% (+0.00%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#31)	17	17	100.00%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings Change summary preferences

codacy-production · 2025-10-16T20:12:26Z

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
✅ +0.00% (target: -1.00%)	✅ 100.00%

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (`92304f6`)	1150	1150	100.00%
Head commit (`228aabd`)	1162 (+12)	1162 (+12)	100.00% (+0.00%)

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#31)	17	17	100.00%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings Change summary preferences

codecov · 2025-10-16T20:12:31Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (92304f6) to head (228aabd).
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main       #31   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           16        16           
  Lines         1150      1162   +12     
=========================================
+ Hits          1150      1162   +12

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…s.py

techouse added 5 commits October 16, 2025 21:02

✨ add comma_compact_nulls option to encode_options.py for `ListForm…

b190d37

…at.COMMA`

✨ implement comma_compact_nulls handling in encode.py for improved …

05e5f3d

…list serialization

✅ add tests for comma_compact_nulls functionality in encode_test.py

7bf9aa5

💡 update README to include comma_compact_nulls option details

99f2e88

✅ add test for non-comma generator handling with `comma_compact_nulls…

bf0b94e

…` option

techouse self-assigned this Oct 16, 2025

techouse added the enhancement New feature or request label Oct 16, 2025

🚨 improve docstring for comma_compact_nulls option in encode_option…

228aabd

…s.py

techouse merged commit 06a2a92 into main Oct 16, 2025
19 checks passed

techouse deleted the feat/comma_compact_nulls branch October 16, 2025 20:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

✨ add `EncodeOptions.comma_compact_nulls` #31

✨ add `EncodeOptions.comma_compact_nulls` #31

Uh oh!

techouse commented Oct 16, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

coderabbitai bot commented Oct 16, 2025 •

edited

Loading

Uh oh!

codacy-production bot commented Oct 16, 2025

Uh oh!

codacy-production bot commented Oct 16, 2025 •

edited

Loading

Uh oh!

codecov bot commented Oct 16, 2025 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

✨ add EncodeOptions.comma_compact_nulls #31

✨ add EncodeOptions.comma_compact_nulls #31

Uh oh!

Conversation

techouse commented Oct 16, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Suggested labels

Poem

Pre-merge checks and finishing touches

Uh oh!

codacy-production bot commented Oct 16, 2025

Coverage summary from Codacy

See diff coverage on Codacy

See your quality gate settings Change summary preferences

Uh oh!

codacy-production bot commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage summary from Codacy

See diff coverage on Codacy

See your quality gate settings Change summary preferences

Uh oh!

codecov bot commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

✨ add `EncodeOptions.comma_compact_nulls` #31

✨ add `EncodeOptions.comma_compact_nulls` #31

techouse commented Oct 16, 2025 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Oct 16, 2025 •

edited

Loading

codacy-production bot commented Oct 16, 2025 •

edited

Loading

codecov bot commented Oct 16, 2025 •

edited

Loading