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

1"""TEXT 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, _escape_char 

8from icalendar.parser_tools import DEFAULT_ENCODING, ICAL_TYPE, to_unicode 

9 

10 

11class vText(str): 

12 r"""vText is a data type that contains human-readable text values. 

13 

14 The vText property uses the :rfc:`5545#section-3.3.11` TEXT value type 

15 in various icalendar properties to show free-form text that others can read. 

16 This class can be created from Python strings, and can be used to add text 

17 descriptions to calendar events. 

18 

19 To create a TEXT object, pass in the string you want when creating the 

20 object. 

21 

22 To add a line break, use ``\n`` or ``\N``. 

23 

24 Use the LANGUAGE property parameter to set the language of the text. 

25 

26 When the TEXT object is serialized to an icalendar stream, certain 

27 characters are escaped or changed. 

28 These characters include the COMMA, SEMICOLON, BACKSLASH, and line breaks. 

29 

30 Examples: 

31 

32 vText property as a TEXT value type. 

33 

34 .. code-block:: text 

35 

36 Project XYZ Final Review\nConference Room - 3B\nCome Prepared. 

37 

38 Create a vText property, and display it in a readable format. 

39 

40 .. code-block:: pycon 

41 

42 >>> from icalendar.prop import vText 

43 >>> desc = 'Project XYZ Final Review\nConference Room - 3B\nCome Prepared.' 

44 >>> text = vText(desc) 

45 >>> text 

46 vText(b'Project XYZ Final Review\\nConference Room - 3B\\nCome Prepared.') 

47 >>> print(text.ical_value) 

48 Project XYZ Final Review 

49 Conference Room - 3B 

50 Come Prepared. 

51 

52 Add a SUMMARY to an event, then display its value as a vText property then in a readable format: 

53 

54 .. code-block:: pycon 

55 

56 >>> from icalendar import Event 

57 >>> event = Event() 

58 >>> event.add('SUMMARY', desc) 

59 >>> event['SUMMARY'] 

60 vText(b'Project XYZ Final Review\\nConference Room - 3B\\nCome Prepared.') 

61 >>> print(event.to_ical().decode()) 

62 BEGIN:VEVENT 

63 SUMMARY:Project XYZ Final Review\nConference Room - 3B\nCome Prepared. 

64 END:VEVENT 

65 

66 """ 

67 

68 default_value: ClassVar[str] = "TEXT" 

69 params: Parameters 

70 __slots__ = ("encoding", "params") 

71 

72 def __new__( 

73 cls, 

74 value: ICAL_TYPE, 

75 encoding: str = DEFAULT_ENCODING, 

76 /, 

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

78 ) -> Self: 

79 value = to_unicode(value, encoding=encoding) 

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

81 self.encoding = encoding 

82 self.params = Parameters(params) 

83 return self 

84 

85 def __repr__(self) -> str: 

86 return f"vText({self.to_ical()!r})" 

87 

88 def to_ical(self) -> bytes: 

89 return _escape_char(self).encode(self.encoding) 

90 

91 @classmethod 

92 def from_ical(cls, ical: ICAL_TYPE) -> Self: 

93 return cls(ical) 

94 

95 @property 

96 def ical_value(self) -> str: 

97 """The string value of the text.""" 

98 return str(self) 

99 

100 from icalendar.param import ALTREP, GAP, LANGUAGE, RELTYPE, VALUE 

101 

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

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

104 if name == "request-status": # TODO: maybe add a vRequestStatus class? 

105 return [name, {}, "text", self.split(";", 2)] 

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

107 

108 @classmethod 

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

110 """Examples of vText.""" 

111 return [cls("Hello World!")] 

112 

113 @classmethod 

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

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

116 

117 Parameters: 

118 jcal_property: The jCal property to parse. 

119 

120 Raises: 

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

122 """ 

123 JCalParsingError.validate_property(jcal_property, cls) 

124 name = jcal_property[0] 

125 if name == "categories": 

126 from icalendar.prop import vCategory 

127 

128 return vCategory.from_jcal(jcal_property) 

129 string = jcal_property[3] # TODO: accept list or string but join with ; 

130 if name == "request-status": # TODO: maybe add a vRequestStatus class? 

131 JCalParsingError.validate_list_type(jcal_property[3], str, cls, 3) 

132 string = ";".join(jcal_property[3]) 

133 JCalParsingError.validate_value_type(string, str, cls, 3) 

134 return cls( 

135 string, 

136 params=Parameters.from_jcal_property(jcal_property), 

137 ) 

138 

139 @classmethod 

140 def parse_jcal_value(cls, jcal_value: Any) -> Self: 

141 """Parse a jCal value into a vText.""" 

142 JCalParsingError.validate_value_type(jcal_value, (str, int, float), cls) 

143 return cls(str(jcal_value)) 

144 

145 

146__all__ = ["vText"]