Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/icalendar/prop/uri.py: 79%

1"""URI values from :rfc:`5545`.""" 

2 

3from typing import Any, ClassVar 

4from xml.etree.ElementTree import Element, SubElement 

5 

6from icalendar.compatibility import Self 

7from icalendar.error import JCalParsingError 

8from icalendar.parser import Parameters 

9from icalendar.parser.xcal.base import XCalParser 

10from icalendar.parser.xcal.string import _to_valid_xml_string 

11from icalendar.parser.xcal.wrapper import from_xcal_wrapper 

12from icalendar.parser_tools import DEFAULT_ENCODING, to_unicode 

13 

14 

15class vUri(str): 

16 """URI 

17 

18 Value Name: 

19 URI 

20 

21 Purpose: 

22 This value type is used to identify values that contain a 

23 uniform resource identifier (URI) type of reference to the 

24 property value. 

25 

26 Format Definition: 

27 This value type is defined by the following notation: 

28 

29 .. code-block:: text 

30 

31 uri = scheme ":" hier-part [ "?" query ] [ "#" fragment ] 

32 

33 Description: 

34 This value type might be used to reference binary 

35 information, for values that are large, or otherwise undesirable 

36 to include directly in the iCalendar object. 

37 

38 Property values with this value type MUST follow the generic URI 

39 syntax defined in [RFC3986]. 

40 

41 When a property parameter value is a URI value type, the URI MUST 

42 be specified as a quoted-string value. 

43 

44 Examples: 

45 The following is a URI for a network file: 

46 

47 .. code-block:: ics 

48 

49 http://example.com/my-report.txt 

50 

51 .. code-block:: pycon 

52 

53 >>> from icalendar.prop import vUri 

54 >>> uri = vUri.from_ical('http://example.com/my-report.txt') 

55 >>> uri 

56 vUri('http://example.com/my-report.txt') 

57 >>> uri.uri 

58 'http://example.com/my-report.txt' 

59 """ 

60 

61 default_value: ClassVar[str] = "URI" 

62 params: Parameters 

63 __slots__ = ("params",) 

64 

65 def __new__( 

66 cls, 

67 value: str, 

68 encoding: str = DEFAULT_ENCODING, 

69 /, 

70 params: dict[str, Any] | None = None, 

71 ) -> Self: 

72 value = to_unicode(value, encoding=encoding) 

73 if "\r" in value or "\n" in value: 

74 raise ValueError( 

75 f"A URI value may not contain CR or LF characters: {value!r}" 

76 ) 

77 self = super().__new__(cls, value) 

78 self.params = Parameters(params) 

79 return self 

80 

81 def to_ical(self) -> bytes: 

82 return self.encode(DEFAULT_ENCODING) 

83 

84 @classmethod 

85 def from_ical(cls, ical: str | bytes) -> Self: 

86 try: 

87 return cls(ical) 

88 except Exception as e: 

89 raise ValueError(f"Expected , got: {ical}") from e 

90 

91 @classmethod 

92 def examples(cls) -> list[Self]: 

93 """Examples of vUri.""" 

94 return [cls("http://example.com/my-report.txt")] 

95 

96 def to_jcal(self, name: str) -> list: 

97 """The jCal representation of this property according to :rfc:`7265`.""" 

98 return [name, self.params.to_jcal(), self.VALUE.lower(), str(self)] 

99 

100 @classmethod 

101 def from_jcal(cls, jcal_property: list) -> Self: 

102 """Parse jCal from :rfc:`7265`. 

103 

104 Parameters: 

105 jcal_property: The jCal property to parse. 

106 

107 Raises: 

108 ~error.JCalParsingError: If the provided jCal is invalid. 

109 """ 

110 JCalParsingError.validate_property(jcal_property, cls) 

111 return cls( 

112 jcal_property[3], 

113 params=Parameters.from_jcal_property(jcal_property), 

114 ) 

115 

116 @property 

117 def ical_value(self) -> str: 

118 """The URI.""" 

119 return self.uri 

120 

121 @property 

122 def uri(self) -> str: 

123 """The URI.""" 

124 return str(self) 

125 

126 def __repr__(self) -> str: 

127 """repr(self)""" 

128 return f"{self.__class__.__name__}({self.uri!r})" 

129 

130 from icalendar.param import FMTTYPE, GAP, LABEL, LANGUAGE, LINKREL, RELTYPE, VALUE 

131 

132 def to_xcal(self, element: Element) -> None: 

133 """Add the xCal representation of this property according to :rfc:`6321`.""" 

134 self.params.to_xcal(element) 

135 element = SubElement(element, self.default_value.lower()) 

136 element.text = _to_valid_xml_string(self) 

137 

138 @classmethod 

139 @from_xcal_wrapper 

140 def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: 

141 """Parse xCal from :rfc:`6321`. 

142 

143 Parameters: 

144 xml: The XML to parse or a parser. 

145 

146 Raises: 

147 ~error.XCalParsingError: If the provided xCal is invalid. 

148 """ 

149 element = parser.parse_tag(cls.default_value) 

150 return cls(element.get_xsd_string(), params=params) 

151 

152 

153__all__ = ["vUri"]