core.bones.date

Module Contents

Classes

DateBone

DateBone is a bone that can handle date and/or time information. It can store date and time information
class core.bones.date.DateBone(*, creationMagic=False, date=True, localize=None, naive=False, time=True, updateMagic=False, **kwargs)

Bases: viur.core.bones.base.BaseBone

DateBone is a bone that can handle date and/or time information. It can store date and time information separately, as well as localize the time based on the user’s timezone.

Parameters:

  • creationMagic (bool) – Use the current time as value when creating an entity; ignoring this bone if the entity gets updated.

  • updateMagic (bool) – Use the current time whenever this entity is saved.

  • date (bool) – If True, the bone will contain date information.

  • time (bool) – If True, the bone will contain time information.

  • localize (bool) – If True, the user’s timezone is assumed for input and output. This is only valid if both ‘date’ and ‘time’ are set to True. By default, UTC time is used.

  • naive (bool) –

Initializes a new DateBone.

Parameters:

  • creationMagic (bool) – Use the current time as value when creating an entity; ignoring this bone if the entity gets updated.

  • updateMagic (bool) – Use the current time whenever this entity is saved.

  • date (bool) – Should this bone contain a date-information?

  • time (bool) – Should this bone contain time information?

  • localize (bool) – Assume users timezone for in and output? Only valid if this bone contains date and time-information! Per default, UTC time is used.

  • naive (bool) – Use naive datetime for this bone, the default is aware.

type = 'date'
singleValueFromClient(value, skel, bone_name, client_data)

Reads a value from the client. If the value is valid for this bone, it stores the value and returns None. Otherwise, the previous value is left unchanged, and an error message is returned. The value is assumed to be in the local time zone only if both self.date and self.time are set to True and self.localize is True.

Value is valid if, when converted into String, it complies following formats:

is digit (may include one ‘-’) and valid POSIX timestamp: converted from timestamp; assumes UTC timezone is digit (may include one ‘-’) and NOT valid POSIX timestamp and not date and time: interpreted as seconds after epoch ‘now’: current time ‘nowX’, where X converted into String is added as seconds to current time ‘%H:%M:%S’ if not date and time ‘%M:%S’ if not date and time ‘%S’ if not date and time ‘%Y-%m-%d %H:%M:%S’ (ISO date format) ‘%Y-%m-%d %H:%M’ (ISO date format) ‘%Y-%m-%d’ (ISO date format) ‘%m/%d/%Y %H:%M:%S’ (US date-format) ‘%m/%d/%Y %H:%M’ (US date-format) ‘%m/%d/%Y’ (US date-format) ‘%d.%m.%Y %H:%M:%S’ (EU date-format) ‘%d.%m.%Y %H:%M’ (EU date-format) ‘%d.%m.%Y’ (EU date-format)

The resulting year must be >= 1900.

Parameters:

  • bone_name – Our name in the skeleton

  • client_data – User-supplied request-data, has to be of valid format

Returns:

tuple[datetime or None, [Errors] or None]

isInvalid(value)

Validates the input value to ensure that the year is greater than or equal to 1900. If the year is less than 1900, it returns an error message. Otherwise, it calls the superclass’s isInvalid method to perform any additional validations.

This check is important because the strftime function, which is used to format dates in Python, will break if the year is less than 1900.

Parameters:

value (datetime) – The input value to be validated, expected to be a datetime object.

Returns:

An error message if the year is less than 1900, otherwise the result of calling the superclass’s isInvalid method.

Return type:

str or None

guessTimeZone()

Tries to guess the user’s time zone based on request headers. If the time zone cannot be guessed, it falls back to using the UTC time zone. The guessed time zone is then cached for future use during the current request.

Returns:

The guessed time zone for the user or a default time zone (UTC) if the time zone cannot be guessed.

Return type:

pytz timezone object

singleValueSerialize(value, skel, name, parentIndexed)

Prepares a single value for storage by removing any unwanted parts of the datetime object, such as microseconds or adjusting the date and time components depending on the configuration of the dateBone. The method also ensures that the datetime object is timezone aware.

Parameters:

  • value (datetime) – The input datetime value to be serialized.

  • skel (SkeletonInstance) – The instance of the skeleton that contains this bone.

  • name (str) – The name of the bone in the skeleton.

  • parentIndexed (bool) – A boolean indicating if the parent bone is indexed.

Returns:

The serialized datetime value with unwanted parts removed and timezone-aware.

Return type:

datetime

singleValueUnserialize(value)

Converts the serialized datetime value back to its original form. If the datetime object is timezone aware, it adjusts the timezone based on the configuration of the dateBone.

Parameters:

value (datetime) – The input serialized datetime value to be unserialized.

Returns:

The unserialized datetime value with the appropriate timezone applied or None if the input value is not a valid datetime object.

Return type:

datetime or None

buildDBFilter(name, skel, dbFilter, rawFilter, prefix=None)

Constructs a datastore filter for date and/or time values based on the given raw filter. It parses the raw filter and, if successful, applies it to the datastore query.

Parameters:

  • name (str) – The name of the dateBone in the skeleton.

  • skel (SkeletonInstance) – The skeleton instance containing the dateBone.

  • dbFilter (db.Query) – The datastore query to which the filter will be applied.

  • rawFilter (Dict) – The raw filter dictionary containing the filter values.

  • prefix (Optional[str]) – An optional prefix to use for the filter key, defaults to None.

Returns:

The datastore query with the constructed filter applied.

Return type:

db.Query

performMagic(valuesCache, name, isAdd)

Automatically sets the current date and/or time for a dateBone when a new entry is created or an existing entry is updated, depending on the configuration of creationMagic and updateMagic.

Parameters:

  • valuesCache (dict) – The cache of values to be stored in the datastore.

  • name (str) – The name of the dateBone in the skeleton.

  • isAdd (bool) – A flag indicating whether the operation is adding a new entry (True) or updating an existing one (False).

structure()

Describes the bone and its settings as an JSON-serializable dict. This function has to be implemented for subsequent, specialized bone types.

Return type:

dict