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 

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:: text 

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 self = super().__new__(cls, value) 

70 self.params = Parameters(params) 

71 return self 

72 

73 def to_ical(self) -> bytes: 

74 return self.encode(DEFAULT_ENCODING) 

75 

76 @classmethod 

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

78 try: 

79 return cls(ical) 

80 except Exception as e: 

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

82 

83 @classmethod 

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

85 """Examples of vUri.""" 

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

87 

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

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

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

91 

92 @classmethod 

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

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

95 

96 Parameters: 

97 jcal_property: The jCal property to parse. 

98 

99 Raises: 

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

101 """ 

102 JCalParsingError.validate_property(jcal_property, cls) 

103 return cls( 

104 jcal_property[3], 

105 Parameters.from_jcal_property(jcal_property), 

106 ) 

107 

108 @property 

109 def ical_value(self) -> str: 

110 """The URI.""" 

111 return self.uri 

112 

113 @property 

114 def uri(self) -> str: 

115 """The URI.""" 

116 return str(self) 

117 

118 def __repr__(self) -> str: 

119 """repr(self)""" 

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

121 

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

123 

124 

125__all__ = ["vUri"]