HeaderParser API

synopsis:

HTTP header parser classes

HeaderParser Class

class parser_header.parser.HeaderParser(data=None, **kwargs)[source]

Comprehensive HTTP header parser supporting all standard and custom headers.

Parameters:

  • data (str | bytes | None) – Raw header string or bytes to parse

  • kwargs – Header key-value pairs (underscores converted to hyphens)

Example:

# From raw data
parser = HeaderParser("content-type: application/json")

# From kwargs
parser = HeaderParser(content_type='application/json', user_agent='MyApp')

# Mixed
parser = HeaderParser("accept: */*", content_type='json')

Constructor and Factory Methods

HeaderParser.__init__(data=None, **kwargs)[source]

Initialize HeaderParser with optional data and/or kwargs.

classmethod HeaderParser.from_dict(headers)[source]

Create HeaderParser from a dictionary.

Parameters:

headers (dict) – Dictionary of header name-value pairs

Returns:

New HeaderParser instance

Return type:

HeaderParser

parser = HeaderParser.from_dict({
    'Content-Type': 'application/json',
    'Authorization': 'Bearer token'
})
classmethod HeaderParser.from_kwargs(**kwargs)[source]

Create HeaderParser from keyword arguments.

Parameters:

kwargs – Header key-value pairs

Returns:

New HeaderParser instance

Return type:

HeaderParser

parser = HeaderParser.from_kwargs(
    content_type='application/json',
    accept='*/*'
)
classmethod HeaderParser.from_requests_response(response)[source]

Create HeaderParser from a requests Response object.

Parameters:

response – requests Response object

Returns:

New HeaderParser instance

Return type:

HeaderParser

import requests
response = requests.get('https://example.com')
parser = HeaderParser.from_requests_response(response)

Parsing Methods

HeaderParser.parse(data=None, **kwargs)[source]

Parse raw HTTP headers and/or kwargs.

Parameters:

  • data (str | bytes | None) – Raw header string/bytes

  • kwargs – Additional headers as key=value pairs

Returns:

Dictionary of parsed headers

Return type:

dict

parser = HeaderParser()
parser.parse("content-type: text/html", accept='*/*')

Setting Methods

HeaderParser.set(name=None, value=None, **kwargs)[source]

Set header(s) with parsing.

Parameters:

  • name (str | None) – Header name (optional if using kwargs)

  • value (Any | None) – Header value (required if name provided)

  • kwargs – Header key=value pairs

Returns:

self for chaining

Return type:

HeaderParser

Raises:

ValueError – If name provided without value

parser.set('Content-Type', 'application/json')
parser.set(user_agent='Mozilla', accept='*/*')
parser.set('Auth', 'Bearer x', x_request_id='123')
HeaderParser.set_raw(name=None, value=None, **kwargs)[source]

Set header(s) without parsing the value.

Parameters:

  • name – Header name

  • value – Header value (stored as-is)

  • kwargs – Header key=value pairs

Returns:

self for chaining

Return type:

HeaderParser

# Value stored as string, not parsed
parser.set_raw('cache-control', 'max-age=3600')
HeaderParser.update(data=None, **kwargs)[source]

Update headers from dict and/or kwargs.

Parameters:

  • data (dict | None) – Dictionary of headers

  • kwargs – Additional headers

Returns:

self for chaining

Return type:

HeaderParser

parser.update({'Accept': '*/*'}, user_agent='Test')
HeaderParser.remove(*names)[source]

Remove headers by name.

Parameters:

names – Header names to remove

Returns:

self for chaining

Return type:

HeaderParser

parser.remove('x-custom', 'accept')
HeaderParser.clear()[source]

Clear all headers and cookies.

Returns:

self for chaining

Return type:

HeaderParser

Accessing Methods

HeaderParser.get(name, default=None)[source]

Get header value by name (case-insensitive).

Parameters:

  • name (str) – Header name

  • default – Default value if not found

Returns:

Header value or default

parser.get('content-type')  # HeaderValue or string
parser.get('missing', 'N/A')  # 'N/A'
HeaderParser.__getitem__(name)[source]

Get header with bracket notation.

Parameters:

name – Header name

Raises:

KeyError – If header not found

parser['content-type']
HeaderParser.__setitem__(name, value)[source]

Set header with bracket notation.

parser['Content-Type'] = 'application/json'
HeaderParser.__delitem__(name)[source]

Delete header with bracket notation.

Raises:

KeyError – If header not found

del parser['x-custom']
HeaderParser.__contains__(name)[source]

Check if header exists.

Returns:

True if header exists

Return type:

bool

'content-type' in parser  # True/False
HeaderParser.__len__()[source]

Get number of headers.

Returns:

Header count

Return type:

int

HeaderParser.__iter__()[source]

Iterate over header names.

for name in parser:
    print(name)
HeaderParser.keys()[source]

Get list of header names.

Returns:

List of names

Return type:

list[str]

HeaderParser.values()[source]

Get list of header values.

Returns:

List of values

Return type:

list

HeaderParser.items()[source]

Get list of (name, value) tuples.

Returns:

List of tuples

Return type:

list[tuple]

Export Methods

HeaderParser.to_dict(stringify=False)[source]

Export headers as dictionary.

Parameters:

stringify (bool) – If True, convert all values to strings

Returns:

Dictionary of headers

Return type:

dict

parser.to_dict()  # With parsed values
parser.to_dict(stringify=True)  # All strings
HeaderParser.to_raw()[source]

Convert headers to raw format string.

Returns:

Raw headers string

Return type:

str

print(parser.to_raw())
# content-type: application/json
# accept: */*
HeaderParser.to_requests_headers()[source]

Convert to format suitable for requests library.

Returns:

Dictionary with string values

Return type:

dict[str, str]

import requests
headers = parser.to_requests_headers()
requests.get(url, headers=headers)

Properties

HeaderParser.content_type

Get Content-Type value (without parameters).

Type:

str | None

HeaderParser.content_length

Get Content-Length as integer.

Type:

int | None

HeaderParser.user_agent

Get User-Agent value.

Type:

str | None

HeaderParser.origin

Get Origin value.

Type:

str | None

HeaderParser.referer

Get Referer value.

Type:

str | None

Utility Methods

HeaderParser.is_cors()[source]

Check if request is CORS (has Origin header).

Returns:

True if CORS request

Return type:

bool

HeaderParser.is_ajax()[source]

Check if request is AJAX (X-Requested-With: XMLHttpRequest).

Returns:

True if AJAX request

Return type:

bool

HeaderParser.get_client_hints()[source]

Get all Client Hints (Sec-CH-*) headers.

Returns:

Dictionary of client hints

Return type:

dict

HeaderParser.get_sec_fetch_metadata()[source]

Get Sec-Fetch-* headers.

Returns:

Dictionary with site, mode, dest, user keys

Return type:

dict

HeaderValue Class

class parser_header.parser.HeaderValue[source]

Dataclass representing a header value with parameters.

value

Main header value.

Type:

str

params

Parameter dictionary.

Type:

dict[str, str]

Example:

# Created automatically when parsing Content-Type, etc.
parser.set('content-type', 'text/html; charset=utf-8')
hv = parser.get('content-type')

print(hv.value)   # 'text/html'
print(hv.params)  # {'charset': 'utf-8'}
print(str(hv))    # 'text/html; charset=utf-8'