Skip to main content

argparse for mail-style headers

Project description

Project Status: Active — The project has reached a stable, usable state and is being actively developed. CI Status coverage pyversions MIT License

GitHub | PyPI | Documentation | Issues | Changelog

headerparser parses key-value pairs in the style of RFC 822 (e-mail) headers and converts them into case-insensitive dictionaries with the trailing message body (if any) attached. Fields can be converted to other types, marked required, or given default values using an API based on the standard library’s argparse module. (Everyone loves argparse, right?) Low-level functions for just scanning header fields (breaking them into sequences of key-value pairs without any further processing) are also included.

The Format

RFC 822-style headers are header fields that follow the general format of e-mail headers as specified by RFC 822 and friends: each field is a line of the form “Name: Value”, with long values continued onto multiple lines (“folded”) by indenting the extra lines. A blank line marks the end of the header section and the beginning of the message body.

This basic grammar has been used by numerous textual formats besides e-mail, including but not limited to:

  • HTTP request & response headers

  • Usenet messages

  • most Python packaging metadata files

  • Debian packaging control files

  • META-INF/MANIFEST.MF files in Java JARs

  • a subset of the YAML serialization format

— all of which this package can parse.

Installation

headerparser requires Python 3.8 or higher. Just use pip for Python 3 (You have pip, right?) to install headerparser:

python3 -m pip install headerparser

Examples

Define a parser:

>>> import headerparser
>>> parser = headerparser.HeaderParser()
>>> parser.add_field('Name', required=True)
>>> parser.add_field('Type', choices=['example', 'demonstration', 'prototype'], default='example')
>>> parser.add_field('Public', type=headerparser.BOOL, default=False)
>>> parser.add_field('Tag', multiple=True)
>>> parser.add_field('Data')

Parse some headers and inspect the results:

>>> msg = parser.parse('''\
... Name: Sample Input
... Public: yes
... tag: doctest, examples,
...   whatever
... TAG: README
...
... Wait, why I am using a body instead of the "Data" field?
... ''')
>>> sorted(msg.keys())
['Name', 'Public', 'Tag', 'Type']
>>> msg['Name']
'Sample Input'
>>> msg['Public']
True
>>> msg['Tag']
['doctest, examples,\n  whatever', 'README']
>>> msg['TYPE']
'example'
>>> msg['Data']
Traceback (most recent call last):
    ...
KeyError: 'data'
>>> msg.body
'Wait, why I am using a body instead of the "Data" field?\n'

Fail to parse headers that don’t meet your requirements:

>>> parser.parse('Type: demonstration')
Traceback (most recent call last):
    ...
headerparser.errors.MissingFieldError: Required header field 'Name' is not present
>>> parser.parse('Name: Bad type\nType: other')
Traceback (most recent call last):
    ...
headerparser.errors.InvalidChoiceError: 'other' is not a valid choice for 'Type'
>>> parser.parse('Name: unknown field\nField: Value')
Traceback (most recent call last):
    ...
headerparser.errors.UnknownFieldError: Unknown header field 'Field'

Allow fields you didn’t even think of:

>>> parser.add_additional()
>>> msg = parser.parse('Name: unknown field\nField: Value')
>>> msg['Field']
'Value'

Just split some headers into names & values and worry about validity later:

>>> for field in headerparser.scan('''\
... Name: Scanner Sample
... Unknown headers: no problem
... Unparsed-Boolean: yes
... CaSe-SeNsItIvE-rEsUlTs: true
... Whitespace around colons:optional
... Whitespace around colons  :  I already said it's optional.
...   That means you have the _option_ to use as much as you want!
...
... And there's a body, too, I guess.
... '''): print(field)
('Name', 'Scanner Sample')
('Unknown headers', 'no problem')
('Unparsed-Boolean', 'yes')
('CaSe-SeNsItIvE-rEsUlTs', 'true')
('Whitespace around colons', 'optional')
('Whitespace around colons', "I already said it's optional.\n  That means you have the _option_ to use as much as you want!")
(None, "And there's a body, too, I guess.\n")

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

headerparser-0.5.2.tar.gz (31.1 kB view details)

Uploaded Source

Built Distribution

headerparser-0.5.2-py3-none-any.whl (18.1 kB view details)

Uploaded Python 3

File details

Details for the file headerparser-0.5.2.tar.gz.

File metadata

  • Download URL: headerparser-0.5.2.tar.gz
  • Upload date:
  • Size: 31.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.13.0

File hashes

Hashes for headerparser-0.5.2.tar.gz
Algorithm Hash digest
SHA256 2e24ae218ed5d2ef5839fafeff084c40ee1e317bbbe6489cfe333385d7cb98e7
MD5 a1743cf84b081f01f6c4069e87c8a163
BLAKE2b-256 8697ecdbe764cb2909999ca51db3a76852aaba4f938c309c41b86014c90a8d4b

See more details on using hashes here.

File details

Details for the file headerparser-0.5.2-py3-none-any.whl.

File metadata

  • Download URL: headerparser-0.5.2-py3-none-any.whl
  • Upload date:
  • Size: 18.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.13.0

File hashes

Hashes for headerparser-0.5.2-py3-none-any.whl
Algorithm Hash digest
SHA256 e89d35c8cfe494f7fdec6eff14b4a9d5542fc2b2b8f1b50d750b62d822d0b8d6
MD5 a9d5985f29b1f957882ad7f529b6e778
BLAKE2b-256 0f879b5b7eb8eade5d5c5357b19ced4b719c0c0815089c5dc0e9a68cd3b8ff5c

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page