Welcome to CityTime’s documentation!

CityTime

Dependencies:
pytz
Thanks:
/u/phira

The CityTime object is my solution for the headache of time zones and daylight savings time. It takes the local time and the local time zone, and translates the time into UTC. The time can then be reproduced in various formats and also incremented forward and back while still adjusting for daylight savings time.

CityTime is a tool for comparing the time in two different cities. For example, let’s say it is 5pm in New York and 4pm in Chicago. CityTime will take both of those times and time zones, convert them to UTC, and by comparing the two CityTime objects, will tell you if they are the same time or not (in this case, they are).

Let’s say it’s 8pm in Tokyo on November 1 (UTC + 9), and 7am in New York on the same date (UTC - 4). If you create a CityTime object for each city, and compare the two, it will show that they are the same. However, if you tried the same thing on November 3 (after Daylight Savings Time ends), they will be different, because Japan does not follow Daylight Savings Time.

CityTime handles cases like those mentioned above by converting the input local time to UTC, while storing the Olson Database time zone, rather than just using a UTC offset. This way, local differences in the start and end of Daylight Savings Time are accounted for.

class citytime.citytime.CityTime(time: Union[_ForwardRef('CityTime'), datetime.datetime, str, NoneType] = None, tz: Union[str, NoneType] = None)

Object used for handling local times at different cities or time zones.

It translates everything to UTC, and then attaches the time zone for translating back to local time. CityTime can also handle incrementing the time forward or back, in order to compare two separate UTC equivalent times with each other.

CityTime objects can be instantiated using no parameters (creating a blank object that must be set later), a datetime.datetime object + time zone string, or another CityTime object.

Parameter tz will be ignored if parameter time is of type CityTime.

Parameters:time – str or datetime.datetime or CityTime
Raises:TypeError – If time argument is not CityTime, datetime.datetime or ISO8601
astimezone(time_zone: str) → datetime.datetime

Check to see what the local time would be in a different time zone.

Let’s say it is 8pm in Tokyo on November 1, and we would like to know what time it is in New York. Calling .astimezone(‘America/New_York’) from our CityTime object will show that it is 7am in New York.

change_tz(time_zone: str) → None

Change the time zone of a CityTime object that has already been set.

If you have a CityTime object set for New York City, for example, and you want to change it so that you have the local time for Los Angeles instead, this method will reset the time zone to Los Angeles’ time zone and can then output the local Los Angeles time and will no longer give New York City’s local time

copy() → citytime.citytime.CityTime

Returns a copy of this CityTime instance.

Return type:CityTime
day_abbr() → str

Get the abbreviated form of the calendar day of the week for the local time zone.

Return type:str
day_name() → str

Get the calendar day of the week for the local time zone.

Return type:str
epoch() → int

Returns the POSIX Epoch time.

Return type:int
increment(days: Union[int, float, NoneType] = None, hours: Union[int, float, NoneType] = None, minutes: Union[int, float, NoneType] = None, seconds: Union[int, float, NoneType] = None) → None

Increment the time forward or back while adjusting for daylight savings time.

This increments the underlying UTC time, but it also checks to make sure that the equivalent local time is a valid time.

For example, let’s say it’s 7am in New York on November 1. We want to know what the local time will be 24 hours later. By incrementing the time by +24 hours, it will show that the local time is now 6am. This is due to daylight savings time ending at 2am on November 2.

is_set() → bool

Checks to see whether a CityTime object has been created with or without the local time being set.

This is for instances where a someone might want to create a CityTime object, but will actually set its time later in the program.

local() → datetime.datetime

Outputs the time as a datetime.datetime object with the local time zone.

:rtype : datetime.datetime

local_minute() → int

Get just the local time, no date info, in the form of minutes.

:rtype : int

local_strftime(form: str) → str

The equivalent of datetime.datetime.strftime.

Convert the local time to a string as specified by the format argument. The format argument must be a string.

classmethod now(zone: str) → citytime.citytime.CityTime

Returns a CityTime object set to the user’s current local time, but taking a user input time zone.

offset() → str

Returns the local time zone’s offset from UTC.

Return type:str
set(date_time: datetime.datetime, time_zone: str) → None

Allows setting the local time after a CityTime object has been created.

Input can be with either another CityTime object, or with a datetime.datetime object plus a time zone string that refers to a time zone in the Olson database. It is important to note that when initiating or setting a CityTime object, the local time must include the date and the time zone. Otherwise, there would be no way to account for Daylight Savings Time.

