Metadata-Version: 2.4
Name: minimindslab-url-query-sort
Version: 0.1.0
Summary: Deterministically parse, normalize, and re-serialize URL query strings with stable key ordering and optional value sorting.
Author: MiniMindsLab
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# MiniMindsLab URL Query Sort

Deterministically parse, normalize, and re-serialize URL query strings with stable key ordering and optional value sorting.

## Features

- Stable query key ordering.
- Deterministic handling of repeated keys.
- Consistent normalization of:
  - empty keys
  - blank values
  - missing `=` segments
- Percent-encoding-safe round trip using UTF-8.
- Pure Python (standard library only), offline-friendly.

## Install

This package is standard Python packaging with `src/` layout.

## Usage

```python
from minimindslab_url_query_sort import normalize_query, parse_query

q = "b=2&a=3&a=1&flag&=x&empty="

pairs = parse_query(q)
# [('b', '2'), ('a', '3'), ('a', '1'), ('flag', ''), ('', 'x'), ('empty', '')]

normalized = normalize_query(q, sort_values_for_repeated_keys=True)
# '=x&a=1&a=3&b=2&empty=&flag='
```

## API

- `parse_query(query: str) -> list[tuple[str, str]]`
- `normalize_pairs(pairs: list[tuple[str, str]], *, sort_values_for_repeated_keys: bool = False) -> str`
- `normalize_query(query: str, *, sort_values_for_repeated_keys: bool = False) -> str`

### Ordering policy

- Keys are sorted lexicographically.
- For repeated keys:
  - default: preserve original relative order (stable)
  - optional: sort values lexicographically when `sort_values_for_repeated_keys=True`

### Normalization policy

- Missing `=` becomes blank value (e.g., `flag` -> `flag=`).
- Blank values are serialized with `=` (e.g., `x=`).
- Empty keys are allowed (e.g., `=v`).
