Move normalize header functions from _utils.py to _models.py

[AstralScribe]

Summary

Issue: #3381

This PR refactors the normalize_header_key as an inline method and moves normalize_header_value function to _models.py from _utils.py.

Checklist

• I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.

[tomchristie]

Thanks. ☺️

I'd suggest we should stay consistent and use _normalize_header_key() and _normalize_header_value() here.
There's perhaps some more cleanup we could do in this particular case, but that's probably the best starting point.

[AstralScribe]

I have converted the inline method into a similar function.

[AstralScribe]

I have done some more refactoring, but I am not sure if this simplifies or complicates it. I had to add some things due to mypy type checking.

def _convert_mapping_to_sequence(
    mappings: typing.Union[typing.Mapping[str, str], typing.Mapping[bytes, bytes]],
) -> typing.Sequence[typing.Tuple[str | bytes, str | bytes]]:
    return [(k, v) for k, v in mappings.items()]


def _normalize_headers(
    headers: HeaderTypes | None, encoding: str | None
) -> list[tuple[bytes, bytes, bytes]]:
    """
    Coerce str/bytes into a strictly byte-wise HTTP headers.
    """
    if headers is None:
        return []

    if isinstance(headers, Headers):
        return list(headers._list)

    normalized_list: list[tuple[bytes, bytes, bytes]] = []

    if isinstance(headers, typing.Mapping):
        n_headers = _convert_mapping_to_sequence(headers)
    elif isinstance(headers, typing.Sequence):
        n_headers = headers

    for key, value in n_headers:
        if not isinstance(value, (str, bytes)):
            raise TypeError(f"Header value must be str or bytes, not {type(value)}")
        b_key = key if isinstance(key, bytes) else key.encode(encoding or "ascii")
        b_value = (
            value if isinstance(value, bytes) else value.encode(encoding or "ascii")
        )
        normalized_list.append((b_key, b_key.lower(), b_value))

    return normalized_list

It replaces the whole init with:

self._list = _normalize_headers(headers, encoding)

[tomchristie]

Exactly like this, yep. 👍
Just helps keep things neat & localised.

[tomchristie]

Thanks @AstralScribe. 😊

I have done some more refactoring, but I am not sure if this simplifies or complicates it. I had to add some things due to mypy type checking.

Let's take a pass on that particular follow-up. What you've got here is great as it is.