qs_codec.enums package

Submodules

qs_codec.enums.charset module

Definitions for character set handling.

This module exposes Charset, an enum of supported character sets used by the encoder/decoder. Each member’s value is the canonical Python codec name (e.g. "utf-8") that can be passed directly to str.encode / bytes.decode.

class qs_codec.enums.charset.Charset(*values)

Bases: _CharsetDataMixin, Enum

Supported character sets for query-string processing.

Each enum member’s value is the codec string understood by Python’s encoding APIs. Prefer accessing encoding instead of hard-coding literals.

LATIN1 = _CharsetDataMixin(encoding='iso-8859-1')

ISO-8859-1 (Latin-1) character encoding.

UTF8 = _CharsetDataMixin(encoding='utf-8')

UTF-8 character encoding.

encoding: str

qs_codec.enums.duplicates module

Duplicate-key handling strategies used during decoding.

When a query string contains the same key multiple times, decoders need a policy to resolve them. The Duplicates enum is referenced by DecodeOptions to control that behavior.

class qs_codec.enums.duplicates.Duplicates(*values)

Bases: Enum

Defines how to resolve duplicate keys produced during parsing.

This is consulted by the decoder when more than one value is encountered for the same key. It does not affect encoding.

Members

COMBINE

Combine duplicate keys into a single list of values (preserves order).

FIRST

Keep only the first occurrence and discard subsequent ones.

LAST

Keep only the last occurrence, overwriting prior ones.

COMBINE = 1

Combine duplicate keys into a single list of values (preserves order).

FIRST = 2

Keep only the first value encountered for the key.

LAST = 3

Keep only the last value encountered for the key.

qs_codec.enums.format module

URI component formatting strategies.

This module defines the Format enum that specifies how space and other characters are normalized in a percent-encoded query string after encoding. Two common profiles are provided:

• Format.RFC1738 – replaces “%20” with “+” in the final output.

• Format.RFC3986 – leaves “%20” as-is (default on the web today).

Use the functions on Formatter if you need direct access to the formatting operations.

class qs_codec.enums.format.Format(*values)

Bases: _FormatDataMixin, Enum

Supported URI component formatting profiles.

Each enum value packs a (format_name, formatter) tuple. After raw percent-encoding is performed by the encoder, the selected profile’s formatter is called to adjust the final textual representation (e.g., mapping "%20" to "+" for RFC 1738).

RFC1738 = _FormatDataMixin(format_name='RFC1738', formatter=<function Formatter.rfc1738>)

RFC 1738.

RFC3986 = _FormatDataMixin(format_name='RFC3986', formatter=<function Formatter.rfc3986>)

RFC 3986.

format_name: str

formatter: Callable[[str], str]

class qs_codec.enums.format.Formatter

Bases: object

Formatting helpers used by Format.

These functions expect already percent-encoded input and adjust only the representation of spaces (and related normalization) according to the selected RFC profile. They do not perform percent-encoding themselves.

static rfc1738(value: str) → str

Apply RFC 1738 post-processing.

Replaces occurrences of "%20" with "+" to match the historical application/x-www-form-urlencoded semantics described in RFC 1738. The input is assumed to already be percent-encoded; only the space representation is changed.

static rfc3986(value: str) → str

Apply RFC 3986 post-processing.

Returns the input unchanged (spaces remain encoded as "%20"). This is the modern, conservative representation used by most tooling today.

qs_codec.enums.list_format module

List formatting strategies for query‑string arrays.

This module defines small generator functions and an enum that the encoder uses to format list (array) keys, e.g., foo[]=1, foo[0]=1, foo=1,2, or repeated keys foo=1&foo=2.

class qs_codec.enums.list_format.ListFormat(*values)

Bases: _ListFormatDataMixin, Enum

Available list formatting options for the encoder.

Each member pairs a stable name with a generator function from ListFormatGenerator:

• BRACKETS: foo[] for each element.

• INDICES: foo[0], foo[1], …

• REPEAT: repeat the key per value (foo=1&foo=2).

• COMMA: single key with comma‑joined values (foo=1,2).

These options control only how keys are produced; value encoding and delimiter handling are governed by other options.

BRACKETS = _ListFormatDataMixin(list_format_name='BRACKETS', generator=<function ListFormatGenerator.brackets>)

Use brackets to represent list items, for example foo[]=123&foo[]=456&foo[]=789.

COMMA = _ListFormatDataMixin(list_format_name='COMMA', generator=<function ListFormatGenerator.comma>)

Use commas to represent list items, for example foo=123,456,789.

INDICES = _ListFormatDataMixin(list_format_name='INDICES', generator=<function ListFormatGenerator.indices>)

Use indices to represent list items, for example foo[0]=123&foo[1]=456&foo[2]=789.

REPEAT = _ListFormatDataMixin(list_format_name='REPEAT', generator=<function ListFormatGenerator.repeat>)

Use a repeat key to represent list items, for example foo=123&foo=456&foo=789.

generator: Callable[[str, str | None], str]

list_format_name: str

class qs_codec.enums.list_format.ListFormatGenerator

Bases: object

Factory of tiny helpers that format a list element key segment.

Each static method returns the string that should be appended to the current key prefix to represent one element in a list. The encoder selects the method based on the chosen ListFormat variant.

static brackets(prefix: str, key: str | None = None) → str

Return the key for a list element using empty brackets.

Example

prefix='foo' → 'foo[]'

Parameters:

• prefix – The current key prefix (e.g., 'foo').

• key – Unused for this strategy.

Returns:

The formatted key segment.

static comma(prefix: str, key: str | None = None) → str

Return the key for comma‑separated lists (no change).

The encoder will join values with commas instead of repeating the key.

Parameters:

• prefix – Current key prefix.

• key – Unused for this strategy.

Returns:

The unchanged prefix.

static indices(prefix: str, key: str | None = None) → str

Return the key for an indexed list element.

Example

prefix='foo', key='0' → 'foo[0]'

Parameters:

• prefix – Current key prefix.

• key – The numeric index string for this element.

Returns:

The formatted key.

static repeat(prefix: str, key: str | None = None) → str

Return the key for “repeat key” lists (no change).

Example

prefix='foo' → 'foo' (the key is repeated per element)

Parameters:

• prefix – Current key prefix.

• key – Unused for this strategy.

Returns:

The unchanged prefix.

qs_codec.enums.sentinel module

Sentinel values and their percent-encoded forms.

Browsers sometimes include an utf8=… “sentinel” in application/x-www-form-urlencoded submissions to signal the character encoding that was used. This module exposes those sentinels as an Enum, where each member carries both the raw token (what the page emits) and the fully URL-encoded fragment (what appears on the wire).

class qs_codec.enums.sentinel.Sentinel(*values)

Bases: _SentinelDataMixin, Enum

All supported utf8 sentinels.

Each enum member provides:

• raw: the source token a browser starts with, and

• encoded: the final, percent-encoded utf8=… fragment.

CHARSET = _SentinelDataMixin(raw='✓', encoded='utf8=%E2%9C%93')

UTF‑8 sentinel indicating the request is UTF‑8 encoded.

This is the percent‑encoded UTF‑8 sequence for ✓, yielding the fragment utf8=%E2%9C%93.

ISO = _SentinelDataMixin(raw='&#10003;', encoded='utf8=%26%2310003%3B')

HTML‑entity sentinel used by non‑UTF‑8 submissions.

When a check mark (✓) appears but the page/form encoding is iso-8859-1 (or another charset that lacks ✓), browsers first HTML‑entity‑escape it as "✓" and then URL‑encode it, producing utf8=%26%2310003%3B.

encoded: str

raw: str

Module contents