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

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

2 

3from typing import Any, ClassVar 

4 

5from icalendar.compatibility import Self 

6from icalendar.error import JCalParsingError 

7from icalendar.parser import Parameters 

8from icalendar.parser_tools import DEFAULT_ENCODING, to_unicode 

9 

10 

11class vUri(str): 

12 """URI 

13 

14 Value Name: 

15 URI 

16 

17 Purpose: 

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

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

20 property value. 

21 

22 Format Definition: 

23 This value type is defined by the following notation: 

24 

25 .. code-block:: text 

26 

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

28 

29 Description: 

30 This value type might be used to reference binary 

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

32 to include directly in the iCalendar object. 

33 

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

35 syntax defined in [RFC3986]. 

36 

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

38 be specified as a quoted-string value. 

39 

40 Examples: 

41 The following is a URI for a network file: 

42 

43 .. code-block:: ics 

44 

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

46 

47 .. code-block:: pycon 

48 

49 >>> from icalendar.prop import vUri 

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

51 >>> uri 

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

53 >>> uri.uri 

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

55 """ 

56 

57 default_value: ClassVar[str] = "URI" 

58 params: Parameters 

59 __slots__ = ("params",) 

60 

61 def __new__( 

62 cls, 

63 value: str, 

64 encoding: str = DEFAULT_ENCODING, 

65 /, 

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

67 ) -> Self: 

68 value = to_unicode(value, encoding=encoding) 

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

70 raise ValueError( 

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

72 ) 

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

74 self.params = Parameters(params) 

75 return self 

76 

77 def to_ical(self) -> bytes: 

78 return self.encode(DEFAULT_ENCODING) 

79 

80 @classmethod 

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

82 try: 

83 return cls(ical) 

84 except Exception as e: 

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

86 

87 @classmethod 

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

89 """Examples of vUri.""" 

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

91 

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

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

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

95 

96 @classmethod 

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

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

99 

100 Parameters: 

101 jcal_property: The jCal property to parse. 

102 

103 Raises: 

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

105 """ 

106 JCalParsingError.validate_property(jcal_property, cls) 

107 return cls( 

108 jcal_property[3], 

109 params=Parameters.from_jcal_property(jcal_property), 

110 ) 

111 

112 @property 

113 def ical_value(self) -> str: 

114 """The URI.""" 

115 return self.uri 

116 

117 @property 

118 def uri(self) -> str: 

119 """The URI.""" 

120 return str(self) 

121 

122 def __repr__(self) -> str: 

123 """repr(self)""" 

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

125 

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

127 

128 

129__all__ = ["vUri"]