:py:mod:`core.bones.date` ========================= .. py:module:: core.bones.date Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: core.bones.date.DateBone .. py:class:: DateBone(*, creationMagic = False, date = True, localize = None, naive = False, time = True, updateMagic = False, **kwargs) Bases: :py:obj:`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. :param bool creationMagic: Use the current time as value when creating an entity; ignoring this bone if the entity gets updated. :param bool updateMagic: Use the current time whenever this entity is saved. :param bool date: If True, the bone will contain date information. :param time: If True, the bone will contain time information. :param localize: 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. Initializes a new DateBone. :param creationMagic: Use the current time as value when creating an entity; ignoring this bone if the entity gets updated. :param updateMagic: Use the current time whenever this entity is saved. :param date: Should this bone contain a date-information? :param time: Should this bone contain time information? :param localize: Assume users timezone for in and output? Only valid if this bone contains date and time-information! Per default, UTC time is used. :param naive: Use naive datetime for this bone, the default is aware. .. py:attribute:: type :value: 'date' .. py:method:: 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. :param bone_name: Our name in the skeleton :param client_data: *User-supplied* request-data, has to be of valid format :returns: tuple[datetime or None, [Errors] or None] .. py:method:: 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. :param datetime value: 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. :rtype: str or None .. py:method:: 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. :rtype: pytz timezone object .. py:method:: 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. :param datetime value: The input datetime value to be serialized. :param SkeletonInstance skel: The instance of the skeleton that contains this bone. :param str name: The name of the bone in the skeleton. :param bool parentIndexed: A boolean indicating if the parent bone is indexed. :returns: The serialized datetime value with unwanted parts removed and timezone-aware. :rtype: datetime .. py:method:: 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. :param datetime value: 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. :rtype: datetime or None .. py:method:: 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. :param str name: The name of the dateBone in the skeleton. :param SkeletonInstance skel: The skeleton instance containing the dateBone. :param db.Query dbFilter: The datastore query to which the filter will be applied. :param Dict rawFilter: The raw filter dictionary containing the filter values. :param Optional[str] prefix: An optional prefix to use for the filter key, defaults to None. :returns: The datastore query with the constructed filter applied. :rtype: db.Query .. py:method:: 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. :param dict valuesCache: The cache of values to be stored in the datastore. :param str name: The name of the dateBone in the skeleton. :param bool isAdd: A flag indicating whether the operation is adding a new entry (True) or updating an existing one (False). .. py:method:: structure() Describes the bone and its settings as an JSON-serializable dict. This function has to be implemented for subsequent, specialized bone types.