This is a tzinfo subclass thant allows one to use the tzfile(5)
format timezone files to extract current and historical zone information.

Parameters:

fileobj – This can be an opened file stream or a file name that the time zone
information can be read from.

filename – This is an optional parameter specifying the source of the time zone
information in the event that fileobj is a file object. If omitted
and fileobj is a file stream, this parameter will be set either to
fileobj’s name attribute or to repr(fileobj).

Only construct a tzfile directly if you have a specific timezone
file on disk that you want to read into a Python tzinfo object.
If you want to get a tzfile representing a specific IANA zone,
(e.g. 'America/New_York'), you should call
dateutil.tz.gettz() with the zone identifier.

Examples:

Using the US Eastern time zone as an example, we can see that a tzfile
provides time zone information for the standard Daylight Saving offsets:

The tzfile structure contains a fully history of the time zone,
so historical dates will also have the right offsets. For example, before
the adoption of the UTC standards, New York used local solar mean time:

And during World War II, New York was on “Eastern War Time”, which was a
state of permanent daylight saving time:

The tzrange object is a time zone specified by a set of offsets and
abbreviations, equivalent to the way the TZ variable can be specified
in POSIX-like systems, but using Python delta objects to specify DST
start, end and offsets.

Parameters:

stdabbr – The abbreviation for standard time (e.g. 'EST').

stdoffset –

An integer or datetime.timedelta object or equivalent
specifying the base offset from UTC.

If unspecified, +00:00 is used.

dstabbr –

The abbreviation for DST / “Summer” time (e.g. 'EDT').

If specified, with no other DST information, DST is assumed to occur
and the default behavior or dstoffset, start and end is
used. If unspecified and no other DST information is specified, it
is assumed that this zone has no DST.

If this is unspecified and other DST information is is specified,
DST occurs in the zone but the time zone abbreviation is left
unchanged.

dstoffset – A an integer or datetime.timedelta object or equivalent
specifying the UTC offset during DST. If unspecified and any other DST
information is specified, it is assumed to be the STD offset +1 hour.

start –

A relativedelta.relativedelta object or equivalent specifying
the time and time of year that daylight savings time starts. To
specify, for example, that DST starts at 2AM on the 2nd Sunday in
March, pass:

relativedelta(hours=2,month=3,day=1,weekday=SU(+2))

If unspecified and any other DST information is specified, the default
value is 2 AM on the first Sunday in April.

end – A relativedelta.relativedelta object or equivalent
representing the time and time of year that daylight savings time
ends, with the same specification method as in start. One note is
that this should point to the first time in the standard zone, so if
a transition occurs at 2AM in the DST zone and the clocks are set back
1 hour to 1AM, set the hours parameter to +1.

tzstr objects are time zone objects specified by a time-zone string as
it would be passed to a TZ variable on POSIX-style systems (see
the GNU C Library: TZ Variable for more details).

There is one notable exception, which is that POSIX-style time zones use an
inverted offset format, so normally GMT+3 would be parsed as an offset
3 hours behind GMT. The tzstr time zone object will parse this as an
offset 3 hours ahead of GMT. If you would like to maintain the POSIX
behavior, pass a True value to posix_offset.

This function assumes that an imaginary datetime represents what the
wall time would be in a zone had the offset transition not occurred, so
it will always fall forward by the transition’s change in offset.

As a note, datetime.astimezone() is guaranteed to produce a valid,
existing datetime, so a round-trip to and from UTC is sufficient to get
an extant datetime, however, this generally “falls back” to an earlier time
rather than falling forward to the STD side (though no guarantees are made
about this behavior).

Parameters:

dt – A datetime.datetime which may or may not exist.

Returns:

Returns an existing datetime.datetime. If dt was not
imaginary, the datetime returned is guaranteed to be the same object
passed to the function.