xmu.types

Wrappers for data that can be garbled during read/write

class xmu.types.ExtendedDate(year, month, day)

Bases: tuple

day

Alias for field number 2

month

Alias for field number 1

year

Alias for field number 0

class xmu.types.EMuType(val: Any, fmt: str = '{}')

Bases: object

Container for data types that may be garbled during read/write

For example, transforming a year to a date using datetime.strptime() imposes a month and date, which could be bad news if that data is ever loaded back into the database. This class tracks the original string and format while coercing the string to a Python data type and providing support for basic operations.

Parameters:

• val (Any) – value to wrap

• fmt (str) – formatting string used to translate value back to a string

value

value coerced to the correct type from a string

Type:

Any

format

a formatting string

Type:

str

verbatim

the original, unparsed value

Type:

Any

property min_value: Any

Minimum value needed to express the original string

property max_value: Any

Maximum value needed to express the original string

property comp: Any

Value to use for comparisons

property min_comp: Any

Minimum value to use for comparisons

property max_comp: Any

Maximum value to use for comparisons

emu_str() → str

Returns a string representation suitable for EMu

coerce(other: Any) → EMuType

Coerces another object to the current class

Parameters:

other (Any) – an object to convert to this class

Returns:

other as EMuType

Return type:

EMuType

is_range() → bool

Checks if class represents a range

class xmu.types.EMuFloat(val: str | float, fmt: str = None)

Bases: EMuType

Wraps floats read from strings to preserve precision

Parameters:

• val (str | float) – float as a string or float

• fmt (str) – formatting string used to convert the float back to a string. Computed for strings but must be included if val is a float.

value

float parsed from string

Type:

float

format

formatting string used to convert the float back to a string

Type:

str

verbatim

the original, unparsed value

Type:

Any

property dec_places: int

Number of decimal places from the formatting string

round(dec_places: int) → EMuFloat

Rounds the float to the given number of decimal places

Parameters:

dec_places (int) – the number of decimal places

Returns:

the rounded value

Return type:

EMuFloat

class xmu.types.EMuCoord(val: str | float, fmt: str = None)

Bases: EMuFloat

Wraps coordinates read from strings

value

coordinate as a string or float

Type:

str | float

format

formatting string used to convert the float back to a string

Type:

str

degrees

degrees parsed from original

Type:

EMuFloat

minutes

minutes parsed from original, if any

Type:

EMuFloat

seconds

seconds parsed from original, if any

Type:

EMuFloat

verbatim

the original, unparsed value

Type:

Any

pos = ''

pattern for hemisphere for positive coordinates

Type:

str

neg = ''

pattern for hemisphere for negative coordinates

Type:

str

bounds = (0, 0)

range of allowable values

Type:

tuple of int

deg_dist_m = 110567

width of one degree lat (anywhere) or lon (at the equator)

Type:

float

property hemisphere: str

Gets the hemisphere in which a coordinate is located

property kind: str

Gets kind of verbatim coordinate string

to_dms(unc_m: int = None) → str

Expresses coordinate as degrees-minutes-seconds

Parameters:

unc_m (int) – uncerainty in meters

Returns:

coordinate as degrees-minutes-seconds

Return type:

str

to_dec(unc_m: int = None) → str

Expresses coordinate as a decimal

Parameters:

unc_m (int) – uncerainty in meters

Returns:

coordinate as decimal

Return type:

str

coord_uncertainty_m() → int

Estimates coordinate uncertainty in meters based on distance at equator

Returns:

uncertainty in meters, rounded to an exponent of 10

Return type:

int

class xmu.types.EMuLatitude(val: str | float, fmt: str = None)

Bases: EMuCoord

Wraps latitudes read from strings

pos = 'N(orth)?'

pattern for hemisphere for positive coordinates

Type:

str

neg = 'S(outh)?'

pattern for hemisphere for negative coordinates

Type:

str

bounds = (-90, 90)

range of allowable values

Type:

tuple of int

class xmu.types.EMuLongitude(val: str | float, fmt: str = None)

Bases: EMuCoord

Wraps longitudes read from strings

pos = 'E(ast)?'

pattern for hemisphere for positive coordinates

Type:

str

neg = 'W(est)?'

pattern for hemisphere for negative coordinates

Type:

str

bounds = (-180, 180)

range of allowable values

Type:

tuple of int

class xmu.types.EMuDate(*val, fmt: str = None)

Bases: EMuType

Wraps dates read from strings to preserve meaning

For dates in the range supported by the native EMu datetime module, this class supports both comparisons and addition/subtraction using timedelta objects but not augmented assignment using += or -=. For dates outside this range, comparisons and operations are currently not possible.

Parameters:

• val (str or datetime.date) – date as a string or date object

• fmt (str) – formatting string used to convert the value back to a string. If omitted, the class will try to determine the correct format.

value

date parsed from string

Type:

datetime.date or ExtendedDate

format

date format string used to convert the date back to a string

Type:

str

verbatim

the original, unparsed value

Type:

Any

strftime(fmt: str = None) → str

Formats date as a string

Parameters:

fmt (str) – date format string

Returns:

date as string

Return type:

str

to_datetime(tm: time) → datetime

Combines date and time into a single datetime

Parameters:

tm (datetime.time) – time to use with date

Returns:

combined datetime

Return type:

datetime.datetime

emu_str() → str

Returns a string representation of the date suitable for EMu

property min_value: date | ExtendedDate

Minimum date needed to express the original string

For example, the first day of the month for a date that specifies only a month and year or the first day of the year for a year.

property max_value: date | ExtendedDate

Maximum date needed to express the original string

For example, the last day of the month for a date that specifies only a month and year or the last day of the year for a year.

property comp: tuple[int, int, int]

Value to use for comparisons

property min_comp: tuple[int, int, int]

Minimum value to use for comparisons

property max_comp: tuple[int, int, int]

Maximum value to use for comparisons

property year: int

Year of the parsed date

property month: int

Month of the parsed date

property day: int

Day of the parsed date

date() → date

Returns the datetime.date corresponding to this object

Included to allow instances of this class to play well with functions that accept dates using both the datetime.date and datetime.datetime classes; instances of datetime.datetime include a date method that allows them to be easily converted to dates, for example, for comparisons.

Returns:

the date corresponding to this object

Return type:

datetime.date

static strptime(val: str, fmt: str) → date | ExtendedDate

Formats a string as a date

Parameters:

• val (str) – date string

• fmt (str) – date format string

Returns:

date as an object. If year is out-of-range for the native date class, returns an ExtendedDate tuple instead.

Return type:

datetime.date or ExtendedDate

class xmu.types.EMuTime(val: str | datetime.time, fmt: str = None)

Bases: EMuType

strftime(fmt: str = None) → str

Formats time as a string

Parameters:

fmt (str) – time format string

Returns:

time as string

Return type:

str

to_datetime(dt: date) → datetime

Combines date and time into a single datetime

Parameters:

dt (datetime.date) – date to use with time

Returns:

combined datetime

Return type:

datetime.datetime

property hour: int

Hour of the parsed time

property minute: int

Minute of the parsed time

property second: int

Second of the parsed time

property microsecond: int

Microsecond of the parsed time

property tzinfo: str

Time zone info for the parsed time