o .j@s^dZddlmZddlZddlmZddlmZmZmZm Z m Z ddl m Z ddl mZmZmZmZmZddlmZmZmZmZmZmZmZmZmZmZdd lmZdd l m!Z!dd l"m#Z#m$Z$dd l%m&Z&m'Z'm(Z(m)Z)m*Z*dd l+m,Z,ddl-m.Z.ddl/m0Z0m1Z1m2Z2m3Z3ddl4m5Z5ddl6m7Z7erddl8m9Z9ddl:m;Z;gZdS)z$The base for :rfc:`5545` components.) annotationsN)deepcopy)datedatetimetime timedeltatimezone)Path) TYPE_CHECKINGAnyClassVarLiteraloverload) CONCEPTS_TYPE_SETTERLINKS_TYPE_SETTERRELATED_TO_TYPE_SETTERcomments_propertyconcepts_propertylinks_propertyrefids_propertyrelated_to_propertysingle_utc_property uid_property)ComponentFactory) CaselessDict)InvalidCalendarJCalParsingError) Contentline Contentlines Parametersq_joinq_split)ComponentIcalParser)DEFAULT_ENCODING) VPROPERTY TypesFactory vDDDListsvText)tzpis_date)Iterable)Selfcs>eZdZUdZdZded< dZded< dZded< dZded < dZ ded < dZ d ed < d Z ded< e Zded<dZded<ded< edddZedddZedd d!Zedd%d&Zfd'd(Zd)d*Zfd+d,Zdd-d.Zd/d0Zedd2d3Z  4ddd9d:Zdde?Z@eAZBeCZDeEZFe0ddZGd4ZHeddZIe         ddddZJdddZKdddZLedddZMddLJfdd ZNdddZOdddZPZQS) ComponentzBase class for calendar components. Component is the base object for calendar, Event and the other components defined in :rfc:`5545`. Normally you will not use this class directly, but rather one of the subclasses. NzClassVar[str | None]namezClassVar[tuple[()]]required singletonsmultiple exclusivez-ClassVar[tuple[str] | tuple[tuple[str, str]]] inclusiveFzClassVar[bool]ignore_exceptionszClassVar[TypesFactory] types_factoryz!ClassVar[ComponentFactory | None]_components_factorylist[Component] subcomponentsreturnrcCs|jdur t|_|jS)zGet the component factory.N)r7r)clsr/r/L/home/thesage/.local/lib/python3.10/site-packages/icalendar/cal/component.py_get_component_factoryms z Component._get_component_factorystrtype[Component]cCs||S)z|Return a component with this name. Parameters: name: Name of the component, i.e. ``VCALENDAR`` )r=get_component_class)r;r.r/r/r<r@tszComponent.get_component_classcomponent_classNonecCsjt|dr |jdurt|d|}||j}|dur.||ur.td|jd|||dS)aRegister a custom component class. Parameters: component_class: Component subclass to register. Must have a ``name`` attribute. Raises: ValueError: If ``component_class`` has no ``name`` attribute. ValueError: If a component with this name is already registered. Examples: Create a custom icalendar component with the name ``X-EXAMPLE``: .. code-block:: pycon >>> from icalendar import Component >>> class XExample(Component): ... name = "X-EXAMPLE" ... def custom_method(self): ... return "custom" >>> Component.register(XExample) r.Nz must have a 'name' attributez Component 'z' is already registered as )hasattrr. ValueErrorr=getadd_component_class)r;rAcomponent_factoryexistingr/r/r<register}s  zComponent.registervalue1date | datetime | timedelta | time | tuple | list str | NonecCs`t|tr!|s dStdd|DrdStdd|DrdSdSt|r'dSt|tr.dSdS)aInfer the ``VALUE`` parameter from a Python type. Parameters: value: Python native type, one of :class:`datetime.date`, :class:`datetime.datetime`, :class:`datetime.timedelta`, :class:`datetime.time`, :class:`tuple`, or :class:`list`. Returns: str or None: The ``VALUE`` parameter string, for example, "DATE", "TIME", or other string, or ``None`` if no specific ``VALUE`` is needed. Ncss|]}t|VqdSNr).0itemr/r/r< sz.Component._infer_value_type..DATEcss|]}t|tVqdSrM) isinstancerrNr/r/r<rQTIME)rSlistallr*rrJr/r/r<_infer_value_types  zComponent._infer_value_typecs"tj|i|g|_g|_dS)z#Set keys to upper for initial dict.N)super__init__r9errors)selfargskwargs __class__r/r<r[s zComponent.__init__cCdS)zAReturns True, CaselessDict would return False if it had no items.Tr/r]r/r/r<__bool__zComponent.__bool__cs t|S)z1Get property value from the component dictionary.)rZ __getitem__)r]keyr`r/r<rfs zComponent.__getitem__cCs"z||WSty|YSw)z Get property value with default.)KeyError)r]rgdefaultr/r/r<rEs   z Component.getcCstt||j S)zDReturns True if Component has no items or subcomponents, else False.)boolrVvaluesr9rcr/r/r<is_emptyszComponent.is_emptyc Cs|s|St||jjr|}n6d}|rd|vr|d}nt||jjs9||}|r9|}|dur1i}d|vr9||d<|j||}||}|rkt|dsOt|_|D]\} } | dure| |jvrd|j| =qS| |j| <qS|S)aEncode values to icalendar property values. :param name: Name of the property. :type name: string :param value: Value of the property. Either of a basic Python type of any of the icalendar's own property types. :type value: Python native type or icalendar property type. :param parameters: Property parameter dictionary for the value. Only available, if encode is set to True. :type parameters: Dictionary :param encode: True, if the value should be encoded to one of icalendar's own property types (Fallback is "vText") or False, if not. :type encode: Boolean :returns: icalendar property value NVALUEparams) rSr6 all_typesrY for_propertyrCrroitems) r;r.rJ parametersencodeobj value_paraminferredklassrgrPr/r/r<_encodes6      zComponent._encodeTrsdict[str, str] | Parametersrtrjcst|trdvrt|}r*t|tr*dvr*fdd|D}n|}vrU}t|trQt|trI||}n |||}n||g}|<dS)aAdd a property. :param name: Name of the property. :type name: string :param value: Value of the property. Either of a basic Python type of any of the icalendar's own property types. :type value: Python native type or icalendar property type. :param parameters: Property parameter dictionary for the value. Only available, if encode is set to True. :type parameters: Dictionary :param encode: True, if the value should be encoded to one of icalendar's own property types (Fallback is "vText") or False, if not. :type encode: Boolean :returns: None )dtstampcreatedz last-modified)rdateexdate categoriescsg|] }|qSr/ryrOvrtr.rsr]r/r< Ez!Component.add..N)rSrlowerr( localize_utcrVryappend)r]r.rJrsrtoldvalr/rr<adds$       z Component.addr$cCsDt|dr|jSt|tr|S|j||}t|tr |t}|S)z&Internal for decoding property values. ical_value) rCrrSr&r6 from_icalr'rtr#)r]r.rJdecodedr/r/r<_decodeWs    zComponent._decoderir csNvr}t|trfdd|DS|S|tur%t|S)zReturns decoded value of property. A component maps keys to icalendar property value types. This function returns values compatible to native Python types. cg|]}|qSr/rrr.r]r/r<rsz%Component.decoded..)rSrVr_markerrh)r]r.rirJr/rr<rjs  zComponent.decodedcs2ddtD}|rfdd|DS|S)z*Returns a list of values (split on comma).cSsg|]}|dqS)z" )striprr/r/r<rsz(Component.get_inline..crr/r)rOvalrr/r<rr)r!)r]r.decodevalsr/rr< get_inline}szComponent.get_inlinecs2|r fdd|D}jdt|<dS)z^Converts a list of values into comma separated string and sets value to that. csg|] }j|ddqS)rm)rtr)rOrJrr/r<rrz(Component.set_inline..inlineN)r6r )r]r.rkrtr/rr< set_inlineszComponent.set_inline componentcCs|j|dS)z%Add a subcomponent to this component.N)r9r)r]rr/r/r< add_componentszComponent.add_componentselectcallable[[Component], bool]cCsRg}|g}|r'|}|dus|j|kr||r|||t|j|s|S)zWalk to given component.N)popr.rextendreversedr9)r]r.rresultstackrr/r/r<_walks zComponent._walkcCrbNTr/)_r/r/r<szComponent.cCs|dur|}|||S)aRecursively traverses component and subcomponents. Returns sequence of same. If name is passed, only components with name will be returned. :param name: The name of the component or None such as ``VEVENT``. :param select: A function that takes the component as first argument and returns True/False. :returns: A list of components that match. :rtype: list[Component] N)upperr)r]r.rr/r/r<walks zComponent.walkuidcs|jfdddS)zReturn a list of components with the given UID. Parameters: uid: The UID of the component. Returns: list[Component]: List of components with the given UID. cs |jkSrMr)crr/r<rs z$Component.with_uid..)r)r)r]rr/rr<with_uids zComponent.with_uid recursivesortedlist[tuple[str, object]]c Csg}|jd}|dfg}|ru|\}}|r#|d||jfnP|d||jf|r5|n|}|D]} || } t| trS| D] } || | fqHq;|| | fq;||df|rst |j D] } || dfqi|s|S)z`Returns properties in this component and subcomponents as: [(name, value), ...] textFENDBEGINT) r6rrr.to_ical sorted_keyskeysrSrVrr9) r]rrrv_textrcompis_endproperty_namesr.rkrJ subcomponentr/r/r<property_itemss,    zComponent.property_itemsst str | bytesLiteral[False]cCdSrMr/r;rr2r/r/r<rszComponent.from_ical Literal[True]cCrrMr/rr/r/r<rrer"cCst|||jS)z/Get the iCal parser for the given input string.)r"r=r6)r;rr/r/r<_get_ical_parserszComponent._get_ical_parserstr | bytes | PathComponent | list[Component]cCst|tr |}n)t|tr3d|vr3d|vr3t|}z|}Wn ty,d}Ynw|r3|}||}|}|r@|St|dkrNt | d|t|dkr\t | d||dS)aParse iCalendar data into component instances. Handles standard and custom components (``X-*``, IANA-registered). Parameters: st: iCalendar data as bytes or string, or a path to an iCalendar file as :class:`pathlib.Path` or string. multiple: If ``True``, returns list. If ``False``, returns single component. Returns: Component or list of components See Also: :doc:`/how-to/custom-components` for examples of parsing custom components   Frmz3Found multiple components where only one is allowedz1Found no components where exactly one is requiredr) rSr read_bytesr>is_fileOSErrorrparselenrD _format_error)r;rr2pathrparser componentsr/r/r<rs8       [...]cCs^d}t|t|t||kr(|t|t|}|d|d|d|S|d|S)Naz:  )r)error_description bad_inputelipsismax_error_length truncate_tor/r/r<r(s zComponent._format_errorcCs t|dt}tj||||dS)z!Returns property as content line.ror)getattrrr from_parts)r]r.rJrror/r/r< content_line1szComponent.content_linecCsDt}|j|dD]\}}|j|||d}||q |d|S)zjoin)r]outrframekindnodesubssubr/r/r<__repr__Hs.    $     zComponent.__repr__csht|jt|jkr dSt|}|sdS|jD] }||jvr#dSq|jD] }||jvr1dSq'dS)NFT)rr9rZ__eq__)r]otherproperties_equalrr`r/r<rus     zComponent.__eq__DTSTAMPa@RFC 5545: Conformance: This property MUST be included in the "VEVENT", "VTODO", "VJOURNAL", or "VFREEBUSY" calendar components. Description: In the case of an iCalendar object that specifies a "METHOD" property, this property specifies the date and time that the instance of the iCalendar object was created. In the case of an iCalendar object that doesn't specify a "METHOD" property, this property specifies the date and time that the information associated with the calendar component was last revised in the calendar store. The value MUST be specified in the UTC time format. In the case of an iCalendar object that doesn't specify a "METHOD" property, this property is equivalent to the "LAST-MODIFIED" property. z LAST-MODIFIEDaRFC 5545: Purpose: This property specifies the date and time that the information associated with the calendar component was last revised in the calendar store. Note: This is analogous to the modification date and time for a file in the file system. Conformance: This property can be specified in the "VEVENT", "VTODO", "VJOURNAL", or "VTIMEZONE" calendar components. rcC |jp|jS)zDatetime when the information associated with the component was last revised. Since :attr:`LAST_MODIFIED` is an optional property, this returns :attr:`DTSTAMP` if :attr:`LAST_MODIFIED` is not set. ) LAST_MODIFIEDrrcr/r/r< last_modified zComponent.last_modifiedcC ||_dSrMrr]rJr/r/r<r cC|`dSrMrrcr/r/r<rcCr)zDatetime when the information associated with the component was created. Since :attr:`CREATED` is an optional property, this returns :attr:`DTSTAMP` if :attr:`CREATED` is not set. )CREATEDrrcr/r/r<r|rzComponent.createdcCrrMrrr/r/r<r|rcCrrMrrcr/r/r<r|rcCstdd|DS)zXWhether this component has attributes that indicate that Mozilla Thunderbird created it.css|]}|dVqdS)zX-MOZ-N) startswith)rOattrr/r/r<rQrTz+Component.is_thunderbird..)anyrrcr/r/r<is_thunderbirdszComponent.is_thunderbirdcCs ttjS)zReturn now as UTC value.)rnowrutcr/r/r/r<_utc_nows zComponent._utc_nowran CREATED specifies the date and time that the calendar information was created by the calendar user agent in the calendar store. Conformance: The property can be specified once in "VEVENT", "VTODO", or "VJOURNAL" calendar components. The value MUST be specified as a date with UTC time. cCs(|dus|dur dS||krtddS)z{This validates start and end. Raises: ~error.InvalidCalendar: If the information is not valid Nzend must be after start)r)startendr/r/r<_validate_start_and_ends z!Component._validate_start_and_endr| date | Nonecommentslist[str] | str | Noneconceptsrrlinksrrefids related_torstampIterable[Component] | Nonec CsZ|} || _|| _|| _|| _|| _|| _|| _|| _| dur+t| t r&| nt | | _ | S)aCreate a new component. Parameters: comments: The :attr:`comments` of the component. concepts: The :attr:`concepts` of the component. created: The :attr:`created` of the component. last_modified: The :attr:`last_modified` of the component. links: The :attr:`links` of the component. related_to: The :attr:`related_to` of the component. stamp: The :attr:`DTSTAMP` of the component. subcomponents: The subcomponents of the component. Raises: ~error.InvalidCalendar: If the content is not valid according to :rfc:`5545`. .. warning:: As time progresses, we will be stricter with the validation. N) rr|rr rrrrrSrVr9) r;r|r rrrrrrr9rr/r/r<news z Component.newrVcCs`g}|D]\}}t|tr|n|gD] }|||qq|j|dd|jDgS)a Convert this component to a jCal object. Returns: jCal object See also :attr:`to_json`. In this example, we create a simple VEVENT component and convert it to jCal: .. code-block:: pycon >>> from icalendar import Event >>> from datetime import date >>> from pprint import pprint >>> event = Event.new(summary="My Event", start=date(2025, 11, 22)) >>> pprint(event.to_jcal()) ['vevent', [['dtstamp', {}, 'date-time', '2025-05-17T08:06:12Z'], ['summary', {}, 'text', 'My Event'], ['uid', {}, 'text', 'd755cef5-2311-46ed-a0e1-6733c9e15c63'], ['dtstart', {}, 'date', '2025-11-22']], []] cSsg|]}|qSr/)to_jcal)rOrr/r/r<rSsz%Component.to_jcal..)rrrSrVrrrr.r9)r] propertiesrgrJrPr/r/r<r4szComponent.to_jcalcCst|S)zReturn this component as a jCal JSON string. Returns: JSON string See also :attr:`to_jcal`. )jsondumpsrrcr/r/r<to_jsonVszComponent.to_jsonjcal str | listc Cst|tr t|}t|trt|dkrtd||d|\}}}t|ts/td|dg|d||jkrB| |}| |S|}t|tsRtd|d|dt |D]H\}}tj ||d|gd |d} |d } |j | | } td| | |} Wd n1swY| |j | kr| `|| | qVt|tstd |d |dt |D]#\}} td ||j| | Wd n1swYq|S) aCreate a component from a jCal list. Parameters: jcal: jCal list or JSON string according to :rfc:`7265`. Raises: ~error.JCalParsingError: If the jCal provided is invalid. ~json.JSONDecodeError: If the provided string is not valid JSON. This reverses :func:`to_json` and :func:`to_jcal`. The following code parses an example from :rfc:`7265`: .. code-block:: pycon >>> from icalendar import Component >>> jcal = ["vcalendar", ... [ ... ["calscale", {}, "text", "GREGORIAN"], ... ["prodid", {}, "text", "-//Example Inc.//Example Calendar//EN"], ... ["version", {}, "text", "2.0"] ... ], ... [ ... ["vevent", ... [ ... ["dtstamp", {}, "date-time", "2008-02-05T19:12:24Z"], ... ["dtstart", {}, "date", "2008-10-06"], ... ["summary", {}, "text", "Planning meeting"], ... ["uid", {}, "text", "4088E990AD89CB3DBB484909"] ... ], ... [] ... ] ... ] ... ] >>> calendar = Component.from_jcal(jcal) >>> print(calendar.name) VCALENDAR >>> print(calendar.prodid) -//Example Inc.//Example Calendar//EN >>> event = calendar.events[0] >>> print(event.summary) Planning meeting z(A component must be a list with 3 items.rXzThe name must be a string.r)rrJzThe properties must be a list.rm)rNz!The subcomponents must be a list.)rSr>rloadsrVrrrr.r@ from_jcal enumeratevalidate_propertyr6rqreraise_with_path_addedrnrr9r)r;rr.rr9 component_clsriprop prop_name prop_valueprop_clsv_proprr/r/r<r`sT .        zComponent.from_jcalr,cs|rt|StS)aCopy the component. Parameters: recursive: If ``True``, this creates copies of the component, its subcomponents, and all its properties. If ``False``, this only creates a shallow copy of the component. Returns: A copy of the component. Examples: Create a shallow copy of a component: .. code-block:: pycon >>> from icalendar import Event >>> event = Event.new(description="Event to be copied") >>> event_copy = event.copy() >>> str(event_copy.description) 'Event to be copied' Shallow copies lose their subcomponents: .. code-block:: pycon >>> from icalendar import Calendar >>> calendar = Calendar.example() >>> len(calendar.subcomponents) 3 >>> calendar_copy = calendar.copy() >>> len(calendar_copy.subcomponents) 0 A recursive copy also copies all the subcomponents: .. code-block:: pycon >>> full_calendar_copy = calendar.copy(recursive=True) >>> len(full_calendar_copy.subcomponents) 3 >>> full_calendar_copy.events[0] == calendar.events[0] True >>> full_calendar_copy.events[0] is calendar.events[0] False )rrZcopy)r]rr`r/r<r*s1 zComponent.copycCrb)zThis component is fully parsed.Fr/rcr/r/r<is_lazyrezComponent.is_lazycCs|S)zReturn the fully parsed component. For non-lazy components, this returns self. For lazy components, this parses the component and returns the result. r/rcr/r/r<rszComponent.parse)r:r)r.r>r:r?)rAr?r:rB)rJrKr:rLrM)Nrmr)r.r>rsrzrtrj)r.r>rJr$)r.r>rir r:r )rm)rr-r:rB)r.rLrrr:r8)rr>r:r8)TT)rrjrrjr:r)F)rrr2rr:r-)rrr2rr:r8)rrr:r")rrr2rjr:r)r)T)rrj)r:r)r:rj) NNNNNNNNN)r|r r r rrrr rrrr rrrr r9rr:r-)r:rV)r:r>)rrr:r-)rrjr:r,)r:r,)Rr __module__ __qualname____doc__r.__annotations__r0r1r2r3r4r5r%instancer6r7 classmethodr=r@rI staticmethodrYr[rdrfrErlryrrrrrrrrrrrrrrrrrrrrrrrrpropertyrsetterdeleterr|rrrrrr rrrrrrrrr _validate_newr rrrrr*r+r __classcell__r/r/r`r<r-/s            %  !   : =     * .     -           0 " X 5r-)?r. __future__rrr*rrrrrrpathlibr typingr r r r ricalendar.attrrrrrrrrrrricalendar.cal.component_factoryricalendar.caselessdictricalendar.errorrricalendar.parserrrrr r!icalendar.parser.ical.componentr"icalendar.parser_toolsr#icalendar.propr$r%r&r'icalendar.timezoner(icalendar.toolsr*collections.abcr+icalendar.compatibilityr,rr-__all__r/r/r/r<s<   0        S