@backtomyfuture/exchange-cli-darwin-x64 0.1.10

package/bin/_internal/exchangelib/fields.py

@@ -0,0 +1,1842 @@
+import abc
+import datetime
+import logging
+import warnings
+from contextlib import suppress
+from decimal import Decimal, InvalidOperation
+from importlib import import_module
+
+from .errors import InvalidTypeError
+from .ewsdatetime import UTC, EWSDate, EWSDateTime, EWSTimeZone, NaiveDateTimeNotAllowed, UnknownTimeZone
+from .util import (
+    TNS,
+    create_element,
+    get_xml_attr,
+    get_xml_attrs,
+    is_iterable,
+    set_xml_value,
+    value_to_xml_text,
+    xml_text_to_value,
+)
+from .version import EXCHANGE_2013, SupportedVersionInstanceMixIn
+
+log = logging.getLogger(__name__)
+
+
+# DayOfWeekIndex enum. See
+# https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/dayofweekindex
+FIRST = "First"
+SECOND = "Second"
+THIRD = "Third"
+FOURTH = "Fourth"
+LAST = "Last"
+WEEK_NUMBERS = (FIRST, SECOND, THIRD, FOURTH, LAST)
+
+# Month enum
+JANUARY = "January"
+FEBRUARY = "February"
+MARCH = "March"
+APRIL = "April"
+MAY = "May"
+JUNE = "June"
+JULY = "July"
+AUGUST = "August"
+SEPTEMBER = "September"
+OCTOBER = "October"
+NOVEMBER = "November"
+DECEMBER = "December"
+MONTHS = (JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY, AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER)
+
+# Weekday enum
+MONDAY = "Monday"
+TUESDAY = "Tuesday"
+WEDNESDAY = "Wednesday"
+THURSDAY = "Thursday"
+FRIDAY = "Friday"
+SATURDAY = "Saturday"
+SUNDAY = "Sunday"
+WEEKDAY_NAMES = (MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY)
+
+# Used for weekday recurrences except weekly recurrences. E.g. for "First WeekendDay in March"
+DAY = "Day"
+WEEK_DAY = "Weekday"  # Non-weekend day
+WEEKEND_DAY = "WeekendDay"
+EXTRA_WEEKDAY_OPTIONS = (DAY, WEEK_DAY, WEEKEND_DAY)
+
+# DaysOfWeek enum: See
+# https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/daysofweek-daysofweektype
+WEEKDAYS = WEEKDAY_NAMES + EXTRA_WEEKDAY_OPTIONS
+
+
+class InvalidField(ValueError):
+    """Used when a field name does not match any defined fields."""
+
+
+class InvalidFieldForVersion(ValueError):
+    """Used when a field is not supported on the given Exchange version."""
+
+
+class InvalidChoiceForVersion(ValueError):
+    """Used when a value is not valid for an enum-type field."""
+
+
+def split_field_path(field_path):
+    """Split a string path into its field, label and subfield parts.
+
+    :param field_path:
+
+    :return Examples:
+      'start' -> ('start', None, None)
+      'phone_numbers__PrimaryPhone' -> ('phone_numbers', 'PrimaryPhone', None)
+      'physical_addresses__Home__street' -> ('physical_addresses', 'Home', 'street')
+    """
+    if not isinstance(field_path, str):
+        raise InvalidTypeError("field_path", field_path, str)
+    search_parts = field_path.split("__")
+    field = search_parts[0]
+    try:
+        label = search_parts[1]
+    except IndexError:
+        label = None
+    try:
+        subfield = search_parts[2]
+    except IndexError:
+        subfield = None
+    return field, label, subfield
+
+
+def resolve_field_path(field_path, folder, strict=True):
+    """Take the name of a field, or '__'-delimited path to a subfield, and return the corresponding Field object,
+    label and SubField object.
+    """
+    from .indexed_properties import MultiFieldIndexedElement, SingleFieldIndexedElement
+
+    fieldname, label, subfield_name = split_field_path(field_path)
+    field = folder.get_item_field_by_fieldname(fieldname)
+    subfield = None
+    if isinstance(field, IndexedField):
+        if strict and not label:
+            raise ValueError(
+                f"IndexedField path {field_path!r} must specify label, e.g. "
+                f"'{fieldname}__{field.value_cls.get_field_by_fieldname('label').default}'"
+            )
+        valid_labels = field.value_cls.get_field_by_fieldname("label").supported_choices(version=folder.account.version)
+        if label and label not in valid_labels:
+            raise ValueError(
+                f"Label {label!r} on IndexedField path {field_path!r} must be one of {sorted(valid_labels)}"
+            )
+        if issubclass(field.value_cls, MultiFieldIndexedElement):
+            if strict and not subfield_name:
+                raise ValueError(
+                    f"IndexedField path {field_path!r} must specify subfield, e.g. "
+                    f"'{fieldname}__{label}__{field.value_cls.FIELDS[1].name}'"
+                )
+
+            if subfield_name:
+                try:
+                    subfield = field.value_cls.get_field_by_fieldname(subfield_name)
+                except ValueError:
+                    field_names = ", ".join(
+                        f.name for f in field.value_cls.supported_fields(version=folder.account.version)
+                    )
+                    raise ValueError(
+                        f"Subfield {subfield_name!r} on IndexedField path {field_path!r} "
+                        f"must be one of {sorted(field_names)}"
+                    )
+        else:
+            if not issubclass(field.value_cls, SingleFieldIndexedElement):
+                raise InvalidTypeError("field.value_cls", field.value_cls, SingleFieldIndexedElement)
+            if subfield_name:
+                raise ValueError(
+                    f"IndexedField path {field_path!r} must not specify subfield, e.g. just {fieldname}__{label}'"
+                )
+            subfield = field.value_cls.value_field(version=folder.account.version)
+    else:
+        if label or subfield_name:
+            raise ValueError(f"Field path {field_path!r} must not specify label or subfield, e.g. just {fieldname!r}")
+    return field, label, subfield
+
+
+class FieldPath:
+    """Holds values needed to point to a single field. For indexed properties, we allow setting either field,
+    field and label, or field, label and subfield. This allows pointing to either the full indexed property set, a
+    property with a specific label, or a particular subfield field on that property.
+    """
+
+    def __init__(self, field, label=None, subfield=None):
+        """
+
+        :param field: A FieldURIField or ExtendedPropertyField instance
+        :param label: a str
+        :param subfield: A SubField instance
+        """
+        # 'label' and 'subfield' are only used for IndexedField fields
+        self.field = field
+        self.label = label
+        self.subfield = subfield
+
+    @classmethod
+    def from_string(cls, field_path, folder, strict=False):
+        field, label, subfield = resolve_field_path(field_path, folder=folder, strict=strict)
+        return cls(field=field, label=label, subfield=subfield)
+
+    def get_value(self, item):
+        # For indexed properties, get either the full property set, the property with matching label, or a particular
+        # subfield.
+        if self.label:
+            for sub_item in getattr(item, self.field.name):
+                if sub_item.label == self.label:
+                    if self.subfield:
+                        return getattr(sub_item, self.subfield.name)
+                    return sub_item
+            return None  # No item with this label
+        return getattr(item, self.field.name)
+
+    def get_sort_value(self, item):
+        # For fields that allow values of different types, we need to return a value that is
+        val = self.get_value(item)
+        if isinstance(self.field, DateOrDateTimeField) and isinstance(val, EWSDate):
+            return item.date_to_datetime(field_name=self.field.name)
+        return val
+
+    def to_xml(self):
+        if isinstance(self.field, IndexedField):
+            if not self.label or not self.subfield:
+                raise ValueError(f"Field path for indexed field {self.field.name!r} is missing label and/or subfield")
+            return self.subfield.field_uri_xml(field_uri=self.field.field_uri, label=self.label)
+        return self.field.field_uri_xml()
+
+    def expand(self, version):
+        # If this path does not point to a specific subfield on an indexed property, return all the possible path
+        # combinations for this field path.
+        if isinstance(self.field, IndexedField):
+            labels = (
+                [self.label]
+                if self.label
+                else self.field.value_cls.get_field_by_fieldname("label").supported_choices(version=version)
+            )
+            subfields = [self.subfield] if self.subfield else self.field.value_cls.supported_fields(version=version)
+            for label in labels:
+                for subfield in subfields:
+                    yield FieldPath(field=self.field, label=label, subfield=subfield)
+        else:
+            yield self
+
+    @property
+    def path(self):
+        if self.label:
+            from .indexed_properties import SingleFieldIndexedElement
+
+            if issubclass(self.field.value_cls, SingleFieldIndexedElement) or not self.subfield:
+                return f"{self.field.name}__{self.label}"
+            return f"{self.field.name}__{self.label}__{self.subfield.name}"
+        return self.field.name
+
+    def __eq__(self, other):
+        return hash(self) == hash(other)
+
+    def __str__(self):
+        return self.path
+
+    def __repr__(self):
+        return self.__class__.__name__ + repr((self.field, self.label, self.subfield))
+
+    def __hash__(self):
+        return hash((self.field, self.label, self.subfield))
+
+
+class FieldOrder:
+    """Holds values needed to call server-side sorting on a single field path."""
+
+    def __init__(self, field_path, reverse=False):
+        """
+
+        :param field_path: A FieldPath instance
+        :param reverse: A bool
+        """
+        self.field_path = field_path
+        self.reverse = reverse
+
+    @classmethod
+    def from_string(cls, field_path, folder):
+        return cls(
+            field_path=FieldPath.from_string(field_path=field_path.lstrip("-"), folder=folder, strict=True),
+            reverse=field_path.startswith("-"),
+        )
+
+    def to_xml(self):
+        field_order = create_element("t:FieldOrder", attrs=dict(Order="Descending" if self.reverse else "Ascending"))
+        field_order.append(self.field_path.to_xml())
+        return field_order
+
+
+class Field(SupportedVersionInstanceMixIn, metaclass=abc.ABCMeta):
+    """Holds information related to an item field."""
+
+    value_cls = None
+    is_list = False
+    # Is the field a complex EWS type? Quoting the EWS FindItem docs:
+    #
+    #   The FindItem operation returns only the first 512 bytes of any streamable property. For Unicode, it returns
+    #   the first 255 characters by using a null-terminated Unicode string. It does not return any of the message
+    #   body formats or the recipient lists.
+    #
+    is_complex = False
+
+    def __init__(
+        self,
+        name=None,
+        is_required=False,
+        is_required_after_save=False,
+        is_read_only=False,
+        is_read_only_after_send=False,
+        is_searchable=True,
+        is_attribute=False,
+        default=None,
+        **kwargs,
+    ):
+        self.name = name  # Usually set by the EWSMeta metaclass
+        self.default = default  # Default value if none is given
+        self.is_required = is_required
+        # Some fields cannot be deleted on update. Default to True if 'is_required' is set
+        self.is_required_after_save = is_required or is_required_after_save
+        self.is_read_only = is_read_only
+        # Set this for fields that raise ErrorInvalidPropertyUpdateSentMessage on update after send. Default to True
+        # if 'is_read_only' is set
+        self.is_read_only_after_send = is_read_only or is_read_only_after_send
+        # Define whether the field can be used in a QuerySet. For some reason, EWS disallows searching on some fields,
+        # instead throwing ErrorInvalidValueForProperty
+        self.is_searchable = is_searchable
+        # When true, this field is treated as an XML attribute instead of an element
+        self.is_attribute = is_attribute
+        super().__init__(**kwargs)
+
+    def clean(self, value, version=None):
+        if version and not self.supports_version(version):
+            raise InvalidFieldForVersion(
+                f"Field {self.name!r} does not support EWS builds prior to {self.supported_from} (server has {version})"
+            )
+        if value is None:
+            if self.is_required and self.default is None:
+                raise ValueError(f"{self.name!r} is a required field with no default")
+            return self.default
+        if self.is_list:
+            if not is_iterable(value):
+                raise TypeError(f"Field {self.name!r} value {value!r} must be of type {list}")
+            for v in value:
+                if not isinstance(v, self.value_cls):
+                    raise TypeError(f"Field {self.name!r} value {v!r} must be of type {self.value_cls}")
+                if hasattr(v, "clean"):
+                    v.clean(version=version)
+        else:
+            if not isinstance(value, self.value_cls):
+                raise TypeError(f"Field {self.name!r} value {value!r} must be of type {self.value_cls}")
+            if hasattr(value, "clean"):
+                value.clean(version=version)
+        return value
+
+    @abc.abstractmethod
+    def from_xml(self, elem, account):
+        """Read a value from the given element"""
+
+    @abc.abstractmethod
+    def to_xml(self, value, version):
+        """Convert this field to an XML element"""
+
+    def __eq__(self, other):
+        return hash(self) == hash(other)
+
+    @abc.abstractmethod
+    def __hash__(self):
+        """Field instances must be hashable"""
+
+    def __repr__(self):
+        args_str = ", ".join(
+            f"{f}={getattr(self, f)!r}" for f in ("name", "value_cls", "is_list", "is_complex", "default")
+        )
+        return f"{self.__class__.__name__}({args_str})"
+
+
+class FieldURIField(Field):
+    """A field that has a FieldURI value in EWS. This means it's value is contained in an XML element or attribute. It
+    may additionally be a label for searching, filtering and limiting fields. In that case, the FieldURI format will be
+    'itemtype:FieldName'
+    """
+
+    def __init__(self, *args, **kwargs):
+        self.field_uri = kwargs.pop("field_uri", None)
+        self.namespace = kwargs.pop("namespace", TNS)
+        super().__init__(*args, **kwargs)
+        # See all valid FieldURI values at
+        # https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/fielduri
+        # The field_uri has a prefix when the FieldURI points to an Item field.
+        if self.field_uri is None:
+            self.field_uri_postfix = None
+        elif ":" in self.field_uri:
+            self.field_uri_postfix = self.field_uri.split(":")[1]
+        else:
+            self.field_uri_postfix = self.field_uri
+
+    def _get_val_from_elem(self, elem):
+        if self.is_attribute:
+            return elem.get(self.field_uri) or None
+        return get_xml_attr(elem, self.response_tag())
+
+    def from_xml(self, elem, account):
+        val = self._get_val_from_elem(elem)
+        if val is not None:
+            try:
+                return xml_text_to_value(val, self.value_cls)
+            except (ValueError, InvalidOperation):
+                log.warning("Cannot convert value '%s' on field '%s' to type %s", val, self.name, self.value_cls)
+                return None
+        return self.default
+
+    def to_xml(self, value, version):
+        field_elem = create_element(self.request_tag())
+        return set_xml_value(field_elem, value, version=version)
+
+    def field_uri_xml(self):
+        from .properties import FieldURI
+
+        if not self.field_uri:
+            raise ValueError(f"'field_uri' value is missing on field '{self.name}'")
+        return FieldURI(field_uri=self.field_uri).to_xml(version=None)
+
+    def request_tag(self):
+        if not self.field_uri_postfix:
+            raise ValueError(f"'field_uri_postfix' value is missing on field '{self.name}'")
+        return f"t:{self.field_uri_postfix}"
+
+    def response_tag(self):
+        if not self.field_uri_postfix:
+            raise ValueError(f"'field_uri_postfix' value is missing on field '{self.name}'")
+        return f"{{{self.namespace}}}{self.field_uri_postfix}"
+
+    def __hash__(self):
+        return hash(self.field_uri)
+
+
+class BooleanField(FieldURIField):
+    """A field that handles boolean values."""
+
+    value_cls = bool
+
+
+class IntegerField(FieldURIField):
+    """A field that handles integer values."""
+
+    value_cls = int
+
+    def __init__(self, *args, **kwargs):
+        self.min = kwargs.pop("min", None)
+        self.max = kwargs.pop("max", None)
+        super().__init__(*args, **kwargs)
+
+    def _clean_single_value(self, v):
+        if self.min is not None and v < self.min:
+            raise ValueError(f"Value {v!r} on field {self.name!r} must be greater than {self.min}")
+        if self.max is not None and v > self.max:
+            raise ValueError(f"Value {v!r} on field {self.name!r} must be less than {self.max}")
+
+    def clean(self, value, version=None):
+        value = super().clean(value, version=version)
+        if value is not None:
+            if self.is_list:
+                for v in value:
+                    self._clean_single_value(v)
+            else:
+                self._clean_single_value(value)
+        return value
+
+
+class DecimalField(IntegerField):
+    """A field that handles decimal values."""
+
+    value_cls = Decimal
+
+
+class EnumField(IntegerField):
+    """A field type where you can enter either the 1-based index in an enum (tuple), or the enum value. Values will be
+    stored internally as integers but output in XML as strings.
+    """
+
+    def __init__(self, *args, **kwargs):
+        self.enum = kwargs.pop("enum")
+        # Set different min/max defaults than IntegerField
+        if "max" in kwargs:
+            raise AttributeError("EnumField does not support the 'max' attribute")
+        kwargs["min"] = kwargs.pop("min", 1)
+        kwargs["max"] = kwargs["min"] + len(self.enum) - 1
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        if self.is_list:
+            value = list(value)  # Convert to something we can index
+            for i, v in enumerate(value):
+                if isinstance(v, str):
+                    if v not in self.enum:
+                        raise ValueError(f"List value {v!r} on field {self.name!r} must be one of {sorted(self.enum)}")
+                    value[i] = self.enum.index(v) + 1
+            if not value:
+                raise ValueError(f"Value {value!r} on field {self.name!r} must not be empty")
+            if len(value) > len(set(value)):
+                raise ValueError(f"List entries {value!r} on field {self.name!r} must be unique")
+        else:
+            if isinstance(value, str):
+                if value not in self.enum:
+                    raise ValueError(f"Value {value!r} on field {self.name!r} must be one of {sorted(self.enum)}")
+                value = self.enum.index(value) + 1
+        return super().clean(value, version=version)
+
+    def as_string(self, value):
+        # Converts an integer in the enum to its equivalent string
+        if self.is_list:
+            return [self.enum[v - 1] for v in sorted(value)]
+        return self.enum[value - 1]
+
+    def from_xml(self, elem, account):
+        val = self._get_val_from_elem(elem)
+        if val is not None:
+            try:
+                if self.is_list:
+                    return [self.enum.index(v) + 1 for v in val.split(" ")]
+                return self.enum.index(val) + 1
+            except ValueError:
+                log.warning("Cannot convert value '%s' on field '%s' to type %s", val, self.name, self.value_cls)
+                return None
+        return self.default
+
+    def to_xml(self, value, version):
+        field_elem = create_element(self.request_tag())
+        if self.is_list:
+            return set_xml_value(field_elem, " ".join(self.as_string(value)), version=version)
+        return set_xml_value(field_elem, self.as_string(value), version=version)
+
+
+class EnumListField(EnumField):
+    """Like EnumField, but for lists of enum values."""
+
+    is_list = True
+
+
+class WeekdaysField(EnumListField):
+    """Like EnumListField, allow a single value instead of a 1-element list."""
+
+    def clean(self, value, version=None):
+        if isinstance(value, (int, str)):
+            value = [value]
+        return super().clean(value, version)
+
+
+class EnumAsIntField(EnumField):
+    """Like EnumField, but communicates values with EWS in integers."""
+
+    def from_xml(self, elem, account):
+        return super(EnumField, self).from_xml(elem=elem, account=account)
+
+    def to_xml(self, value, version):
+        field_elem = create_element(self.request_tag())
+        return set_xml_value(field_elem, value, version=version)
+
+
+class AppointmentStateField(IntegerField):
+    """MSDN: https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/appointmentstate"""
+
+    NONE = "None"
+    MEETING = "Meeting"
+    RECEIVED = "Received"
+    CANCELLED = "Canceled"
+    STATES = {
+        NONE: 0x0000,
+        MEETING: 0x0001,
+        RECEIVED: 0x0002,
+        CANCELLED: 0x0004,
+    }
+
+    def from_xml(self, elem, account):
+        val = super().from_xml(elem=elem, account=account)
+        if val is None:
+            return val
+        return tuple(name for name, mask in self.STATES.items() if bool(val & mask))
+
+
+class Base64Field(FieldURIField):
+    """A field that handles binary data and automatically Base64 encodes and decodes the data."""
+
+    value_cls = bytes
+    is_complex = True
+
+    def __init__(self, *args, **kwargs):
+        if "is_searchable" not in kwargs:
+            kwargs["is_searchable"] = False
+        super().__init__(*args, **kwargs)
+
+
+class MimeContentField(Base64Field):
+    """Like Base64Field. This element has an optional 'CharacterSet' attribute, but it specifies the encoding of the
+    base64-encoded string (which doesn't make sense since base64-encoded strings are always ASCII). We ignore it here
+    because the decoded data could be in some other encoding, specified in the "Content-Type" HTTP header.
+    """
+
+
+class DateField(FieldURIField):
+    """A field that handles date values."""
+
+    value_cls = EWSDate
+
+    def clean(self, value, version=None):
+        # Allow plain datetime.date values as input
+        if type(value) is datetime.date:
+            value = self.value_cls.from_date(value)
+        return super().clean(value=value, version=version)
+
+
+class DateTimeBackedDateField(DateField):
+    """A field that acts like a date, but where values are sent to EWS as EWSDateTime."""
+
+    def __init__(self, *args, **kwargs):
+        # Not all fields assume a default time of 00:00, so make this configurable
+        self._default_time = kwargs.pop("default_time", datetime.time(0, 0))
+        # Create internal field to handle datetime-only logic
+        self._datetime_field = DateTimeField(*args, **kwargs)
+        kwargs.pop("allow_naive", None)
+        super().__init__(*args, **kwargs)
+
+    def date_to_datetime(self, value):
+        return self._datetime_field.value_cls.combine(value, self._default_time).replace(tzinfo=UTC)
+
+    def from_xml(self, elem, account):
+        val = self._get_val_from_elem(elem)
+        if val is not None and len(val) == 25:
+            # This is a datetime string with timezone info, e.g. '2021-03-01T21:55:54+00:00'. We don't want to have
+            # datetime values converted to UTC before converting to date. EWSDateTime.from_string() insists on
+            # converting to UTC, but we don't have an EWSTimeZone we can convert the timezone info to. Instead, parse
+            # the string with .fromisoformat().
+            return datetime.datetime.fromisoformat(val).date()
+        # Revert to default parsing of datetime strings
+        res = self._datetime_field.from_xml(elem=elem, account=account)
+        if res is None:
+            return res
+        return res.date()
+
+    def to_xml(self, value, version):
+        # Convert date to datetime
+        value = self.date_to_datetime(value)
+        return self._datetime_field.to_xml(value=value, version=version)
+
+
+class TimeField(FieldURIField):
+    """A field that handles time values."""
+
+    value_cls = datetime.time
+
+    def from_xml(self, elem, account):
+        val = self._get_val_from_elem(elem)
+        if val is not None:
+            with suppress(ValueError):
+                if ":" in val:
+                    # Assume a string of the form HH:MM:SS
+                    return datetime.datetime.strptime(val, "%H:%M:%S").time()
+                # Assume an integer in minutes since midnight
+                return (datetime.datetime(2000, 1, 1) + datetime.timedelta(minutes=int(val))).time()
+        return self.default
+
+
+class TimeDeltaField(FieldURIField):
+    """A field that handles timedelta values."""
+
+    value_cls = datetime.timedelta
+
+    def __init__(self, *args, **kwargs):
+        self.min = kwargs.pop("min", datetime.timedelta(0))
+        self.max = kwargs.pop("max", datetime.timedelta(days=1))
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        if self.min is not None and value < self.min:
+            raise ValueError(f"Value {value!r} on field {self.name!r} must be greater than {self.min}")
+        if self.max is not None and value > self.max:
+            raise ValueError(f"Value {value!r} on field {self.name!r} must be less than {self.max}")
+        return super().clean(value, version=version)
+
+
+class DateTimeField(FieldURIField):
+    """A field that handles datetime values."""
+
+    value_cls = EWSDateTime
+
+    def __init__(self, *args, **kwargs):
+        self.allow_naive = kwargs.pop("allow_naive", False)
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        if isinstance(value, datetime.datetime):
+            if not value.tzinfo:
+                raise ValueError(f"Value {value!r} on field {self.name!r} must be timezone aware")
+            if type(value) is datetime.datetime:
+                value = self.value_cls.from_datetime(value)
+        return super().clean(value, version=version)
+
+    def from_xml(self, elem, account):
+        val = self._get_val_from_elem(elem)
+        if val is not None:
+            try:
+                return self.value_cls.from_string(val)
+            except ValueError as e:
+                if isinstance(e, NaiveDateTimeNotAllowed):
+                    # We encountered a naive datetime
+                    if account:
+                        # Convert to timezone-aware datetime using the default timezone of the account
+                        tz = account.default_timezone
+                        log.info("Found naive datetime %s on field %s. Assuming timezone %s", e.local_dt, self.name, tz)
+                        return e.local_dt.replace(tzinfo=tz)
+                    if not self.allow_naive:
+                        # There's nothing we can do but return the naive date. It's better than assuming e.g. UTC.
+                        # Making this a hard error is probably too risky. Warn instead.
+                        log.warning("Returning naive datetime %s on field %s", e.local_dt, self.name)
+                    return e.local_dt
+                log.info("Cannot convert value '%s' on field '%s' to type %s", val, self.name, self.value_cls)
+                return None
+        return self.default
+
+
+class DateOrDateTimeField(DateTimeField):
+    """This field can handle both EWSDate and EWSDateTime. Used for calendar items where 'start' and 'end'
+    values are conceptually dates when the calendar item is an all-day event, but datetimes in all other cases, and
+    for recurrences where the returned 'start' and 'end' values may be either dates or datetimes depending on whether
+    the recurring item is a task or a calendar item.
+
+    For all-day calendar items, we assume both start and end dates are inclusive.
+
+    For filtering kwarg validation and other places where we must decide on a specific class, we settle on datetime.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # Create internal field to handle date-only logic
+        self._date_field = DateField(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        # Most calendar items will contain datetime values. We can't access the is_all_day value here, so CalendarItem
+        # must handle that sanity check.
+        if type(value) in (EWSDate, datetime.date):
+            return self._date_field.clean(value=value, version=version)
+        return super().clean(value=value, version=version)
+
+    def from_xml(self, elem, account):
+        val = self._get_val_from_elem(elem)
+        if val is not None and len(val) in (11, 16):
+            # This is a date with timezone info, as sent by task recurrences. Eg: '2006-01-09+01:00' or '2006-01-09Z'
+            return self._date_field.from_xml(elem=elem, account=account)
+        return super().from_xml(elem=elem, account=account)
+
+
+class TimeZoneField(FieldURIField):
+    """A field that handles timezone values."""
+
+    value_cls = EWSTimeZone
+
+    def clean(self, value, version=None):
+        # Allow other timezone implementations as input
+        if value is not None:
+            value = self.value_cls.from_timezone(value)
+        return super().clean(value=value, version=version)
+
+    def from_xml(self, elem, account):
+        field_elem = elem.find(self.response_tag())
+        if field_elem is not None:
+            tz_id = field_elem.get("Id") or field_elem.get("Name")
+            try:
+                return self.value_cls.from_ms_id(tz_id)
+            except UnknownTimeZone:
+                warnings.warn(
+                    f"""\
+Cannot convert value {tz_id!r} on field {self.name!r} to type {self.value_cls.__name__!r} (unknown timezone ID).
+You can fix this by adding a custom entry into the timezone translation map:
+
+from exchangelib.winzone import MS_TIMEZONE_TO_IANA_MAP, CLDR_TO_MS_TIMEZONE_MAP
+
+# Replace "Some_Region/Some_Location" with a reasonable value from CLDR_TO_MS_TIMEZONE_MAP.keys()
+MS_TIMEZONE_TO_IANA_MAP[{tz_id!r}] = "Some_Region/Some_Location"
+
+# Your code here"""
+                )
+                return None
+        return self.default
+
+    def to_xml(self, value, version):
+        attrs = dict(Id=value.ms_id)
+        if value.ms_name:
+            attrs["Name"] = value.ms_name
+        return create_element(self.request_tag(), attrs=attrs)
+
+
+class TextField(FieldURIField):
+    """A field that stores a string value with no length limit."""
+
+    value_cls = str
+    is_complex = True
+
+
+class TextListField(TextField):
+    """Like TextField, but for lists of text."""
+
+    is_list = True
+
+    def __init__(self, *args, **kwargs):
+        self.list_elem_name = kwargs.pop("list_elem_name", "String")
+        super().__init__(*args, **kwargs)
+
+    def list_elem_request_tag(self):
+        return f"t:{self.list_elem_name}"
+
+    def list_elem_response_tag(self):
+        return f"{{{self.namespace}}}{self.list_elem_name}"
+
+    def from_xml(self, elem, account):
+        iter_elem = elem.find(self.response_tag())
+        if iter_elem is not None:
+            return get_xml_attrs(iter_elem, self.list_elem_response_tag())
+        return self.default
+
+    def to_xml(self, value, version):
+        field_elem = create_element(self.request_tag())
+        for v in value:
+            field_elem.append(set_xml_value(create_element(self.list_elem_request_tag()), v, version=version))
+        return field_elem
+
+
+class MessageField(TextField):
+    """A field that handles the Message element."""
+
+    INNER_ELEMENT_NAME = "Message"
+
+    def from_xml(self, elem, account):
+        reply = elem.find(self.response_tag())
+        if reply is None:
+            return None
+        message = reply.find(f"{{{TNS}}}{self.INNER_ELEMENT_NAME}")
+        if message is None:
+            return None
+        return message.text
+
+    def to_xml(self, value, version):
+        field_elem = create_element(self.request_tag())
+        message = create_element(f"t:{self.INNER_ELEMENT_NAME}")
+        message.text = value
+        return set_xml_value(field_elem, message, version=version)
+
+
+class CharField(TextField):
+    """A field that stores a string value with a limited length."""
+
+    is_complex = False
+
+    def __init__(self, *args, **kwargs):
+        self.max_length = kwargs.pop("max_length", 255)
+        if not 1 <= self.max_length <= 255:
+            # A field supporting messages longer than 255 chars should be TextField
+            raise ValueError("'max_length' must be in the range 1-255")
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        value = super().clean(value, version=version)
+        if value is not None and len(value) > self.max_length:
+            raise ValueError(f"{self.name!r} value {value!r} exceeds length {self.max_length}")
+        return value
+
+
+class IdField(CharField):
+    """A field to hold the 'Id' and 'Changekey' attributes on 'ItemId' type items. There is no guaranteed max length,
+    but we can assume 512 bytes in practice. See
+    https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/ews-identifiers-in-exchange
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.max_length = 512  # This is above the normal 255 limit, but this is actually an attribute, not a field
+        self.is_searchable = False
+        self.is_attribute = True
+
+
+class CharListField(TextListField):
+    """Like TextListField, but for string values with a limited length."""
+
+    def __init__(self, *args, **kwargs):
+        self.max_length = kwargs.pop("max_length", 255)
+        if not 1 <= self.max_length <= 255:
+            # A field supporting messages longer than 255 chars should be TextField
+            raise ValueError("'max_length' must be in the range 1-255")
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        value = super().clean(value, version=version)
+        if value is not None:
+            for v in value:
+                if len(v) > self.max_length:
+                    raise ValueError(f"{self.name!r} value {v!r} exceeds length {self.max_length}")
+        return value
+
+
+class URIField(TextField):
+    """Helper to mark strings that must conform to xsd:anyURI.
+    If we want a URI validator, see https://stackoverflow.com/questions/14466585/is-this-regex-correct-for-xsdanyuri
+    """
+
+
+class EmailAddressField(CharField):
+    """A helper class used for email address string that we can use for email validation."""
+
+
+class CultureField(CharField):
+    """Helper to mark strings that are # RFC 1766 culture values."""
+
+
+class Choice(SupportedVersionInstanceMixIn):
+    """Implement versioned choices for the ChoiceField field."""
+
+    def __init__(self, value, *args, **kwargs):
+        self.value = value
+        super().__init__(*args, **kwargs)
+
+
+class ChoiceField(CharField):
+    """Like CharField, but restricts the value to a limited set of strings."""
+
+    def __init__(self, *args, **kwargs):
+        self.choices = kwargs.pop("choices")
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        value = super().clean(value, version=version)
+        if value is None:
+            return None
+        valid_choices = [c.value for c in self.choices]
+        if version:
+            valid_choices_for_version = self.supported_choices(version=version)
+            if value in valid_choices_for_version:
+                return value
+            if value in valid_choices:
+                raise InvalidChoiceForVersion(
+                    f"Choice {self.name!r} only supports server versions from {self.supported_from or '*'} to "
+                    f"{self.deprecated_from or '*'} (server has {version})"
+                )
+        else:
+            if value in valid_choices:
+                return value
+        raise ValueError(f"Invalid choice {value!r} for field {self.name!r}. Valid choices are {sorted(valid_choices)}")
+
+    def supported_choices(self, version):
+        return tuple(c.value for c in self.choices if c.supports_version(version))
+
+
+FREE_BUSY_CHOICES = [
+    Choice("Free"),
+    Choice("Tentative"),
+    Choice("Busy"),
+    Choice("OOF"),
+    Choice("NoData"),
+    Choice("WorkingElsewhere", supported_from=EXCHANGE_2013),
+]
+
+
+class FreeBusyStatusField(ChoiceField):
+    """Like ChoiceField, but specifically for Free/Busy values."""
+
+    def __init__(self, *args, **kwargs):
+        kwargs["choices"] = set(FREE_BUSY_CHOICES)
+        super().__init__(*args, **kwargs)
+
+
+class BodyField(TextField):
+    """A TextField with specific requirements for the Item body."""
+
+    def __init__(self, *args, **kwargs):
+        from .properties import Body
+
+        self.value_cls = Body
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        if value is not None and not isinstance(value, self.value_cls):
+            value = self.value_cls(value)
+        return super().clean(value, version=version)
+
+    def from_xml(self, elem, account):
+        from .properties import Body, HTMLBody
+
+        field_elem = elem.find(self.response_tag())
+        val = None if field_elem is None else field_elem.text or None
+        if val is not None:
+            body_type = field_elem.get("BodyType")
+            return {Body.body_type: Body, HTMLBody.body_type: HTMLBody}[body_type](val)
+        return self.default
+
+    def to_xml(self, value, version):
+        from .properties import Body, HTMLBody
+
+        body_type = {
+            Body: Body.body_type,
+            HTMLBody: HTMLBody.body_type,
+        }[type(value)]
+        field_elem = create_element(self.request_tag(), attrs=dict(BodyType=body_type))
+        return set_xml_value(field_elem, value, version=version)
+
+
+class EWSElementField(FieldURIField):
+    """A generic field for any EWSElement object."""
+
+    def __init__(self, *args, **kwargs):
+        self._value_cls = kwargs.pop("value_cls")
+        if "namespace" not in kwargs:
+            kwargs["namespace"] = self.value_cls.NAMESPACE
+        super().__init__(*args, **kwargs)
+
+    @property
+    def value_cls(self):
+        if isinstance(self._value_cls, str):
+            # Support 'value_cls' as string to allow self-referencing classes. The class must be importable from the
+            # top-level module.
+            self._value_cls = getattr(import_module(self.__module__.split(".")[0]), self._value_cls)
+        return self._value_cls
+
+    def from_xml(self, elem, account):
+        if self.is_list:
+            iter_elem = elem.find(self.response_tag())
+            if iter_elem is not None:
+                return [
+                    self.value_cls.from_xml(elem=e, account=account)
+                    for e in iter_elem.findall(self.value_cls.response_tag())
+                ]
+        else:
+            if self.field_uri is None:
+                sub_elem = elem.find(self.value_cls.response_tag())
+            else:
+                sub_elem = elem.find(self.response_tag())
+            if sub_elem is not None:
+                return self.value_cls.from_xml(elem=sub_elem, account=account)
+        return self.default
+
+    def to_xml(self, value, version):
+        if self.field_uri is None:
+            return value.to_xml(version=version)
+        field_elem = create_element(self.request_tag())
+        return set_xml_value(field_elem, value, version=version)
+
+
+class EWSElementListField(EWSElementField):
+    """Like EWSElementField, but for lists of EWSElement objects."""
+
+    is_list = True
+    is_complex = True
+
+
+class TransitionListField(EWSElementListField):
+    def __init__(self, *args, **kwargs):
+        from .properties import BaseTransition
+
+        kwargs["value_cls"] = BaseTransition
+        super().__init__(*args, **kwargs)
+
+    def from_xml(self, elem, account):
+        iter_elem = elem.find(self.response_tag()) if self.field_uri else elem
+        if iter_elem is not None:
+            return [
+                self.value_cls.transition_model_from_tag(e.tag).from_xml(elem=e, account=account) for e in iter_elem
+            ]
+        return self.default
+
+
+class AssociatedCalendarItemIdField(EWSElementField):
+    is_complex = True
+
+    def __init__(self, *args, **kwargs):
+        from .properties import AssociatedCalendarItemId
+
+        kwargs["value_cls"] = AssociatedCalendarItemId
+        super().__init__(*args, **kwargs)
+
+    def to_xml(self, value, version):
+        return value.to_xml(version=version)
+
+
+class RecurrenceField(EWSElementField):
+    is_complex = True
+
+    def __init__(self, *args, **kwargs):
+        from .recurrence import Recurrence
+
+        kwargs["value_cls"] = Recurrence
+        super().__init__(*args, **kwargs)
+
+    def to_xml(self, value, version):
+        return value.to_xml(version=version)
+
+
+class TaskRecurrenceField(EWSElementField):
+    is_complex = True
+
+    def __init__(self, *args, **kwargs):
+        from .recurrence import TaskRecurrence
+
+        kwargs["value_cls"] = TaskRecurrence
+        super().__init__(*args, **kwargs)
+
+    def to_xml(self, value, version):
+        return value.to_xml(version=version)
+
+
+class ReferenceItemIdField(EWSElementField):
+    is_complex = True
+
+    def __init__(self, *args, **kwargs):
+        from .properties import ReferenceItemId
+
+        kwargs["value_cls"] = ReferenceItemId
+        super().__init__(*args, **kwargs)
+
+    def to_xml(self, value, version):
+        return value.to_xml(version=version)
+
+
+class OccurrenceField(EWSElementField):
+    is_complex = True
+
+
+class OccurrenceListField(OccurrenceField):
+    is_list = True
+
+
+class MessageHeaderField(EWSElementListField):
+    def __init__(self, *args, **kwargs):
+        from .properties import MessageHeader
+
+        kwargs["value_cls"] = MessageHeader
+        super().__init__(*args, **kwargs)
+
+
+class BaseEmailField(EWSElementField, metaclass=abc.ABCMeta):
+    """Base class for EWSElement classes that have an 'email_address' field that we want to provide helpers for."""
+
+    is_complex = True  # FindItem only returns the name, not the email address
+
+    def clean(self, value, version=None):
+        if isinstance(value, str):
+            value = self.value_cls(email_address=value)
+        return super().clean(value, version=version)
+
+    def from_xml(self, elem, account):
+        if self.field_uri is None:
+            sub_elem = elem.find(self.value_cls.response_tag())
+        else:
+            sub_elem = elem.find(self.response_tag())
+        if sub_elem is not None:
+            if self.field_uri is not None:
+                # We want the nested Mailbox, not the wrapper element
+                nested_elem = sub_elem.find(self.value_cls.response_tag())
+                if nested_elem is None:
+                    raise ValueError(
+                        f"Expected XML element {self.value_cls.response_tag()!r} missing on field {self.name!r}"
+                    )
+                return self.value_cls.from_xml(elem=nested_elem, account=account)
+            return self.value_cls.from_xml(elem=sub_elem, account=account)
+        return self.default
+
+
+class EmailField(BaseEmailField):
+    def __init__(self, *args, **kwargs):
+        from .properties import Email
+
+        kwargs["value_cls"] = Email
+        super().__init__(*args, **kwargs)
+
+
+class RecipientAddressField(BaseEmailField):
+    def __init__(self, *args, **kwargs):
+        from .properties import RecipientAddress
+
+        kwargs["value_cls"] = RecipientAddress
+        super().__init__(*args, **kwargs)
+
+
+class MailboxField(BaseEmailField):
+    def __init__(self, *args, **kwargs):
+        from .properties import Mailbox
+
+        kwargs["value_cls"] = Mailbox
+        super().__init__(*args, **kwargs)
+
+
+class MailboxListField(EWSElementListField):
+    def __init__(self, *args, **kwargs):
+        from .properties import Mailbox
+
+        kwargs["value_cls"] = Mailbox
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        if value is not None:
+            value = [self.value_cls(email_address=s) if isinstance(s, str) else s for s in value]
+        return super().clean(value, version=version)
+
+
+class AddressListField(EWSElementListField):
+    def __init__(self, *args, **kwargs):
+        from .properties import Address
+
+        kwargs["value_cls"] = Address
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        if value is not None:
+            value = [self.value_cls(email_address=s) if isinstance(s, str) else s for s in value]
+        return super().clean(value, version=version)
+
+
+class MemberListField(EWSElementListField):
+    def __init__(self, *args, **kwargs):
+        from .properties import Member
+
+        kwargs["value_cls"] = Member
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        from .properties import Mailbox
+
+        if value is not None:
+            value = [self.value_cls(mailbox=Mailbox(email_address=s)) if isinstance(s, str) else s for s in value]
+        return super().clean(value, version=version)
+
+
+class AttendeesField(EWSElementListField):
+    def __init__(self, *args, **kwargs):
+        from .properties import Attendee
+
+        kwargs["value_cls"] = Attendee
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        from .properties import Mailbox
+
+        if value is not None:
+            value = [
+                self.value_cls(mailbox=Mailbox(email_address=s), response_type="Accept") if isinstance(s, str) else s
+                for s in value
+            ]
+        return super().clean(value, version=version)
+
+
+class AttachmentField(EWSElementListField):
+    """A field for item attachments."""
+
+    def __init__(self, *args, **kwargs):
+        from .attachments import Attachment
+
+        kwargs["value_cls"] = Attachment
+        super().__init__(*args, **kwargs)
+
+    def from_xml(self, elem, account):
+        from .attachments import FileAttachment, ItemAttachment
+
+        iter_elem = elem.find(self.response_tag())
+        # Look for both FileAttachment and ItemAttachment
+        if iter_elem is not None:
+            attachments = []
+            for att_type in (ItemAttachment, FileAttachment):
+                attachments.extend(
+                    [att_type.from_xml(elem=e, account=account) for e in iter_elem.findall(att_type.response_tag())]
+                )
+            return attachments
+        return self.default
+
+
+class LabelField(ChoiceField):
+    """A field to hold the label on an IndexedElement."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.is_attribute = True
+
+    def from_xml(self, elem, account):
+        return elem.get(self.field_uri)
+
+
+class SubField(Field):
+    """A field to hold the value on an IndexedElement."""
+
+    namespace = TNS
+    value_cls = str
+
+    def from_xml(self, elem, account):
+        return elem.text
+
+    def to_xml(self, value, version):
+        return value
+
+    @staticmethod
+    def field_uri_xml(field_uri, label):
+        from .properties import IndexedFieldURI
+
+        return IndexedFieldURI(field_uri=field_uri, field_index=label).to_xml(version=None)
+
+    def clean(self, value, version=None):
+        value = super().clean(value, version=version)
+        if self.is_required and not value:
+            raise ValueError(f"Value for subfield {self.name!r} must be non-empty")
+        return value
+
+    def __hash__(self):
+        return hash(self.name)
+
+
+class EmailSubField(SubField):
+    """A field to hold the value on an SingleFieldIndexedElement."""
+
+    value_cls = str
+
+    def from_xml(self, elem, account):
+        return elem.text or elem.get("Name")  # Sometimes elem.text is empty. Exchange saves the same in 'Name' attr
+
+
+class NamedSubField(SubField):
+    """A field to hold the value on an MultiFieldIndexedElement."""
+
+    value_cls = str
+
+    def __init__(self, *args, **kwargs):
+        self.field_uri = kwargs.pop("field_uri")
+        if ":" in self.field_uri:
+            raise ValueError("'field_uri' value must not contain a colon")
+        super().__init__(*args, **kwargs)
+
+    def from_xml(self, elem, account):
+        field_elem = elem.find(self.response_tag())
+        val = None if field_elem is None else field_elem.text or None
+        if val is not None:
+            return val
+        return self.default
+
+    def to_xml(self, value, version):
+        field_elem = create_element(self.request_tag())
+        return set_xml_value(field_elem, value, version=version)
+
+    def field_uri_xml(self, field_uri, label):
+        from .properties import IndexedFieldURI
+
+        return IndexedFieldURI(field_uri=f"{field_uri}:{self.field_uri}", field_index=label).to_xml(version=None)
+
+    def request_tag(self):
+        return f"t:{self.field_uri}"
+
+    def response_tag(self):
+        return f"{{{self.namespace}}}{self.field_uri}"
+
+
+class IndexedField(EWSElementField, metaclass=abc.ABCMeta):
+    """A base class for all indexed fields."""
+
+    is_list = True
+    is_complex = True
+
+    PARENT_ELEMENT_NAME = None
+
+    def __init__(self, *args, **kwargs):
+        from .indexed_properties import IndexedElement
+
+        value_cls = kwargs["value_cls"]
+        if not issubclass(value_cls, IndexedElement):
+            raise TypeError(f"'value_cls' {value_cls!r} must be a subclass of type {IndexedElement}")
+        super().__init__(*args, **kwargs)
+
+    def to_xml(self, value, version):
+        return set_xml_value(create_element(f"t:{self.PARENT_ELEMENT_NAME}"), value, version=version)
+
+    def response_tag(self):
+        return f"{{{self.namespace}}}{self.PARENT_ELEMENT_NAME}"
+
+    def __hash__(self):
+        return hash(self.field_uri)
+
+
+class SingleFieldIndexedField(IndexedField):
+    """A base class for all single-field indexed fields."""
+
+    def __init__(self, *args, **kwargs):
+        from .indexed_properties import SingleFieldIndexedElement
+
+        value_cls = kwargs["value_cls"]
+        if not issubclass(value_cls, SingleFieldIndexedElement):
+            raise TypeError(f"'value_cls' {value_cls!r} must be a subclass of type {SingleFieldIndexedElement}")
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        if value is not None:
+            default_labels = self.value_cls.LABEL_CHOICES
+            if len(value) > len(default_labels):
+                raise ValueError(f"This field can handle at most {len(default_labels)} values (value: {value})")
+            tmp = []
+            value_field_name = self.value_cls.value_field(version=version).name
+            for s, default_label in zip(value, default_labels):
+                if not isinstance(s, str):
+                    tmp.append(s)
+                    continue
+                tmp.append(self.value_cls(**{"label": default_label, value_field_name: s}))
+            value = tmp
+        return super().clean(value, version=version)
+
+
+class EmailAddressesField(SingleFieldIndexedField):
+    PARENT_ELEMENT_NAME = "EmailAddresses"
+
+    def __init__(self, *args, **kwargs):
+        from .indexed_properties import EmailAddress
+
+        kwargs["value_cls"] = EmailAddress
+        super().__init__(*args, **kwargs)
+
+
+class ImAddressField(SingleFieldIndexedField):
+    PARENT_ELEMENT_NAME = "ImAddresses"
+
+    def __init__(self, *args, **kwargs):
+        from .indexed_properties import ImAddress
+
+        kwargs["value_cls"] = ImAddress
+        super().__init__(*args, **kwargs)
+
+
+class PhoneNumberField(SingleFieldIndexedField):
+    PARENT_ELEMENT_NAME = "PhoneNumbers"
+
+    def __init__(self, *args, **kwargs):
+        from .indexed_properties import PhoneNumber
+
+        kwargs["value_cls"] = PhoneNumber
+        super().__init__(*args, **kwargs)
+
+
+class PhysicalAddressField(IndexedField):
+    is_list = True
+    is_complex = True
+
+    PARENT_ELEMENT_NAME = "PhysicalAddresses"
+
+    def __init__(self, *args, **kwargs):
+        from .indexed_properties import PhysicalAddress
+
+        kwargs["value_cls"] = PhysicalAddress
+        super().__init__(*args, **kwargs)
+
+
+class ExtendedPropertyField(Field):
+    is_complex = True
+
+    def __init__(self, *args, **kwargs):
+        self.value_cls = kwargs.pop("value_cls")
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        if value is None:
+            if self.is_required:
+                raise ValueError(f"{self.name!r} is a required field")
+            return self.default
+        if not isinstance(value, self.value_cls):
+            # Allow keeping ExtendedProperty field values as their simple Python type, but run clean() anyway
+            tmp = self.value_cls(value)
+            tmp.clean(version=version)
+            return value
+        value.clean(version=version)
+        return value
+
+    def field_uri_xml(self):
+        from .properties import ExtendedFieldURI
+
+        cls = self.value_cls
+        return ExtendedFieldURI(
+            distinguished_property_set_id=cls.distinguished_property_set_id,
+            property_set_id=cls.property_set_id.lower() if cls.property_set_id else None,
+            property_tag=cls.property_tag_as_hex(),
+            property_name=cls.property_name,
+            property_id=value_to_xml_text(cls.property_id) if cls.property_id else None,
+            property_type=cls.property_type,
+        ).to_xml(version=None)
+
+    def from_xml(self, elem, account):
+        extended_properties = elem.findall(self.value_cls.response_tag())
+        for extended_property in extended_properties:
+            if self.value_cls.is_property_instance(extended_property):
+                return self.value_cls.from_xml(elem=extended_property, account=account)
+        return self.default
+
+    def to_xml(self, value, version):
+        extended_property = create_element(self.value_cls.request_tag())
+        set_xml_value(extended_property, self.field_uri_xml(), version=version)
+        if isinstance(value, self.value_cls):
+            return set_xml_value(extended_property, value, version=version)
+        # Allow keeping ExtendedProperty field values as their simple Python type
+        return set_xml_value(extended_property, self.value_cls(value), version=version)
+
+    def __hash__(self):
+        return hash(self.name)
+
+
+class ExtendedPropertyListField(ExtendedPropertyField):
+    is_list = True
+
+
+class ItemField(FieldURIField):
+    @property
+    def value_cls(self):
+        from .items import Item
+
+        return Item
+
+    def from_xml(self, elem, account):
+        from .items import ITEM_CLASSES
+
+        for item_cls in ITEM_CLASSES:
+            item_elem = elem.find(item_cls.response_tag())
+            if item_elem is not None:
+                return item_cls.from_xml(elem=item_elem, account=account)
+        return None
+
+    def to_xml(self, value, version):
+        # We don't want to wrap in an Item element
+        return value.to_xml(version=version)
+
+
+class UnknownEntriesField(CharListField):
+    def list_elem_tag(self):
+        return f"{{{self.namespace}}}UnknownEntry"
+
+
+class PermissionSetField(EWSElementField):
+    is_complex = True
+
+    def __init__(self, *args, **kwargs):
+        from .properties import PermissionSet
+
+        kwargs["value_cls"] = PermissionSet
+        super().__init__(*args, **kwargs)
+
+    def to_xml(self, value, version):
+        return value.to_xml(version=version)
+
+
+class EffectiveRightsField(EWSElementField):
+    def __init__(self, *args, **kwargs):
+        from .properties import EffectiveRights
+
+        kwargs["value_cls"] = EffectiveRights
+        super().__init__(*args, **kwargs)
+
+
+class RoutingTypeField(ChoiceField):
+    def __init__(self, *args, **kwargs):
+        kwargs["choices"] = {Choice("SMTP"), Choice("EX")}
+        kwargs["default"] = "SMTP"
+        super().__init__(*args, **kwargs)
+
+
+class IdElementField(EWSElementField):
+    def __init__(self, *args, **kwargs):
+        kwargs["is_searchable"] = False
+        kwargs["is_read_only"] = True
+        super().__init__(*args, **kwargs)
+
+
+class TypeValueField(FieldURIField):
+    """This field type has no value_cls because values may have many types."""
+
+    TYPES_MAP = {
+        "Boolean": bool,
+        "Integer32": int,
+        "UnsignedInteger32": int,
+        "Integer64": int,
+        "UnsignedInteger64": int,
+        # Python doesn't have a single-byte type to represent 'Byte'
+        "ByteArray": bytes,
+        "String": str,
+        "StringArray": str,  # A list of strings
+        "DateTime": EWSDateTime,
+    }
+    TYPES_MAP_REVERSED = {
+        bool: "Boolean",
+        int: "Integer64",
+        # Python doesn't have a single-byte type to represent 'Byte'
+        bytes: "ByteArray",
+        str: "String",
+        datetime.datetime: "DateTime",
+        EWSDateTime: "DateTime",
+    }
+
+    @classmethod
+    def get_type(cls, value):
+        if isinstance(value, bytes) and len(value) == 1:
+            # This is a single byte. Translate it to the 'Byte' type
+            return "Byte"
+        if is_iterable(value):
+            # We don't allow generators as values, so keep the logic simple
+            try:
+                first = next(iter(value))
+            except StopIteration:
+                first = None
+            value_type = f"{cls.TYPES_MAP_REVERSED[type(first)]}Array"
+            if value_type not in cls.TYPES_MAP:
+                raise ValueError(f"{value!r} is not a supported type")
+            return value_type
+        return cls.TYPES_MAP_REVERSED[type(value)]
+
+    @classmethod
+    def is_array_type(cls, value_type):
+        return value_type == "StringArray"
+
+    def clean(self, value, version=None):
+        if value is None:
+            if self.is_required and self.default is None:
+                raise ValueError(f"{self.name!r} is a required field with no default")
+            return self.default
+        return value
+
+    def from_xml(self, elem, account):
+        field_elem = elem.find(self.response_tag())
+        if field_elem is None:
+            return self.default
+        value_type_str = get_xml_attr(field_elem, f"{{{TNS}}}Type")
+        value = get_xml_attr(field_elem, f"{{{TNS}}}Value")
+        if value_type_str == "Byte":
+            try:
+                # The value is an unsigned integer in the range 0 -> 255. Convert it to a single byte
+                return xml_text_to_value(value, int).to_bytes(1, "little", signed=False)
+            except OverflowError as e:
+                log.warning("Invalid byte value %r (%e)", value, e)
+                return None
+        value_type = self.TYPES_MAP[value_type_str]
+        if self.is_array_type(value_type_str):
+            return tuple(xml_text_to_value(value=v, value_type=value_type) for v in value.split(" "))
+        return xml_text_to_value(value=value, value_type=value_type)
+
+    def to_xml(self, value, version):
+        value_type_str = self.get_type(value)
+        if value_type_str == "Byte":
+            # A single byte is encoded to an unsigned integer in the range 0 -> 255
+            value = int.from_bytes(value, byteorder="little", signed=False)
+        elif is_iterable(value):
+            value = " ".join(value_to_xml_text(v) for v in value)
+        field_elem = create_element(self.request_tag())
+        field_elem.append(set_xml_value(create_element("t:Type"), value_type_str, version=version))
+        field_elem.append(set_xml_value(create_element("t:Value"), value, version=version))
+        return field_elem
+
+
+class DictionaryField(FieldURIField):
+    value_cls = dict
+
+    def from_xml(self, elem, account):
+        from .properties import DictionaryEntry
+
+        iter_elem = elem.find(self.response_tag())
+        if iter_elem is not None:
+            entries = [
+                DictionaryEntry.from_xml(elem=e, account=account)
+                for e in iter_elem.findall(DictionaryEntry.response_tag())
+            ]
+            return {e.key: e.value for e in entries}
+        return self.default
+
+    def clean(self, value, version=None):
+        if isinstance(value, dict):
+            cleaned = {}
+            for k, v in value.items():
+                if type(k) is datetime.datetime:
+                    k = EWSDateTime.from_datetime(k)
+                if type(v) is datetime.datetime:
+                    v = EWSDateTime.from_datetime(v)
+                cleaned[k] = v
+            value = cleaned
+        return super().clean(value=value, version=version)
+
+    def to_xml(self, value, version):
+        from .properties import DictionaryEntry
+
+        field_elem = create_element(self.request_tag())
+        entries = [DictionaryEntry(key=k, value=v) for k, v in value.items()]
+        return set_xml_value(field_elem, entries, version=version)
+
+
+class PersonaPhoneNumberField(EWSElementField):
+    is_complex = True
+
+    def __init__(self, *args, **kwargs):
+        from .properties import PhoneNumber
+
+        kwargs["value_cls"] = PhoneNumber
+        super().__init__(*args, **kwargs)
+
+
+class BodyContentAttributedValueField(EWSElementField):
+    is_complex = True
+
+    def __init__(self, *args, **kwargs):
+        from .properties import BodyContentAttributedValue
+
+        kwargs["value_cls"] = BodyContentAttributedValue
+        super().__init__(*args, **kwargs)
+
+
+class StringAttributedValueField(EWSElementListField):
+    def __init__(self, *args, **kwargs):
+        from .properties import StringAttributedValue
+
+        kwargs["value_cls"] = StringAttributedValue
+        super().__init__(*args, **kwargs)
+
+
+class PhoneNumberAttributedValueField(EWSElementListField):
+    def __init__(self, *args, **kwargs):
+        from .properties import PhoneNumberAttributedValue
+
+        kwargs["value_cls"] = PhoneNumberAttributedValue
+        super().__init__(*args, **kwargs)
+
+
+class EmailAddressAttributedValueField(EWSElementListField):
+    def __init__(self, *args, **kwargs):
+        from .properties import EmailAddressAttributedValue
+
+        kwargs["value_cls"] = EmailAddressAttributedValue
+        super().__init__(*args, **kwargs)
+
+
+class PostalAddressAttributedValueField(EWSElementListField):
+    def __init__(self, *args, **kwargs):
+        from .properties import PostalAddressAttributedValue
+
+        kwargs["value_cls"] = PostalAddressAttributedValue
+        super().__init__(*args, **kwargs)
+
+
+class GenericEventListField(EWSElementField):
+    """A list field that can contain all subclasses of Event."""
+
+    is_list = True
+
+    @property
+    def _event_types_map(self):
+        return {v.response_tag(): v for v in self.value_classes}
+
+    def __init__(self, *args, **kwargs):
+        from .properties import (
+            CopiedEvent,
+            CreatedEvent,
+            DeletedEvent,
+            FreeBusyChangedEvent,
+            ModifiedEvent,
+            MovedEvent,
+            NewMailEvent,
+            StatusEvent,
+        )
+
+        kwargs["value_cls"] = None  # Parent class requires this kwarg
+        kwargs["namespace"] = None  # Parent class requires this kwarg
+        super().__init__(*args, **kwargs)
+        self.value_classes = (
+            CopiedEvent,
+            CreatedEvent,
+            DeletedEvent,
+            ModifiedEvent,
+            MovedEvent,
+            NewMailEvent,
+            StatusEvent,
+            FreeBusyChangedEvent,
+        )
+
+    def from_xml(self, elem, account):
+        events = []
+        for event in elem:
+            # This may or may not be an event element. Could also be other child elements of Notification
+            try:
+                value_cls = self._event_types_map[event.tag]
+            except KeyError:
+                continue
+            events.append(value_cls.from_xml(elem=event, account=account))
+        return events or self.default
+
+
+FLAG_ACTION_CHOICES = [
+    Choice("Any"),
+    Choice("Call"),
+    Choice("DoNotForward"),
+    Choice("FollowUp"),
+    Choice("FYI"),
+    Choice("Forward"),
+    Choice("NoResponseNecessary"),
+    Choice("Read"),
+    Choice("Reply"),
+    Choice("ReplyToAll"),
+    Choice("Review"),
+]
+
+
+class FlaggedForActionField(ChoiceField):
+    """
+    A field specifies the flag for action value that
+    must appear on incoming messages in order for the condition
+    or exception to apply.
+    """
+
+    def __init__(self, *args, **kwargs):
+        kwargs["choices"] = FLAG_ACTION_CHOICES
+        super().__init__(*args, **kwargs)
+
+
+IMPORTANCE_CHOICES = [
+    Choice("Low"),
+    Choice("Normal"),
+    Choice("High"),
+]
+
+
+class ImportanceField(ChoiceField):
+    """
+    A field that describes the importance of an item or
+    the aggregated importance of all items in a conversation
+    in the current folder.
+    """
+
+    def __init__(self, *args, **kwargs):
+        kwargs["choices"] = IMPORTANCE_CHOICES
+        super().__init__(*args, **kwargs)
+
+
+SENSITIVITY_CHOICES = [
+    Choice("Normal"),
+    Choice("Personal"),
+    Choice("Private"),
+    Choice("Confidential"),
+]
+
+
+class SensitivityField(ChoiceField):
+    """A field that indicates the sensitivity level of an item."""
+
+    def __init__(self, *args, **kwargs):
+        kwargs["choices"] = SENSITIVITY_CHOICES
+        super().__init__(*args, **kwargs)
+
+
+class FolderActionField(EWSElementField):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def clean(self, value, version=None):
+        from .folders import DistinguishedFolderId, Folder
+
+        if isinstance(value, Folder):
+            folder_id = value.to_id()
+            if isinstance(folder_id, DistinguishedFolderId):
+                value = self.value_cls(distinguished_folder_id=folder_id)
+            else:
+                value = self.value_cls(folder_id=folder_id)
+        return super().clean(value, version=version)