walero-moon/worldtimepy

A Python wrapper for WorldtimeAPI with a searching functionality and some integration with datetime objects.

Worldtimepy

v0.1.1

Worldtime-py is a Python wrapper for WorldtimeAPI. It is able to search through the endpoints of the API to find the closest location if the exact one could not be found. It reduces the strain and the difficulty of getting the time for the location desired.

WorldtimeAPI is a JSON API for obtaining the current time in, and related data about, a timezone. It gives data such as the UTC offset, whether that timezone is in Daylight Savings Time (DST), UTC offset, etc.

Installing

This library can be installed by using pip install worldtimepy. Doing so will automatically install all requirements.

Requirements

This library requires you to have requests, unidecode, and countryinfo. All of those can be installed using pip.

Using the wrapper

Import the modules first

from worldtimepy import worldtime

from worldtimepy import timeinfo Use this only if you desire to handle the endpoints yourself

class worldtime.WorldTime()

This is the main class through which you should interact with the API.

.locations

Has all existing locations from WorldtimeAPI.

return list

.from_ip(ip: str='') -> TimeInfo optional argument: ip

Takes an IP and returns a corresponding TimeInfo object with timezone information for that IP. If no IP is provided, it will use the requesting IP.

return TimeInfo

.find_by_name(name: str) -> list

Takes a string and returns a list of strings for all locations that contain that name.

return list

.search(name: str) -> str

Takes a country name or a city name and tries to find it in the database. It returns a string that can be used by get_location().

Warning: This function iterates through different databases to try and locate the query. It may be slow.

return string

.get_location(location: str) -> object

Takes a proper location taken from search or find_by_name and returns a TimeInfo object.

return TimeInfo

.refresh()

Gathers new data for self.locations.

No return

class timeinfo.TimeInfo(to_get=0, ip: bool=False)

This class takes a location found through one of the other methods and makes an object with information for that timezone. You can use any location from worldtime.WorldTime().locations here.

Alternatively, if you set ip to True, you may provide an IPv4 address on to_get to get time information for that IP. If ip is set to True and nothing is given to to_get, the machine's IP will be used.

Printing or turning this object into a string returns a prettier string containing time information.

2021-06-11 00:14:14.378300 UTC-0700

.result

Full json pulled from the API.

return dict

.week_day

Returns current day of the week.

return int

.year_day

Returns current day of the year.

return int

.week_number

Returns current number of the week of the year.

return int

.datetime

Returns an aware .

return datetime

.datetime_str

Returns a string version of a datetime object.

return str

.abbreviation

Returns a string representing the abbreviated format of the timezone. E.g. 'PST'

return str

.is_dst

Returns whether timezone is in daylight savings time.

return bool

.dst_offset

.dst_from

.dst_until

.unixtime

Returns a unix like time integer.

return int

.utc

Returns the UTC time..

return str

.utc_offset

.raw_offset