Welcome to CityTime’s documentation! — CityTime 1.0.0 documentation

# 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

- Index
- Module Index
- Search Page