httpdate
![Python Versions](https://img.shields.io/pypi/pyversions/httpdate.svg)
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 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
is_valid_httpdate("Sun, 06 Nov 1994 08:49:37 GMT")
try:
httpdate_to_unixtime("Sun, 06 Nov 1994 08:49:37 GMT")
httpdate_to_unixtime("Sunday, 06-Nov-94 08:49:37 GMT")
httpdate_to_unixtime("Sun Nov 6 08:49:37 1994")
except ValueError:
pass
try:
unixtime_to_httpdate(784111777)
except ValueError:
pass
is_valid_httpdate(httpdate)
:
- Args
httpdate (str)
: An HTTP date string.
- Returns
bool
: True if httpdate
is a valid HTTP date string, otherwise False.
- Raises
TypeError
if httpdate
is not of type str
.
httpdate_to_unixtime(httpdate)
:
- Args
httpdate (str)
: An HTTP date string.
- Returns
int
: A Unix timestamp (int
).
- Raises
TypeError
if httpdate
is not of type str
.ValueError
if httpdate
is not a valid HTTP date string.
unixtime_to_httpdate(unixtime)
:
- Args
unixtime (int)
: A Unix timestamp.
- Returns
str
: An HTTP date string.
- Raises
TypeError
if unixtime
is not of type int
.ValueError
if unixtime
represents a year before 1900, or if it is outside
the range supported by the operating system.
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.