Package: datetime-formatter
datetime_formatterprovides aDSL (domain-specific language)for formattingdatetimesinline to strings.datetime_formatteris also capable of translating
thedatetimeby most intervals, including some that are not supported bytimedeltalike “business_day” (skip weekends and holidays).For example (seeAvailable Output Formatsfor full details)Usedatetime_formatterto format dates effectively, including translations
and holiday/weekend management using easy-to-remember shortcuts
instead of esotericstrftimeshortcuts, i.e.
having to memorize that%mis month, while%M"is minute.
For example, useYMDto refer to aYYYYMMDDformatting of a date.datetime_formatteris especially useful for ingestion of configuration files
where complicated date logic either has to be handled outside of the file itself,
making understanding logic harder, or by making all configuration actual
Python code – which again makes reading harder and interoperability with
non-Python much harder or impossible.datetime_formatterallows all of this
formatting to be done inline, making configuration files easier to comprehend.InstallThe latest stable version can always be installed or updated via pip:$pipinstall--updatedatetime_formatterDocumentationThe documentation is hosted onRead the Docs.Quick Startdatetime_formatteris intended to be used in one of two ways.  You can either
use the providedDateTimeFormatterclass which inherits fromstring.Formatter, but overrides.formatto provide unique functionality.fromdatetime_formatterimportDateTimeFormatterdtf=DateTimeFormatter("2005-03-01 09:30:00")dtf.format("Format this way %ISODATETIME% or that way %YYYY%-%MM%-%DD% %HH%:%MM:%SS%")dtf.format("Or use translaters to change the datetime: %YYYYMMDD-P1Y%")Or use the provided convenience functiondtformat(aliased todtfmtas well):fromdatetimeimportdatetimefromdatetime_formatterimportdtfmtdtfmt(20050301,"YYYYMMDD")=="20050301"# Truedtfmt("2005-03-01","MMDDYY")=="030105"# Truedtfmt("2005-03-01 08:30:00","HHMMSS")=="083000"# TrueYou can use thedtfmtshortcut, intended for use withinf-strings, or
you can instantiate aDateTimeFormatterobject and use its.formatmethod
(or take advantage of the fact that__call__forwards to.format)dtf=DateTimeFormatter(datetime(2005,3,1))dtf.format("%YYYYMMDD%")=="20050301"You can also translate dates and/or times using inline translation syntax, e.g.:dtfmt(20050301,"YMD-M1D")=="20050228"dtfmt(20050301,"YMD-M1Y")=="20040301"dtfmt("20050301 08:30:00","DATETIME-P1H")=="2005-03-01 09:30:00"You can also convert to a new timezone on the fly, but only if you
yourdatetimeobject is not timezone-naive.fromdateutilimporttzutc=tz.gettz("UTC")est=tz.gettz("EST")dt=datetime(2005,3,1,8,30,0,0,est)dtfmt(dt,"ISODT",output_tz=utc)=="2005-03-01T13:30:00+00:00"The full list of supported output shortcuts and translations are provided
below.  You can also use theholidaysmodule with translations to skip
well-known holidays, much like you can skip weekends using thebusiness_daytranslation size.importholidaysdtfmt(20061229,"DATE-P2B",holidays=holidays.US())=="2007-01-03"Please see thedocumentationfor additional examples and detailed
information.Available Output FormatsThese shortcuts are used either as thefmtstrargument todtfmtor
within a string passed toDateTimeFormatter.format- in the latter case,
the fields to be replaced must be surrounded by%, e.g.%YYYYMMDD%.FormatShortcutdatetimeequivalent (strftimeor function)Output format exampleDATE%Y-%m-%d2005-03-01DATETIME%Y-%m-%d%H:%M:%S2005-03-01 13:30:00USDATE%x03/01/05USDATETIME%x %X03/01/05 13:30:00TIME%X13:30:00YEAR%Y2005YMD%Y%m%d20050301YYYYMM%Y%m200503MMYYYY%m%Y032005YYMM%y%m0503MMYY%m%y0305YYYYMMDD%Y%m%d20050301MMDDYY%m%d%y030105MMDDYYYY%m%d%Y03012005ISODATE%Y-%m-%d2005-03-01ISODATETIMEdatetime.isoformat2005-03-01T13:30:00.200Z-05:00MONTH%m03MON%m03MONTHABV%bMarMONTHNAME%BMarchDAYABV%aTuesDAYNAME%ATuesdayDAYNUM%w2DAYYEAR%j060TZOFF%z-0500TZNAME%ZESTWEEKNUM%W09DAY%d01DD%d01MM%m03YY%y05YYYY%Y2005LOCALE_DT%cTue Mar  1 13:30:00 2005HHMMSS%H:%M:%S13:30:00HHMMSSZZ%H:%M:%S.%f13:30:00.200000AMPM%pPMHH%H13HH12%I01HOUR%H13MIN%M30SECOND%S00SS%S00MICROSECOND%f200000ZZ%f200000Available TranslationsTranslations are made up of three parts.  Thedirection(MorP)
determines whether to go forward/backward (plus/minus).  Theunit(see table below forunit-types) determines how far each step takes us
foward or backward.  Finally thesizeis a non-negative integer that tells
us how far to move in the providedunits.Part namePossible ValuesDescriptionDirection["M","P","m","p"]M = minus, P = plusNumberInteger >= 0The number of units to translate the date bySize/Unit["Y","m","D","W","H","M","S","Z","B"]SizeMeaningYYear(s)mMonth(s)DDay(s)WWeek(s)HHour(s)MMinute(s)SSecond(s)ZMicrosecond(s)BBusiness day(s)FBusiness week(s)PBusiness month(s)KBusiness year(s)TSTimestamp (UTC seconds since epoch)You can string together any combination of these three translation parts, e.g.:dtfmt(20050301,"YMD-M1B")# 20050301 minus 2 business days (20050225)dtfmt(20050301,"YMD-P1Y")# 20050301 plus 1 year (20060301)dtfmt(20050301,"DATETIME-P1H")# 20050301 00:00:00 plus 1 hour: (2005-03-01 01:00:00)Beta VersionThe latest development (beta) version can be installed directly from GitHub:$pipinstall--upgradehttps://github.com/nadime/datetime_formatter/tarball/betaAll new features are always first pushed to beta branch, then released on
master branch upon official version upgrades.ContributionsIssuesandpull requestsare always welcome.  Please seeherefor more information.LicenseCode and documentation are available according to the MIT License
(seeLICENSE).