CookieParser API¶

CookieParser Class¶

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

Parser for HTTP cookies with multiple extraction methods.

Parameters:

data (str | bytes | None) – Raw cookie string or bytes to parse
kwargs – Cookie key-value pairs (underscores converted to hyphens)

Example:

# From raw data
cookies = CookieParser("cookie: session=abc; user=john")

# From kwargs
cookies = CookieParser(session='abc', user='john')

# Mixed
cookies = CookieParser("cookie: a=1", b='2', c='3')

Constructor and Factory Methods¶

CookieParser.__init__(data=None, **kwargs)[source]¶: Initialize CookieParser with optional data and/or kwargs.

classmethod CookieParser.from_dict(cookies)[source]¶

Create CookieParser from a dictionary.

Parameters:: cookies (dict[str, str]) – Dictionary of cookie name-value pairs
Returns:: New CookieParser instance
Return type:: CookieParser

cookies = CookieParser.from_dict({
    'session': 'abc123',
    'user': 'john'
})

classmethod CookieParser.from_kwargs(**kwargs)[source]¶

Create CookieParser from keyword arguments.

Parameters:: kwargs – Cookie key-value pairs
Returns:: New CookieParser instance
Return type:: CookieParser

cookies = CookieParser.from_kwargs(
    session='abc123',
    auth_token='xyz'
)

Parsing Method¶

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

Parse cookies from raw data and/or kwargs.

Parameters:

data (str | bytes | None) – Raw cookie string/bytes
kwargs – Additional cookies as key=value pairs

Returns:

Dictionary of cookies

Return type:

dict[str, str]

cookies = CookieParser()
cookies.parse("cookie: a=1; b=2", c='3')
# Result: {'a': '1', 'b': '2', 'c': '3'}

Setting Methods¶

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

Set cookie(s).

Parameters:

name (str | None) – Cookie name (optional if using kwargs)
value (str | None) – Cookie value (required if name provided)
kwargs – Cookie key=value pairs

Returns:

self for chaining

Return type:

CookieParser

Raises:

ValueError – If name provided without value

cookies.set('session', 'abc123')
cookies.set(user='john', token='xyz')
cookies.set('a', '1', b='2', c='3')

CookieParser.update(data=None, **kwargs)[source]¶

Update cookies from dict and/or kwargs.

Parameters:

data (dict[str, str] | None) – Dictionary of cookies
kwargs – Additional cookies

Returns:

self for chaining

Return type:

CookieParser

cookies.update({'a': '1', 'b': '2'}, c='3')

CookieParser.remove(*names)[source]¶

Remove cookies by name.

Parameters:: names – Cookie names to remove
Returns:: self for chaining
Return type:: CookieParser

cookies.remove('session', 'token')

CookieParser.clear()[source]¶

Clear all cookies.

Returns:: self for chaining
Return type:: CookieParser

Accessing Methods¶

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

Get specific cookie value.

Parameters:

name (str) – Cookie name (underscores and hyphens interchangeable)
default – Default value if not found

Returns:

Cookie value or default

Return type:

str | None

cookies.get('session')           # 'abc123'
cookies.get('user-id')           # Works
cookies.get('user_id')           # Also works
cookies.get('missing', 'N/A')    # 'N/A'

CookieParser.__getitem__(name)[source]¶

Get cookie with bracket notation.

Parameters:: name – Cookie name
Raises:: KeyError – If cookie not found

cookies['session']  # 'abc123'

CookieParser.__setitem__(name, value)[source]¶

Set cookie with bracket notation.

cookies['session'] = 'new_value'

CookieParser.__delitem__(name)[source]¶

Delete cookie with bracket notation.

Raises:: KeyError – If cookie not found

del cookies['session']

CookieParser.__contains__(name)[source]¶

Check if cookie exists.

Returns:: True if cookie exists
Return type:: bool

'session' in cookies  # True/False

CookieParser.__len__()[source]¶

Get number of cookies.

Returns:: Cookie count
Return type:: int

CookieParser.__iter__()[source]¶

Iterate over cookie names.

for name in cookies:
    print(f"{name}={cookies[name]}")

CookieParser.keys()[source]¶

Get list of cookie names.

Returns:: List of names
Return type:: list[str]

CookieParser.values()[source]¶

Get list of cookie values.

Returns:: List of values
Return type:: list[str]

CookieParser.items()[source]¶

Get list of (name, value) tuples.

Returns:: List of tuples
Return type:: list[tuple[str, str]]

Output Methods¶

CookieParser.to_cookie_header(data=None, **kwargs)[source]¶

Convert cookies to Cookie header format.

Parameters:

data (str | bytes | None) – Optional new data to parse first
kwargs – Additional cookies to include

Returns:

Cookie header string (semicolon-separated)

Return type:

str

cookies = CookieParser(session='abc', user='john')

cookies.to_cookie_header()
# "session=abc; user=john"

cookies.to_cookie_header(token='xyz')
# "session=abc; user=john; token=xyz"

CookieParser.to_dict(data=None, **kwargs)[source]¶

Get cookies as dictionary.

Parameters:

data (str | bytes | None) – Optional new data to parse first
kwargs – Additional cookies to include

Returns:

Dictionary of cookies

Return type:

dict[str, str]

cookies = CookieParser(session='abc')

cookies.to_dict()
# {'session': 'abc'}

cookies.to_dict(extra='value')
# {'session': 'abc', 'extra': 'value'}

Method Chaining¶

All mutating methods return self for chaining:

cookies = (
    CookieParser()
    .set('session', 'abc')
    .set(user='john', token='xyz')
    .remove('token')
    .update({'lang': 'en'})
)

print(cookies.to_cookie_header())
# "session=abc; user=john; lang=en"

Complete Example¶

from parser_header import CookieParser

# Create and manipulate
cookies = CookieParser(session='initial')
cookies.set(user='john')
cookies['token'] = 'xyz123'
cookies.update({'lang': 'en'}, theme='dark')

# Access
print(cookies.get('session'))  # 'initial'
print(cookies['user'])         # 'john'
print(len(cookies))            # 5

# Check existence
print('token' in cookies)      # True
print('missing' in cookies)    # False

# Iterate
for name, value in cookies.items():
    print(f"{name}={value}")

# Output
print(cookies.to_cookie_header())
# "session=initial; user=john; token=xyz123; lang=en; theme=dark"

print(cookies.to_dict())
# {'session': 'initial', 'user': 'john', 'token': 'xyz123', 'lang': 'en', 'theme': 'dark'}

# Remove and clear
cookies.remove('theme', 'lang')
print(len(cookies))  # 3

cookies.clear()
print(len(cookies))  # 0