"""This implementes the VAVAILABILITY component.

This is specified in :rfc:`7953`.
"""

from __future__ import annotations

import uuid
from datetime import datetime
from typing import TYPE_CHECKING

from icalendar.attr import (
    CONCEPTS_TYPE_SETTER,
    LINKS_TYPE_SETTER,
    RELATED_TO_TYPE_SETTER,
    busy_type_property,
    categories_property,
    class_property,
    contacts_property,
    description_property,
    duration_property,
    location_property,
    organizer_property,
    priority_property,
    rfc_7953_dtend_property,
    rfc_7953_dtstart_property,
    rfc_7953_duration_property,
    rfc_7953_end_property,
    sequence_property,
    summary_property,
    url_property,
)
from icalendar.cal.examples import get_example
from icalendar.error import InvalidCalendar

from .component import Component

if TYPE_CHECKING:
    from collections.abc import Sequence
    from datetime import date

    from icalendar.cal.available import Available
    from icalendar.enums import BUSYTYPE, CLASS
    from icalendar.prop import vCalAddress


class Availability(Component):
    """VAVAILABILITY component from :rfc:`7953`.

    This provides a grouping of component properties and
    subcomponents that describe the availability associated with a
    calendar user.

    Description:
        A "VAVAILABILITY" component indicates a period of time
        within which availability information is provided.  A
        "VAVAILABILITY" component can specify a start time and an end time
        or duration.  If "DTSTART" is not present, then the start time is
        unbounded.  If "DTEND" or "DURATION" are not present, then the end
        time is unbounded.  Within the specified time period, availability
        defaults to a free-busy type of "BUSY-UNAVAILABLE" (see
        Section 3.2), except for any time periods corresponding to
        "AVAILABLE" subcomponents.

        "AVAILABLE" subcomponents are used to indicate periods of free
        time within the time range of the enclosing "VAVAILABILITY"
        component.  "AVAILABLE" subcomponents MAY include recurrence
        properties to specify recurring periods of time, which can be
        overridden using normal iCalendar recurrence behavior (i.e., use
        of the "RECURRENCE-ID" property).

        If specified, the "DTSTART" and "DTEND" properties in
        "VAVAILABILITY" components and "AVAILABLE" subcomponents MUST be
        "DATE-TIME" values specified as either the date with UTC time or
        the date with local time and a time zone reference.

        The iCalendar object containing the "VAVAILABILITY" component MUST
        contain appropriate "VTIMEZONE" components corresponding to each
        unique "TZID" parameter value used in any DATE-TIME properties in
        all components, unless [RFC7809] is in effect.

        When used to publish available time, the "ORGANIZER" property
        specifies the calendar user associated with the published
        available time.

        If the "PRIORITY" property is specified in "VAVAILABILITY"
        components, it is used to determine how that component is combined
        with other "VAVAILABILITY" components.  See Section 4.

        Other calendar properties MAY be specified in "VAVAILABILITY" or
        "AVAILABLE" components and are considered attributes of the marked
        block of time.  Their usage is application specific.  For example,
        the "LOCATION" property might be used to indicate that a person is
        available in one location for part of the week and a different
        location for another part of the week (but see Section 9 for when
        it is appropriate to add additional data like this).

    Example:
        The following is an example of a "VAVAILABILITY" calendar
        component used to represent the availability of a user, always
        available Monday through Friday, 9:00 am to 5:00 pm in the
        America/Montreal time zone:

        .. code-block:: ics

            BEGIN:VAVAILABILITY
            ORGANIZER:mailto:bernard@example.com
            UID:0428C7D2-688E-4D2E-AC52-CD112E2469DF
            DTSTAMP:20111005T133225Z
            BEGIN:AVAILABLE
            UID:34EDA59B-6BB1-4E94-A66C-64999089C0AF
            SUMMARY:Monday to Friday from 9:00 to 17:00
            DTSTART;TZID=America/Montreal:20111002T090000
            DTEND;TZID=America/Montreal:20111002T170000
            RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR
            END:AVAILABLE
            END:VAVAILABILITY

        You can get the same example from :meth:`example`:

        .. code-block: pycon

            >>> from icalendar import Availability
            >>> a = Availability.example()
            >>> a.organizer
            vCalAddress('mailto:bernard@example.com')

        The following is an example of a "VAVAILABILITY" calendar
        component used to represent the availability of a user available
        Monday through Thursday, 9:00 am to 5:00 pm, at the main office,
        and Friday, 9:00 am to 12:00 pm, in the branch office in the
        America/Montreal time zone between October 2nd and December 2nd
        2011:

        .. code-block:: ics

            BEGIN:VAVAILABILITY
            ORGANIZER:mailto:bernard@example.com
            UID:84D0F948-7FC6-4C1D-BBF3-BA9827B424B5
            DTSTAMP:20111005T133225Z
            DTSTART;TZID=America/Montreal:20111002T000000
            DTEND;TZID=America/Montreal:20111202T000000
            BEGIN:AVAILABLE
            UID:7B33093A-7F98-4EED-B381-A5652530F04D
            SUMMARY:Monday to Thursday from 9:00 to 17:00
            DTSTART;TZID=America/Montreal:20111002T090000
            DTEND;TZID=America/Montreal:20111002T170000
            RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH
            LOCATION:Main Office
            END:AVAILABLE
            BEGIN:AVAILABLE
            UID:DF39DC9E-D8C3-492F-9101-0434E8FC1896
            SUMMARY:Friday from 9:00 to 12:00
            DTSTART;TZID=America/Montreal:20111006T090000
            DTEND;TZID=America/Montreal:20111006T120000
            RRULE:FREQ=WEEKLY
            LOCATION:Branch Office
            END:AVAILABLE
            END:VAVAILABILITY

        For more examples, have a look at :rfc:`5545`.

    """

    name = "VAVAILABILITY"

    canonical_order = (
        "DTSTART",
        "DTEND",
        "DURATION",
        "DTSTAMP",
        "UID",
        "SEQUENCE",
        "SUMMARY",
        "DESCRIPTION",
        "ORGANIZER",
    )

    required = (
        "DTSTART",
        "DTSTAMP",
        "UID",
    )

    singletons = (
        "DTSTAMP",
        "UID",
        "BUSYTYPE",
        "CLASS",
        "CREATED",
        "DESCRIPTION",
        "DTSTART",
        "LAST-MODIFIED",
        "LOCATION",
        "ORGANIZER",
        "PRIORITY",
        "SEQUENCE",
        "SUMMARY",
        "URL",
        "DTEND",
        "DURATION",
    )

    exclusive = (
        "DTEND",
        "DURATION",
    )

    organizer = organizer_property
    busy_type = busy_type_property
    summary = summary_property
    description = description_property
    sequence = sequence_property
    classification = class_property
    url = url_property
    location = location_property
    categories = categories_property
    priority = priority_property
    contacts = contacts_property

    start = DTSTART = rfc_7953_dtstart_property
    DTEND = rfc_7953_dtend_property
    DURATION = duration_property("Availability")
    duration = rfc_7953_duration_property
    end = rfc_7953_end_property

    @property
    def available(self) -> list[Available]:
        """All VAVAILABLE sub-components.

        This is a shortcut to get all VAVAILABLE sub-components.
        Modifications do not change the calendar.
        Use :py:meth:`Component.add_component`.
        """
        return self.walk("AVAILABLE")

    @classmethod
    def new(
        cls,
        /,
        busy_type: BUSYTYPE | None = None,
        categories: Sequence[str] = (),
        comments: list[str] | str | None = None,
        components: Sequence[Available] | None = (),
        concepts: CONCEPTS_TYPE_SETTER = None,
        contacts: list[str] | str | None = None,
        created: date | None = None,
        classification: CLASS | None = None,
        description: str | None = None,
        end: datetime | None = None,
        last_modified: date | None = None,
        links: LINKS_TYPE_SETTER = None,
        location: str | None = None,
        organizer: vCalAddress | str | None = None,
        priority: int | None = None,
        refids: list[str] | str | None = None,
        related_to: RELATED_TO_TYPE_SETTER = None,
        sequence: int | None = None,
        stamp: date | None = None,
        start: datetime | None = None,
        summary: str | None = None,
        uid: str | uuid.UUID | None = None,
        url: str | None = None,
    ):
        """Create a new event with all required properties.

        This creates a new Availability in accordance with :rfc:`7953`.

        Parameters:
            busy_type: The :attr:`busy_type` of the availability.
            categories: The :attr:`categories` of the availability.
            classification: The :attr:`classification` of the availability.
            comments: The :attr:`comments` of the availability.
            concepts: The :attr:`concepts` of the availability.
            contacts: The :attr:`contacts` of the availability.
            created: The :attr:`created` of the availability.
            description: The :attr:`description` of the availability.
            end: The :attr:`end` of the availability.
            last_modified: The :attr:`last_modified` of the
                availability.
            links: The :attr:`links` of the availability.
            location: The :attr:`location` of the availability.
            organizer: The :attr:`organizer` of the availability.
            refids: :attr:`refids` of the availability.
            related_to: :attr:`related_to` of the availability.
            sequence: The :attr:`sequence` of the availability.
            stamp: The :attr:`stamp` of the availability.
                If None, this is set to the current time.
            start: The :attr:`start` of the availability.
            summary: The :attr:`summary` of the availability.
            uid: The :attr:`uid` of the availability.
                If ``None``, this is set to a new :func:`uuid.uuid4`.
            url: The :attr:`url` of the availability.

        Returns:
            :class:`Availability`

        Raises:
            ~error.InvalidCalendar: If the content is not valid
                according to :rfc:`7953`.

        .. warning:: As time progresses, we will be stricter with the validation.
        """
        availability: Availability = super().new(
            stamp=stamp if stamp is not None else cls._utc_now(),
            created=created,
            comments=comments,
            last_modified=last_modified,
            links=links,
            related_to=related_to,
            refids=refids,
            concepts=concepts,
        )
        availability.summary = summary
        availability.description = description
        availability.uid = uid if uid is not None else uuid.uuid4()
        availability.sequence = sequence
        availability.categories = categories
        availability.classification = classification
        availability.url = url
        availability.busy_type = busy_type
        availability.organizer = organizer
        availability.location = location
        availability.priority = priority
        availability.contacts = contacts
        for subcomponent in components:
            availability.add_component(subcomponent)
        if cls._validate_new:
            if start is not None and (
                not isinstance(start, datetime) or start.tzinfo is None
            ):
                raise InvalidCalendar(
                    "Availability start must be a datetime with a timezone"
                )
            if end is not None and (
                not isinstance(end, datetime) or end.tzinfo is None
            ):
                raise InvalidCalendar(
                    "Availability end must be a datetime with a timezone"
                )
            availability._validate_start_and_end(start, end)
        availability.start = start
        availability.end = end
        return availability

    @classmethod
    def example(cls, name: str = "rfc_7953_1") -> Availability:
        """Return the calendar example with the given name."""
        return cls.from_ical(get_example("availabilities", name))


__all__ = ["Availability"]
