Transformations

Functions which can be applied to source fields, allowing extensibility

exception adtl.transformations.AdtlTransformationWarning

adtl.transformations.Percentage(value: float)

transform a decimal into a percentage

adtl.transformations.correctOldDate(date: str, epoch: float, format: str, return_datetime: bool = False)

Fixes dates so that they are the correct century for when the year is not fully specified. The time module converts 2 digit dates by mapping values 69-99 to 1969-1999, and values 0-68 are mapped to 2000-2068. This doesn’t work for e.g. birthdates here where they are frequently below the cutoff.

Switches the pivot point to that set by epoch so that epoch+ converts to 19xx.

Only use for birth dates to avoid unintentional conversion for recent dates.

Parameters:

• date – Date to convert

• epoch – Epoch as year

• format – strftime(3) format that date is in

• return_datetime – Whether to return date in a datetime.datetime format (when True), or a string (when False, default)

Returns:

Fixed date, return type depends on return_datetime

Return type:

str | datetime.datetime

adtl.transformations.durationDays(startdate: str, currentdate: str, format: str = '%Y-%m-%d') → int

Returns the number of days between two dates. Preferable to Y-M-D elapsed, as month length is ambiguous - can be anywhere between 28-31 days.

adtl.transformations.endDate(startdate: str, duration: str, format='%Y-%m-%d')

Returns the end date in ISO format, given the start date and the duration.

Parameters:

• startdate – Start date

• duration – Duration in days

• format – strftime(3) format that dates are in

Returns:

End date in the specified format

adtl.transformations.getFloat(value: str, set_decimal: str | None = None, separator: str | None = None)

Returns value transformed into a float.

Parameters:

• value – Value to be transformed to float

• set_decimal – optional, set if decimal separator is not a full stop or period (.)

• separator – optional, set to the character used for separating thousands (such as ,).

adtl.transformations.isNotNull(value: str | None) → bool

Returns whether value is not null or an empty string

adtl.transformations.makeDate(year: str, month: str, day: str) → str

Returns a date from components specified as year, month and day

adtl.transformations.makeDateTime(date: str, time_24hr: str, date_format: str, timezone: str) → datetime

Returns a combined date and time

Parameters:

• date – Date to be converted

• time_24hr – Time specified in HH:MM format

• date_format – Date format in strftime(3) format

• timezone – Timezone to use, specified in tzdata format

Returns:

A timezone aware datetime object

Return type:

datetime.datetime

adtl.transformations.makeDateTimeFromSeconds(date: str, time_seconds: int, date_format: str, timezone: str) → datetime

Returns a datetime from date and time specified in elapsed seconds since the beginning of the day

Parameters:

• date – Date to be converted

• time_seconds – Elapsed time in seconds within that day (0 - 86399)

• date_format – Date format in strftime(3) format

• timezone – Timezone to use, specified in tzdata format

Returns:

A timezone aware datetime object

Return type:

datetime.datetime

adtl.transformations.splitDate(date: str, option: Literal['year', 'month', 'day'], epoch: float, format: str = '%Y-%m-%d')

Splits a date into year, month, day

adtl.transformations.startDate(enddate: str, duration: str) → str

Returns the start date in ISO format, given the end date and the duration.

adtl.transformations.startMonth(duration: str | float, currentdate: list | str, epoch: float, dateformat: str = '%Y-%m-%d', duration_type: Literal['years', 'months', 'days'] = 'years', provide_month_day: bool | list = False)

Use to calculate month e.g. of birth from date (e.g. current date) and duration (e.g. age), parameter descriptions are same as adtl.transformations.startYear(), except this function returns the month component

adtl.transformations.startYear(duration: str | float, currentdate: list | str, epoch: float, dateformat: str = '%Y-%m-%d', duration_type: Literal['years', 'months', 'days'] = 'years', provide_month_day: bool | list = False) → int | float

Use to calculate year e.g. of birth from date (e.g. current date) and duration (e.g. age)

The date can be provided as a list of possible dates (if a hierarchy needs searching through)

Parameters:

• duration – Duration value

• currentdate – Date to offset duration from

• epoch – Epoch year to use for conversion of two digit years. Any dates after the epoch are converted to the last century

• dateformat – Date format that currentdate is in

• duration_type – One of ‘years’, ‘months’ or ‘days’

• provide_month_day – If currentdate is only year, and this is specified as a tuple of (month, day), uses these to construct the date

Returns:

Starting year, offset by duration

adtl.transformations.textIfNotNull(field: str, return_val: Any) → Any

Returns a default value if field is not null

adtl.transformations.wordSubstituteSet(value: str, *params) → list[str]

For a value that can have multiple words, use substitutions from params.

Parameters:

• value – String containing a list of words that should be substituted

• params –

  List of 2-tuples, in the form [(w1, s1), (w2, s2), … (w_n, s_n)] where w1 is replaced by s1, w2 is replaced by s2.

  Word matches are regular expressions, delimited by the  word boundary delimiter so can have arbitrary regular expressions to match. Any match of regex w_n will use substitute s_n. Case is ignored when matching.

Returns:

List of words after finding matches and substituting. Duplicate words are only represented once.

adtl.transformations.yearsElapsed(birthdate: str, currentdate: str, epoch: float, bd_format: str = '%Y-%m-%d', cd_format: str = '%Y-%m-%d')

Returns the number of years elapsed between two dates, useful for calculating ages

Parameters:

• birthdate – Start date of duration

• currentdate – End date of duration

• epoch – Epoch year after which dates will be converted to the last century. As an example, if epoch is 2022, then the date 1/1/23 will be converted to the January 1, 1923.

• bd_format – Date format for birthdate specified using strftime(3) conventions. Defaults to ISO format (“%Y-%m-%d”)

• cd_format – Date format for currentdate specified using strftime(3) conventions. Defaults to ISO format (“%Y-%m-%d”)

Returns:

Number of years elapsed or None if invalid dates were encountered

Return type:

int | None