httpdate 1.0.0

Parse and format HTTP dates, such as Last-Modified and If-Modified-Since headers.

httpdate

---

httpdate is a Python library for parsing and formatting HTTP date fields that are used in headers like Last-Modified and If-Modified-Since. It does so in strict accordance with RFC 9110 Section 5.6.7.

It has only one dependency, which is my tiny leapseconds library that just provides a tuple of official leap seconds.

HTTP date formats

All HTTP dates (eg, in Last-Modified headers) must be sent in this format:

# IMF-fixdate
Sun, 06 Nov 1994 08:49:37 GMT

However, RFC 9110 states that recipients must also accept two other obsolete formats:

# rfc850-date
Sunday, 06-Nov-94 08:49:37 GMT

# asctime-date
Sun Nov  6 08:49:37 1994

RFC 9110 criteria for the HTTP date field includes the following:

• It must be in one of the three accepted formats.
• It must represent time as an instance of UTC.
• It must represent weekday names and month names in English.
• It is case-sensitive.
• It must not have any additional whitespace.
• It must be semantically correct (eg, the weekday must be the correct weekday).
• It can include leap seconds (eg, 23:59:60).
• It must represent a year of 1900 or above.

It isn't stated explicitly in the RFCs, but httpdate will only consider a leap second semantically correct if it's an official leap second.

Installation

pip install httpdate

Usage

from httpdate import is_valid_httpdate, httpdate_to_unixtime, unixtime_to_httpdate

# Check if an HTTP date (eg, `Last-Modified` header) is valid:
is_valid_httpdate("Sun, 06 Nov 1994 08:49:37 GMT")

# Parse an HTTP date:
httpdate_to_unixtime("Sun, 06 Nov 1994 08:49:37 GMT")
# Parse an HTTP date (rfc850-date):
httpdate_to_unixtime("Sunday, 06-Nov-94 08:49:37 GMT")
# Parse an HTTP date (asctime-date):
httpdate_to_unixtime("Sun Nov  6 08:49:37 1994")

# Format a Unix timestamp as an HTTP date:
unixtime_to_httpdate(784111777)

• is_valid_httpdate(httpdate):
  • Args
    • Optional[str]
  • Returns
    • bool: True if input is valid, False if invalid or the input is None.
  • Raises
    • TypeError if input is not str or None.
• httpdate_to_unixtime(httpdate):
  • Args
    • Optional[str]
  • Returns
    • Optional[int]: A Unix timestamp (int) if input is valid, None if invalid or input is None.
  • Raises
    • TypeError if input is not str or None.
• unixtime_to_httpdate(unixtime):
  • Args
    • Optional[int]
  • Returns
    • Optional[str]: An HTTP date str if input is valid, None if invalid or input is None.
  • Raises
    • TypeError if input is not int or None.
    • ValueError if input represents a year below 1900 or above 9999.

Why Unix timestamps?

Unix timestamps are unambiguous, efficient, and can easily be converted to other date-time formats using only the standard library.

When a Last-Modified header is semantically correct, this conversion — from string to Unix timestamp and back to string — is lossless. (The only exception is leap seconds; for example Sat, 31 Dec 2016 23:59:60 GMT would be returned as Sun, 01 Jan 2017 00:00:00 GMT. Recipients should interpret these as being identical anyway.)

If you want to store the original string instead, just use is_valid_httpdate() to validate before storing.

License

httpdate is distributed under the terms of the MIT license.