Package: datetoken
This package allows you to store complex relative dates in string tokens.To define the initial/starting point in time(typically written asnow), to
work with dates in the past or in the future. Ideal to perform date
simulations.Time zone configuration. Additionally to the starting point in time, TZs
can be provided to as to somehow abstract the user away from localizingdatetimesobjects in their apps.As a disclaimer, if the custom datetime specified as the starting point
(now’s value) is tz-unaware or naive, it will be treated as an UTC one.
Defaultnow’s value also fallsback todatetime.datetime.utcnow, localized
to UTC.Now, if a time zone is specified, thenow’s value will be coerced to that
TZ prior to applying both snap and modifier expressions. This is handy
to quickly resolve tokens given any point in time (either naive or aware), a
time zone and the datetoken itself.MotivationHave you ever needed to make an application where dates needed to be
represented in a relative fashion, like background periodic
tasks, datetime range pickers… in a compact and stringified format? This
library enables you to persist these string tokens during the lifetime of a
process or even longer, since calculations are performed in the moment of
evaluation. Theses tokens are also useful when caching URLs as replacement
of timestamps, which would break caching given their mutability nature.Some common examples of relative tokens:Today:now/d,nowYesterday:now-d/d,now-d@dLast 24 hours:now-1d,now. Also writable as:now-24h,nowLast business week:now-w/bw,now-w@bwThis business week:now/bw,now@bwLast month:now-1M/M,now-1M@MLast year:now-1Y/Y,now-1Y@YLast month first business week:now-M/M+w/bw,now-M/M+w@bwAs you may have noticed, token follow a pattern:The wordnow. It means the point in the future timeline when
tokens are parsed to their datetime form.Optionally, modifiers to add and/or subtract the future value ofnowcan be used. Unsurprisingly, additions are set via+, while-mean subtractions. These modifiers can be chained as many times
as needed. E.g:now-1M+3d+2h. Along with the arithmetical sign
and the amount, the unit of time the amount refers to must be
specified. Currently, the supported units are:ssecondsmminuteshhoursddayswweeksMmonthsYyearsOptionally, there exist two extra modifiers to snap dates to the
start or the end of any given snapshot unit. Those are:/Snap the date to the start of the snapshot unit.@Snap the date to the end of the snapshot unit.Snapshot units are the same as arithmetical modifiers, plus the following
ones:bw, business weekmon, Mondaytue, Tuesdaywed, Wednesdaythu, Thursdayfri, Fridaysat, Saturdaysun, SundayWith this, we achieve a simple way to define canonical relative date ranges,
such asTodayorLast month. As an example of the later:String representation:now-1M/M,now-1M@MBeing today15 Jan 2018, the result range should be:2018-01-01
00:00:00 / 2018-01-31 23:59:59InstallingInstall and update via eitherpipenvorpippipenvinstalldatetokenorpipinstalldatetokenExamples and usageMost probably you will be dealing with simple presets such asyesterdayor thelast 24 hours.>>>fromdatetoken.utilsimporttoken_to_date>>>fromdatetimeimportdatetime>>>print(datetime.utcnow())2018-10-1814:08:47>>>token_to_date('now-d/d')# Start of yesterday2018-10-1700:00:00>>>token_to_date('now-d@d')# End of yesterday2018-10-1723:59:59For more details, refer toREADME.