No matters your religion, IMAP4 or HTTP, you should not worries about accessing easily header and associated attributes, adjectives or values.

Programming language: Python
License: MIT License
Latest version: v2.2.3

kiss-headers alternatives and similar packages

Based on the "HTTP" category.
Alternatively, view kiss-headers alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of kiss-headers or a related project?

Add another 'HTTP' Package


HTTP Headers for Humans 👋

Object oriented headers, parser and builder.

❓ Why

No matter if you are currently building software using HTTP or IMAP (message, email), you should not worry about easily accessing header and associated attributes, adjectives or values.

I have seen so many chunks of code trying to deal with these headers; often I saw this implementation:

charset = headers['Content-Type'].split(';')[-1].split('=')[-1].replace('"', '')

No more of that!

🔪 Features

kiss-headers is a basic library that allow you to handle headers as objects.

  • A backwards-compatible syntax using bracket style.
  • Capability to alter headers using simple, human-readable operator notation + and -.
  • Flexibility if headers are from an email or HTTP, use as you need with one library.
  • Ability to parse any object and extract recognized headers from it, it also supports UTF-8 encoded headers.
  • Fully type-annotated.
  • Provide great auto-completion in Python interpreter or any capable IDE.
  • No dependencies. And never will be.
  • 90% test coverage.

Plus all the features that you would expect from handling headers...

  • Properties syntax for headers and attribute in header.
  • Supports headers and attributes OneToOne, OneToMany and ManySquashedIntoOne.
  • Capable of parsing bytes, fp, str, dict, email.Message, requests.Response, httpx._models.Response and urllib3.HTTPResponse.
  • Automatically unquote and unfold the value of an attribute when retrieving it.
  • Keep headers and attributes ordering.
  • Case insensitive with header name and attribute key.
  • Character - equal _ in addition of above feature.
  • Any syntax you like, we like.

✨ Installation

Whatever you like, use pipenv or pip, it simply works. Requires Python 3.6+ installed.

pip install kiss-headers --upgrade

🍰 Usage

Quick start

parse_it() method takes bytes, str, fp, dict, email.Message or even a requests.Response or httpx._models.Response itself and returns a Headers object.

from requests import get
from kiss_headers import parse_it

response = get('https://www.google.fr')
headers = parse_it(response)

headers.content_type.charset  # output: ISO-8859-1
# Its the same as
headers["content-type"]["charset"]  # output: ISO-8859-1

Do not forget that headers are not OneToOne. One header can be repeated multiple times and attributes can have multiple values within the same header.

from kiss_headers import parse_it

my_cookies = """set-cookie: 1P_JAR=2020-03-16-21; expires=Wed, 15-Apr-2020 21:27:31 GMT; path=/; domain=.google.fr; Secure; SameSite=none
set-cookie: CONSENT=WP.284b10; expires=Fri, 01-Jan-2038 00:00:00 GMT; path=/; domain=.google.fr"""

headers = parse_it(my_cookies)

type(headers.set_cookie)  # output: list
headers.set_cookie[0].expires # output: Wed, 15-Apr-2020 21:27:31 GMT
headers.set_cookie[0]._1p_jar # output: 2020-03-16-21
headers.set_cookie[0]["1P_JAR"] # output: 2020-03-16-21

Since v2.1 you can transform an Header object to its target CustomHeader subclass to access more methods.

from kiss_headers import parse_it, get_polymorphic, SetCookie

my_cookies = """set-cookie: 1P_JAR=2020-03-16-21; expires=Wed, 15-Apr-2020 21:27:31 GMT; path=/; domain=.google.fr; Secure; SameSite=none
set-cookie: CONSENT=WP.284b10; expires=Fri, 01-Jan-2038 00:00:00 GMT; path=/; domain=.google.fr"""

headers = parse_it(my_cookies)

type(headers.set_cookie[0])  # output: Header

set_cookie = get_polymorphic(headers.set_cookie[0], SetCookie)

type(set_cookie)  # output: SetCookie

set_cookie.get_cookie_name()  # output: 1P_JAR
set_cookie.get_expire()  # output: datetime(...)

Just a note: Accessing a header that has the same name as a reserved keyword must be done this way :

headers = parse_it('From: Ousret; origin=www.github.com\nIS: 1\nWhile: Not-True')

# this flavour
headers.from_ # to access From, just add a single underscore to it
# or.. just using :

🛠️ Create headers from objects

Introduced in the version 2.0, kiss-headers now allow you to create headers with more than 40+ ready-to-use, fully documented, header objects.

1st example usage

from kiss_headers import Headers, Authorization
from requests import get

response = get("https://httpbin.org/bearer", headers=Headers(Authorization("Bearer", "qwerty")))
print(response.status_code)  # 200

2nd example usage

from kiss_headers import *

headers = (
    + UserAgent(
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:50.0) Gecko/20100101 Firefox/50.0"
    + Accept("text/html")
    + Accept("application/xhtml+xml")
    + Accept("application/xml", qualifier=0.9)
    + Accept(qualifier=0.8)
    + AcceptLanguage("en-US")
    + AcceptLanguage("en", qualifier=0.5)
    + AcceptEncoding("gzip")
    + AcceptEncoding("deflate")
    + AcceptEncoding("br")
    + Referer("https://developer.mozilla.org/testpage.html")
    + Connection(should_keep_alive=True)
    + UpgradeInsecureRequests()
    + IfModifiedSince("Mon, 18 Jul 2016 02:36:04 GMT")
    + IfNoneMatch("c561c68d0ba92bbeb8b0fff2a9199f722e3a621a")
    + CacheControl(max_age=0)

raw_headers = str(headers)

raw_headers now retain the following :

Host: developer.mozilla.org
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:50.0) Gecko/20100101 Firefox/50.0
Accept: text/html, application/xhtml+xml, application/xml; q="0.9", */*; q="0.8"
Accept-Language: en-US, en; q="0.5"
Accept-Encoding: gzip, deflate, br
Referer: https://developer.mozilla.org/testpage.html
Connection: keep-alive
Upgrade-Insecure-Requests: 1
If-Modified-Since: Mon, 18 Jul 2016 02:36:04 GMT
If-None-Match: "c561c68d0ba92bbeb8b0fff2a9199f722e3a621a"
Cache-Control: max-age="0"

See the complete list of available header class in the full documentation. Also, you can create your own custom header object using the class kiss_headers.CustomHeader.

📜 Documentation

See the full documentation for advanced usages : www.kiss-headers.tech

👤 Contributing

Contributions, issues and feature requests are very much welcome. Feel free to check issues page if you want to contribute.

Firstly, after getting your own local copy, run ./scripts/install to initialize your virtual environment. Then run ./scripts/check before you commit, make sure everything is still working.

Remember to keep it sweet and simple when contributing to this project.

📝 License

Copyright © 2020 Ahmed TAHRI @Ousret. This project is MIT licensed.

*Note that all licence references and agreements mentioned in the kiss-headers README section above are relevant to that project's source code only.