set_iso_format(date_time: str, time_zone: str) → None

This method is called when setting the CityTime object using an ISO 8601 format string.

* The ISO formatted time MUST be UTC. It cannot accept an offset. *

In order to avoid having to use another dependency, it is very simple in its ability to parse the ISO format string. The string must be in the following format: YYYY-MM-DDTHH:MM:SS It will strip out and disregard any microseconds

time_string() → str

Get the local time in HHMM format.

Return type:str
timezone() → str

Outputs the local time zone (Olson database, string format).

:rtype : str

classmethod today() → citytime.citytime.CityTime

Returns a CityTime object set to the current time in UTC.

Return type:CityTime
tzinfo() → Any

Return a datetime.tzinfo implementation for the given timezone.

Equivalent to pytz.timezone(‘Time_zone_string’). It can then be used with datetime, with pytz.localize, etc.

:rtype : timezone

utc() → datetime.datetime

Outputs the time as a datetime.datetime object converted to UTC.

:rtype : datetime.datetime

utc_strftime(form: str) → str

The equivalent of datetime.datetime.strftime, but for UTC time.

Convert the time in UTC format to a string as specified by the format argument. The format argument must be a string.

weekday() → int

Get the numerical day of the week (0 = Monday, 6 = Sunday) for the local time zone.

Return type:int
class citytime.citytime.Range(time_a: Union[_ForwardRef('CityTime'), NoneType] = None, time_b: Union[_ForwardRef('CityTime'), datetime.timedelta, NoneType] = None)

Range extends the usefulness of CityTime objects by creating a time range between two times: a start time and an end time. This time range can then be compared to other time ranges, tested for overlapping time ranges, sliced into a new Range from two overlapping Ranges, etc.

A Range object made from two CityTime objects uses copies of the original CityTime objects, so that if those objects are changed in the future it won’t affect the Range object that was created. The same is true of Range objects made using a timedelta, the original CityTime object is copied.

A blank (unset) Range object can be created, but none of its methods can be used until it is set using either _create_range or _create_range_timedelta.

Parameters:
  • time_a – CityTime
  • time_b – CityTime or datetime.timedelta
Raises:

ValueError if the first parameter is not of type CityTime and the second parameter is not either CityTime or datetime.timedelta

after(other_range_obj: citytime.citytime.Range) → bool

Determines if one Range object is entirely greater than another Range object.

In other words, the start time of the Range object to be checked must be a later time than the end_time of the checking object.

before(other_range_obj: citytime.citytime.Range) → bool

Determines if one Range object is entirely less than another Range object.

In other words, the end time of the Range object to be checked must be an earlier time than the start_time of the checking object.

check_set() → bool

Indicates whether the Range object has been properly set or not.

Returns:
contains(citytime_or_range_object: Union[_ForwardRef('CityTime'), _ForwardRef('Range')]) → bool

Determines if the start and end times of one Range object fall entirely within the start and end times of another Range object.

copy() → citytime.citytime.Range

Create a copy of this Range instance.

Return type:Range
delta() → datetime.timedelta

Returns the difference (timedelta) between the end time and the start time.

Return type:datetime.timedelta
end_time() → citytime.citytime.CityTime

Return the later of the two Range times, no matter what order they are stored in.

Return type:CityTime
extend(added_delta: datetime.timedelta) → None

Extend the range by increasing end_time by the amount of time in the delta argument.

extend_prior(added_delta: datetime.timedelta) → None

Extend the range by decreasing start_time by the amount of time in the delta argument.

intersection(range_object: citytime.citytime.Range) → citytime.citytime.Range

Create a new range from the intersection of two ranges.

The start time and end time are taken from where the two ranges overlap.

overlap(range_object: citytime.citytime.Range) → datetime.timedelta

Determines how much of the given Range object overlaps with this Range object.

overlaps(range_object: citytime.citytime.Range) → bool

Determines whether the given Range object overlaps with this Range object.

shift(delta: datetime.timedelta) → None

Shift the time of the range.

Works by incrementing start_time and end_time equally by the increment given in delta.

start_time() → citytime.citytime.CityTime

Return the earlier of the two Range times, no matter what order they are stored in.

Return type:CityTime
timedelta_to_h_mm() → str
Return type:str

Indices and tables