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

1"""The ORG property from :rfc:`6350`.""" 

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

12 r"""vCard ORG (Organization) structured property per :rfc:`6350#section-6.6.4`. 

13 

14 The ORG property specifies the organizational name and units 

15 associated with the vCard. 

16 

17 Its value is a structured type consisting of components separated 

18 by semicolons. The components are the organization name, followed 

19 by zero or more levels of organizational unit names. 

20 

21 .. code-block:: text 

22 

23 organization-name; organizational-unit-1; organizational-unit-2; ... 

24 

25 Semicolons are field separators and are NOT escaped. 

26 Commas and backslashes within field values ARE escaped per :rfc:`6350`. 

27 

28 Examples: 

29 A property value consisting of an organizational name, 

30 organizational unit #1 name, and organizational unit #2 name. 

31 

32 .. code-block:: ics 

33 

34 ORG:ABC\, Inc.;North American Division;Marketing 

35 

36 The same example in icalendar. 

37 

38 .. code-block:: pycon 

39 

40 >>> from icalendar.prop import vOrg 

41 >>> org = vOrg(("ABC, Inc.", "North American Division", "Marketing")) 

42 >>> org.to_ical() 

43 b'ABC\\, Inc.;North American Division;Marketing' 

44 >>> vOrg.from_ical(r"ABC\, Inc.;North American Division;Marketing") 

45 ('ABC, Inc.', 'North American Division', 'Marketing') 

46 """ 

47 

48 default_value: ClassVar[str] = "TEXT" 

49 params: Parameters 

50 fields: tuple[str, ...] 

51 

52 def __init__( 

53 self, 

54 fields: tuple[str, ...] | list[str] | str, 

55 /, 

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

57 ) -> None: 

58 """Initialize ORG with variable fields or parse from vCard format string. 

59 

60 Parameters: 

61 fields: Either a tuple or list of one or more strings, or a 

62 vCard format string with semicolon-separated fields 

63 params: Optional property parameters 

64 """ 

65 if isinstance(fields, str): 

66 fields = self.from_ical(fields) 

67 if len(fields) < 1: 

68 raise ValueError("ORG must have at least 1 field (organization name)") 

69 self.fields = tuple(str(f) for f in fields) 

70 self.params = Parameters(params) 

71 

72 def to_ical(self) -> bytes: 

73 """Generate vCard format with semicolon-separated fields.""" 

74 from icalendar.prop.text import vText 

75 

76 parts = [vText(f).to_ical().decode(DEFAULT_ENCODING) for f in self.fields] 

77 return ";".join(parts).encode(DEFAULT_ENCODING) 

78 

79 @staticmethod 

80 def from_ical(ical: str | bytes) -> tuple[str, ...]: 

81 """Parse vCard ORG format into a tuple of fields. 

82 

83 Parameters: 

84 ical: vCard format string with semicolon-separated fields 

85 

86 Returns: 

87 Tuple of field values with one or more fields 

88 """ 

89 from icalendar.parser import split_on_unescaped_semicolon 

90 

91 ical = to_unicode(ical) 

92 fields = split_on_unescaped_semicolon(ical) 

93 return tuple(fields) 

94 

95 def __eq__(self, other: object) -> bool: 

96 """self == other""" 

97 return isinstance(other, vOrg) and self.fields == other.fields 

98 

99 def __repr__(self) -> str: 

100 """String representation.""" 

101 return f"{self.__class__.__name__}({self.fields}, params={self.params})" 

102 

103 @property 

104 def name(self) -> str: 

105 """The organization name (first field).""" 

106 return self.fields[0] 

107 

108 @property 

109 def units(self) -> tuple[str, ...]: 

110 """The organizational unit names (remaining fields after the name).""" 

111 return self.fields[1:] 

112 

113 @property 

114 def ical_value(self) -> tuple[str, ...]: 

115 """The organization fields as a tuple.""" 

116 return self.fields 

117 

118 from icalendar.param import VALUE 

119 

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

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

122 result = [name, self.params.to_jcal(), self.VALUE.lower()] 

123 result.extend(self.fields) 

124 return result 

125 

126 @classmethod 

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

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

129 

130 Parameters: 

131 jcal_property: The jCal property to parse. 

132 

133 Raises: 

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

135 """ 

136 JCalParsingError.validate_property(jcal_property, cls) 

137 for i, field in enumerate(jcal_property[3:], start=3): 

138 JCalParsingError.validate_value_type(field, str, cls, i) 

139 return cls( 

140 tuple(jcal_property[3:]), 

141 Parameters.from_jcal_property(jcal_property), 

142 ) 

143 

144 @classmethod 

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

146 """Examples of vOrg.""" 

147 return [cls(("ABC Inc.", "North American Division", "Marketing"))] 

148 

149 

150__all__ = ["vOrg"]