Package: tsx
tsxTimeStamp eXtensions for PythonWhy tsx?tsxwas created as a response to the known Python datetime standard library flaw that violates ISO 8601. (Example)It properly handles the Daylight Saving Time (summer time), and provides functionality for creating, manipulating, and formatting timestamps in various formatsand precisions.Under the hood, it uses external dateparser library that's fully compatible with ISO 8601, and it simplifies working with date & time stamps.Installationpip pinstall tsxUsage:The library is pretty simple, its central class isTS, which inhertis Python builtinfloat,so every timestamp in fact is a float representing number of seconds since Epoch.TheTSMsecis the sameTSwith only difference that it's constructor by default expects msec precision, i.e. numberof msecs since epoch,but internally it will store the same float as number of seconds since Epoch.TS(ts:Union[int,float,str],prec:Literal["s","ms"]="s")`TSMsec(ts:Union[int,float,str],prec:Literal["s","ms"]="ms")prec- is precision of thetsargument.Ifprec=="s"- thetsargument will be interpreted as nr of seconds since epoch,Ifprec=="ms"- thetsargument will be interpreted as nr of milliseconds since epochExample:ts=TS(ts="1519855200.123856",prec="s")ts==1519855200.123856ts.as_iso=='2018-02-28T22:00:00.123856Z'ts.as_iso_tz(pytz.timezone("Europe/Bucharest"))=='2018-03-01T00:00:00.123856+02:00'TS("2018-02-28T22:00:00.123Z")TS("2018-02-28T22:00:00.123")TS("2018-02-28T22:00:00.123+00:00")ts=TS.now()ts.as_sec==1234567890.123ts.as_ms==1234567890123ts.as_file_date=='20090213'ts.as_file_ts=='20090213-233130'ClassesTSThe TS class, a subclass of float, represents Unix timestamps in seconds. It includes additional methods for timestamp manipulation and formatting.Key Methods and Propertiesnow_dt(): Returns the current datetime in UTC.now_ms(), now_us, now_ns: Returns the current timestamp in various precisions.now(): Returns the current TS instance.from_iso(): Parses an ISO string to a TS instance.timestamp(): Returns the timestamp as a TS instance.as_iso(),as_iso_date(),as_iso_date_basic(),as_iso_tz(),as_iso_basic(): Various ISO format representations.as_file_ts()andas_file_date(): File-friendly timestamp formats.as_sec(),as_ms(),to_sec(): Conversions to different precisions with deprecation notices.floor()andceil(): Methods for flooring and ceiling the timestamp.weekday()andisoweekday(): Methods to get the day of the week.Arithmetic Operations: Overloaded methods for arithmetic.now_dtDescription: Returns the current datetime in UTC.Example:current_dt=TS.now_dt()current_dt==datetime.datetime(2021,10,15,12,0,0,123456,tzinfo=datetime.timezone.utc)nowDescription: Returns the current timestamp in seconds.Example:current_ts=TS.now()current_ts==TS(1634294400.123456)==1634294400.123456now_msDescription: Returns the current timestamp in milliseconds.Example:current_ts=TS.now_ms()current_ts==iTSms(1634294400123)==1634294400123now_usDescription: Returns the current timestamp in microseconds.Example:current_ts=TS.now_us()current_ts==iTSus(1634294400123456)==1634294400123456now_nsDescription: Returns the current timestamp in nanoseconds.Example:current_ts=TS.now_ns()current_ts==iTSn(s1634294400123456789)==1634294400123456789from_isoDescription: Parses an ISO string to a TS instance.Example:ts=TS.from_iso("2021-10-15T12:00:00.123456Z")ts==TS(1634294400.123456)==1634294400.123456timestampDescription: Returns the timestamp as a TS instance.Example:ts=TS.timestamp(1634294400.123456)ts==TS(1634294400.123456)==1634294400.123456as_isoDescription: Returns the timestamp as an ISO string.Example:ts=TS(1634294400.123456)ts.as_iso=='2021-10-15T12:00:00.123456Z'as_iso_dateDescription: Returns the timestamp as an ISO date string.Example:ts=TS(1634294400.123456)ts.as_iso_date=='2021-10-15'as_iso_date_basicDescription: Returns the timestamp as an ISO date string in basic format.Example:ts=TS(1634294400.123456)ts.as_iso_date_basic=='20211015'as_iso_tzDescription: Returns the timestamp as an ISO string with timezone.Parameters:tz: str|tzinfo: The timezone to use.Example:ts=TS(1634294400.123456)ts.as_iso_tz(pytz.timezone("Europe/Bucharest"))=='2021-10-15T14:00:00.123456+02:00'as_iso_basicDescription: Returns the timestamp as an ISO string in basic format.Example:ts=TS(1634294400.123456)ts.as_iso_basic=='20211015T120000.123456Z'as_file_tsDescription: Returns the timestamp as a file-friendly timestamp string.Example:ts=TS(1634294400.123456)ts.as_file_ts=='20211015-120000'as_file_dateDescription: Returns the timestamp as a file-friendly date string.Example:ts=TS(1634294400.123456)ts.as_file_date=='20211015'as_secDescription: Returns the timestamp as a TS instance in seconds.Example:ts=TS(1634294400.123456)ts.as_sec==TS(1634294400.0)==1634294400.0as_msDescription: Returns the timestamp as a TS instance in milliseconds.Example:ts=TS(1634294400.123456)ts.as_ms==iTSms(1634294400123)==1634294400123to_secDescription: Returns the timestamp as a TS instance in seconds.Example:ts=TS(1634294400.123456)ts.to_sec==TS(1634294400.0)==1634294400.0floorDescription: Floors the timestamp to the nearest second.Parameters:unit: int|float: the unit to ceil which should be of the same precision as the timestampExample:ts=TS(1634294413.123456)ts.floor(100)==TS(1634294400.0)==1634294400.0ts.floor(0.025)==TS(1634294413.1)==1634294400.1ceilDescription: Ceils the timestamp to the nearest second.Parameters:unit: int|float: the unit to ceil which should be of the same precision as the timestampExample:ts=TS(1634294413.123456)ts.ceil(100)==TS(1634294500.0)==1634294500.0ts.ceil(0.025)==TS(1634294413.125)==1634294500.125weekdayDescription: Return the day of the week as an integer, where Monday is 0 and Sunday is 6. See also isoweekday().Parameters:utc: bool = True: Whether to use UTC or local time.Example:ts=TS(1634294400.123456)ts.weekday()==4isoweekdayDescription: Return the day of the week as an integer, where Monday is 1 and Sunday is 7. See also weekday().Parameters:utc: bool = True: Whether to use UTC or local time.Example:ts=TS(1634294400.123456)ts.isoweekday()==5Arithmetic OperationsDescription: Overloaded methods for arithmetic.Parameters:other: Union[TS, int, float]: The other timestamp to use.Example:ts=TS(1634294400.123456)ts+100==TS(1634294500.123456)==1634294500.123456ts-100==TS(1634294300.123456)==1634294300.123456ts*100==TS(163429440012.3456)==163429440012.3456ts/100==TS(16342944.00123456)==16342944.00123456ts//100==TS(16342944.0)==16342944.0ts%100==TS(1634294400.123456)==1634294400.123456ts**100==TS(1634294400.123456)==1634294400.123456TSMsecThe TSMsec class, a subclass of float, and it's used as a factory class to instantiate TS from milliseconds precision.After instantiation, the TSMsec instance is identical to TS instance, and it includes all the same methods and properties.iTSThe iTS class, a subclass of int, represents Unix timestamps in seconds. It includes additional methods for timestamp manipulation and formatting.It inherits fromBaseTSandintclasses, so it exposes all the methodsTShas, as well as it supports all the arithmetic operationsintsupports.It's identical toTSclass, but all the methods that returnTSwill returniTSinstead, excepting the timestamp(), which returnsTS.Key Methods and PropertiesThe same asTSclass, but all the methods that returnTSwill returniTSinstead.iTSmsThe iTSms class, a subclass of int, represents Unix timestamps in milliseconds. It includes additional methods for timestamp manipulation and formatting.It inherits fromBaseTSandintclasses, so it exposes all the methodsTShas, as well as it supports all the arithmetic operationsintsupports.It's identical toTSMsecclass, but all the methods that returnTSwill returniTSmsinstead, excepting the timestamp(), which returnsTS.iTSusThe iTSus class, a subclass of int, represents Unix timestamps in microseconds. It includes additional methods for timestamp manipulation and formatting.It inherits fromBaseTSandintclasses, so it exposes all the methodsTShas, as well as it supports all the arithmetic operationsintsupports.It's identical toTSclass, but all the methods that are expected to returnTSwill returniTSusinstead, excepting the timestamp(), which returnsTS.iTSnsThe iTSns class, a subclass of int, represents Unix timestamps in nanoseconds. It includes additional methods for timestamp manipulation and formatting.It inherits fromBaseTSandintclasses, so it exposes all the methodsTShas, as well as it supports all the arithmetic operationsintsupports.It's identical toTSclass, but all the methods that are expected to returnTSwill returniTSnsinstead, excepting the timestamp(), which returnsTS.Note: TheiTSnsclass is only available for Python >= 3.8, and it support ns level now precision by usingtime.time_ns()instead oftime.time().Changelog0.1.16Fixed bug in iTS().subwhen performed operations with floats or other TS instances0.1.15TS.as_dt() now is able to properly handle the big dates (year > 2038), which are causing overflow exceptions in Python datetime.fromtimestamp() stdlib functionsAdded instantiation from Python datetime and date objects + proper handling of big dates (year > 2038)0.1.14TS.now() offers nanosecond precision instead of millisecond0.1.13TypeHint update:TS.as_ms()now returnsiTSmsinstead of simpleintAdded more documentation to README.md0.1.12Added dTS object0.1.11fixed the pickling/unpickling of TSMsec objects by instantiating the TSMsec as actually an instance of TS0.1.10upgrade dependency ciso8601 2.3.0 -> 2.3.10.1.9Fixed bug in TS.suband TS.addintroduced in 0.1.70.1.8Added TS.to_sec as temporary alias for TS.as_sec0.1.7Added iTS, iTSms, iTSus, iTSns classes.deprecated TS.as_msec and TS.as_secNo breaking changes yet0.1.6Fixed bug in TSMsec from TSMsec initialization0.1.5Fixed bug in parsing with date_util the Truncated formats with no TZ info0.1.4Exporting FIRST_MONDAY_TS, DAY_SEC, DAY_MSEC, WEEK_SEC into tsx public space0.1.3Fixed bug in TSMsec(<ISO_STRING>)0.1.2Added as_dt() and as_local_dt() methods0.1.1fixed bug in converting from numpy numbers0.1.0Added theutc:bool=Trueparameter to TS constructor, which if set toTrue(by default) will force the timestamp tobe interpreted as UTC, thus `TS('2018-02-28T22:00:00') will be interpreted as UTC, and not as local time, even if itdoesn't have explicit TZ info.Improved speed of TS.from_iso(). For Python <3.11 it usesciso8601which isthe fastest ISO 8601 parser, and for Python >= 3.11 it uses the builtindatetime.fromisoformat().some minor parsing speed improvementsadded public time utility variablesFIRST_MONDAY_TS,DAY_SEC,DAY_MSEC,WEEK_SEC0.0.9str(ts) now returns ts.as_iso0.0.8added weekday() + isoweekday()0.0.7added floor() and ceil() methods0.0.6added TS.as_iso_date_basic and as_iso_basic0.0.5added TS.from_iso()0.0.4added return typehint to TS.now()0.0.3Lower the minimal typing-extensions version