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

1"""Parameter access for icalendar. 

2 

3Related: 

4 

5- :rfc:`5545`, Section 3.2. Property Parameters 

6- :rfc:`7986`, Section 6. Property Parameters 

7- https://github.com/collective/icalendar/issues/798 

8""" 

9 

10from __future__ import annotations 

11 

12import functools 

13from typing import TYPE_CHECKING, Callable, Optional, TypeVar 

14 

15from icalendar import enums 

16 

17if TYPE_CHECKING: 

18 from enum import Enum 

19 

20 from icalendar.parser import Parameters 

21 

22 

23class IcalendarProperty: 

24 """Interface provided by properties in icalendar.prop.""" 

25 

26 params: Parameters 

27 

28 

29def _default_return_none() -> Optional[str]: 

30 """Return None by default.""" 

31 return None 

32 

33 

34def _default_return_string() -> str: 

35 """Return None by default.""" 

36 return "" 

37 

38 

39T = TypeVar("T") 

40 

41 

42def string_parameter( 

43 name: str, 

44 doc: str, 

45 default: Callable = _default_return_none, 

46 convert: Optional[Callable[[str], T]] = None, 

47 convert_to: Optional[Callable[[T], str]] = None, 

48) -> property: 

49 """Return a parameter with a quoted value (case sensitive).""" 

50 

51 if convert_to is None: 

52 convert_to = convert 

53 

54 @functools.wraps(default) 

55 def fget(self: IcalendarProperty) -> Optional[str]: 

56 value = self.params.get(name) 

57 if value is None: 

58 return default() 

59 return convert(value) if convert else value 

60 

61 def fset(self: IcalendarProperty, value: str): 

62 self.params[name] = convert_to(value) if convert_to else value 

63 

64 def fdel(self: IcalendarProperty): 

65 self.params.pop(name, None) 

66 

67 return property(fget, fset, fdel, doc=doc) 

68 

69 

70ALTREP = string_parameter( 

71 "ALTREP", 

72 """ALTREP - Specify an alternate text representation for the property value. 

73 

74Description: 

75 This parameter specifies a URI that points to an 

76 alternate representation for a textual property value. A property 

77 specifying this parameter MUST also include a value that reflects 

78 the default representation of the text value. The URI parameter 

79 value MUST be specified in a quoted-string. 

80 

81.. note:: 

82 

83 While there is no restriction imposed on the URI schemes 

84 allowed for this parameter, Content Identifier (CID) :rfc:`2392`, 

85 HTTP :rfc:`2616`, and HTTPS :rfc:`2818` are the URI schemes most 

86 commonly used by current implementations. 

87""", 

88) 

89 

90CN = string_parameter( 

91 "CN", 

92 """Specify the common name to be associated with the calendar user specified. 

93 

94Description: 

95 This parameter can be specified on properties with a 

96 CAL-ADDRESS value type. The parameter specifies the common name 

97 to be associated with the calendar user specified by the property. 

98 The parameter value is text. The parameter value can be used for 

99 display text to be associated with the calendar address specified 

100 by the property. 

101""", 

102 default=_default_return_string, 

103) 

104 

105 

106def _default_return_individual() -> enums.CUTYPE | str: 

107 """Default value.""" 

108 return enums.CUTYPE.INDIVIDUAL 

109 

110 

111def _convert_enum(enum: type[Enum]) -> Callable[[str], Enum]: 

112 def convert(value: str) -> str: 

113 """Convert if possible.""" 

114 try: 

115 return enum(value.upper()) 

116 except ValueError: 

117 return value 

118 

119 return convert 

120 

121 

122CUTYPE = string_parameter( 

123 "CUTYPE", 

124 """Identify the type of calendar user specified by the property. 

125 

126Description: 

127 This parameter can be specified on properties with a 

128 CAL-ADDRESS value type. The parameter identifies the type of 

129 calendar user specified by the property. If not specified on a 

130 property that allows this parameter, the default is INDIVIDUAL. 

131 Applications MUST treat x-name and iana-token values they don't 

132 recognize the same way as they would the UNKNOWN value. 

133""", 

134 default=_default_return_individual, 

135 convert=_convert_enum(enums.CUTYPE), 

136) 

137 

138 

139def quoted_list_parameter(name: str, doc: str) -> property: 

140 """Return a parameter that contains a quoted list.""" 

141 

142 def fget(self: IcalendarProperty) -> tuple[str]: 

143 value = self.params.get(name) 

144 if value is None: 

145 return () 

146 if isinstance(value, str): 

147 return tuple(value.split(",")) 

148 return value 

149 

150 def fset(self: IcalendarProperty, value: str | tuple[str]): 

151 if value == (): 

152 fdel(self) 

153 else: 

154 self.params[name] = (value,) if isinstance(value, str) else value 

155 

156 def fdel(self: IcalendarProperty): 

157 self.params.pop(name, None) 

158 

159 return property(fget, fset, fdel, doc=doc) 

160 

161 

162DELEGATED_FROM = quoted_list_parameter( 

163 "DELEGATED-FROM", 

164 """Specify the calendar users that have delegated their participation to the calendar user specified by the property. 

165 

166Description: 

167 This parameter can be specified on properties with a 

168 CAL-ADDRESS value type. This parameter specifies those calendar 

169 users that have delegated their participation in a group-scheduled 

170 event or to-do to the calendar user specified by the property. 

171 The individual calendar address parameter values MUST each be 

172 specified in a quoted-string. 

173""", # noqa: E501 

174) 

175 

176DELEGATED_TO = quoted_list_parameter( 

177 "DELEGATED-TO", 

178 """Specify the calendar users to whom the calendar user specified by the property has delegated participation. 

179 

180Description: 

181 This parameter can be specified on properties with a 

182 CAL-ADDRESS value type. This parameter specifies those calendar 

183 users whom have been delegated participation in a group-scheduled 

184 event or to-do by the calendar user specified by the property. 

185 The individual calendar address parameter values MUST each be 

186 specified in a quoted-string. 

187 """, # noqa: E501 

188) 

189 

190DIR = string_parameter( 

191 "DIR", 

192 """Specify reference to a directory entry associated with the calendar user specified by the property. 

193 

194Description: 

195 This parameter can be specified on properties with a 

196 CAL-ADDRESS value type. The parameter specifies a reference to 

197 the directory entry associated with the calendar user specified by 

198 the property. The parameter value is a URI. The URI parameter 

199 value MUST be specified in a quoted-string. 

200 

201.. note:: 

202 

203 While there is no restriction imposed on the URI schemes 

204 allowed for this parameter, CID :rfc:`2392`, DATA :rfc:`2397`, FILE 

205 :rfc:`1738`, FTP :rfc:`1738`, HTTP :rfc:`2616`, HTTPS :rfc:`2818`, LDAP 

206 :rfc:`4516`, and MID :rfc:`2392` are the URI schemes most commonly 

207 used by current implementations. 

208""", # noqa: E501 

209) 

210 

211 

212def _default_return_busy() -> enums.FBTYPE | str: 

213 """Default value.""" 

214 return enums.FBTYPE.BUSY 

215 

216 

217FBTYPE = string_parameter( 

218 "FBTYPE", 

219 """Specify the free or busy time type. 

220 

221Description: 

222 This parameter specifies the free or busy time type. 

223 The value FREE indicates that the time interval is free for 

224 scheduling. The value BUSY indicates that the time interval is 

225 busy because one or more events have been scheduled for that 

226 interval. The value BUSY-UNAVAILABLE indicates that the time 

227 interval is busy and that the interval can not be scheduled. The 

228 value BUSY-TENTATIVE indicates that the time interval is busy 

229 because one or more events have been tentatively scheduled for 

230 that interval. If not specified on a property that allows this 

231 parameter, the default is BUSY. Applications MUST treat x-name 

232 and iana-token values they don't recognize the same way as they 

233 would the BUSY value. 

234""", 

235 default=_default_return_busy, 

236 convert=_convert_enum(enums.FBTYPE), 

237) 

238 

239LANGUAGE = string_parameter( 

240 "LANGUAGE", 

241 """Specify the language for text values in a property or property parameter. 

242 

243Description: 

244 This parameter identifies the language of the text in 

245 the property value and of all property parameter values of the 

246 property. The value of the "LANGUAGE" property parameter is that 

247 defined in :rfc:`5646`. 

248 

249 For transport in a MIME entity, the Content-Language header field 

250 can be used to set the default language for the entire body part. 

251 Otherwise, no default language is assumed. 

252""", 

253) 

254 

255MEMBER = quoted_list_parameter( 

256 "MEMBER", 

257 """Specify the group or list membership of the calendar user specified by the property. 

258 

259Description: 

260 This parameter can be specified on properties with a 

261 CAL-ADDRESS value type. The parameter identifies the groups or 

262 list membership for the calendar user specified by the property. 

263 The parameter value is either a single calendar address in a 

264 quoted-string or a COMMA-separated list of calendar addresses, 

265 each in a quoted-string. The individual calendar address 

266 parameter values MUST each be specified in a quoted-string. 

267""", # noqa: E501 

268) 

269 

270 

271def _default_return_needs_action() -> enums.PARTSTAT | str: 

272 """Default value.""" 

273 return enums.PARTSTAT.NEEDS_ACTION 

274 

275 

276PARTSTAT = string_parameter( 

277 "PARTSTAT", 

278 """Specify the participation status for the calendar user specified by the property. 

279 

280Description: 

281 This parameter can be specified on properties with a 

282 CAL-ADDRESS value type. The parameter identifies the 

283 participation status for the calendar user specified by the 

284 property value. The parameter values differ depending on whether 

285 they are associated with a group-scheduled "VEVENT", "VTODO", or 

286 "VJOURNAL". The values MUST match one of the values allowed for 

287 the given calendar component. If not specified on a property that 

288 allows this parameter, the default value is NEEDS-ACTION. 

289 Applications MUST treat x-name and iana-token values they don't 

290 recognize the same way as they would the NEEDS-ACTION value. 

291""", 

292 default=_default_return_needs_action, 

293 convert=_convert_enum(enums.PARTSTAT), 

294) 

295 

296 

297def _default_range_none() -> Optional[enums.RANGE | str]: 

298 return None 

299 

300 

301RANGE = string_parameter( 

302 "RANGE", 

303 """Specify the effective range of recurrence instances from the instance specified by the recurrence identifier specified by the property. 

304 

305Description: 

306 This parameter can be specified on a property that 

307 specifies a recurrence identifier. The parameter specifies the 

308 effective range of recurrence instances that is specified by the 

309 property. The effective range is from the recurrence identifier 

310 specified by the property. If this parameter is not specified on 

311 an allowed property, then the default range is the single instance 

312 specified by the recurrence identifier value of the property. The 

313 parameter value can only be "THISANDFUTURE" to indicate a range 

314 defined by the recurrence identifier and all subsequent instances. 

315 The value "THISANDPRIOR" is deprecated by this revision of 

316 iCalendar and MUST NOT be generated by applications. 

317""", # noqa: E501 

318 default=_default_range_none, 

319 convert=_convert_enum(enums.RANGE), 

320) 

321 

322 

323def _default_related() -> enums.RELATED | str: 

324 return enums.RELATED.START 

325 

326 

327RELATED = string_parameter( 

328 "RELATED", 

329 """Specify the relationship of the alarm trigger with respect to the start or end of the calendar component. 

330 

331Description: 

332 This parameter can be specified on properties that 

333 specify an alarm trigger with a "DURATION" value type. The 

334 parameter specifies whether the alarm will trigger relative to the 

335 start or end of the calendar component. The parameter value START 

336 will set the alarm to trigger off the start of the calendar 

337 component; the parameter value END will set the alarm to trigger 

338 off the end of the calendar component. If the parameter is not 

339 specified on an allowable property, then the default is START. 

340 

341""", # noqa: E501 

342 default=_default_related, 

343 convert=_convert_enum(enums.RANGE), 

344) 

345 

346 

347def _default_req_participant() -> enums.ROLE | str: 

348 return enums.ROLE.REQ_PARTICIPANT 

349 

350 

351ROLE = string_parameter( 

352 "ROLE", 

353 """Specify the participation role for the calendar user specified by the property. 

354 

355Description: 

356 This parameter can be specified on properties with a 

357 CAL-ADDRESS value type. The parameter specifies the participation 

358 role for the calendar user specified by the property in the group 

359 schedule calendar component. If not specified on a property that 

360 allows this parameter, the default value is REQ-PARTICIPANT. 

361 Applications MUST treat x-name and iana-token values they don't 

362 recognize the same way as they would the REQ-PARTICIPANT value. 

363""", 

364 default=_default_req_participant, 

365 convert=_convert_enum(enums.ROLE), 

366) 

367 

368 

369def boolean_parameter(name: str, default: bool, doc: str) -> property: # noqa: FBT001 

370 def _default() -> bool: 

371 return default 

372 

373 return string_parameter( 

374 name, 

375 doc, 

376 default=_default, 

377 convert=lambda x: x.upper() == "TRUE", 

378 convert_to=lambda x: "TRUE" if x else "FALSE", 

379 ) 

380 

381 

382RSVP = boolean_parameter( 

383 "RSVP", 

384 False, # noqa: FBT003 

385 """Specify whether there is an expectation of a favor of anreply from the calendar user specified by the property value. 

386 

387Description: 

388 This parameter can be specified on properties with a 

389 CAL-ADDRESS value type. The parameter identifies the expectation 

390 of a reply from the calendar user specified by the property value. 

391 This parameter is used by the "Organizer" to request a 

392 participation status reply from an "Attendee" of a group-scheduled 

393 event or to-do. If not specified on a property that allows this 

394 parameter, the default value is ``False``. 

395""", # noqa: E501 

396) 

397 

398SENT_BY = string_parameter( 

399 "SENT-BY", 

400 """Specify the calendar user that is acting on behalf of the calendar user specified by the property. 

401 

402Description: 

403 This parameter can be specified on properties with a 

404 CAL-ADDRESS value type. The parameter specifies the calendar user 

405 that is acting on behalf of the calendar user specified by the 

406 property. The parameter value MUST be a mailto URI as defined in 

407 :rfc:`2368`. The individual calendar address parameter values MUST 

408 each be specified in a quoted-string. 

409""", # noqa: E501 

410) 

411 

412TZID = string_parameter( 

413 "TZID", 

414 """Specify the identifier for the time zone definition for a time component in the property value. 

415 

416Description: 

417 This parameter MUST be specified on the "DTSTART", 

418 "DTEND", "DUE", "EXDATE", and "RDATE" properties when either a 

419 DATE-TIME or TIME value type is specified and when the value is 

420 neither a UTC or a "floating" time. Refer to the DATE-TIME or 

421 TIME value type definition for a description of UTC and "floating 

422 time" formats. This property parameter specifies a text value 

423 that uniquely identifies the "VTIMEZONE" calendar component to be 

424 used when evaluating the time portion of the property. The value 

425 of the "TZID" property parameter will be equal to the value of the 

426 "TZID" property for the matching time zone definition. An 

427 individual "VTIMEZONE" calendar component MUST be specified for 

428 each unique "TZID" parameter value specified in the iCalendar 

429 object. 

430 

431 The parameter MUST be specified on properties with a DATE-TIME 

432 value if the DATE-TIME is not either a UTC or a "floating" time. 

433 Failure to include and follow VTIMEZONE definitions in iCalendar 

434 objects may lead to inconsistent understanding of the local time 

435 at any given location. 

436 

437 The presence of the SOLIDUS character as a prefix, indicates that 

438 this "TZID" represents a unique ID in a globally defined time zone 

439 registry (when such registry is defined). 

440 

441.. note:: 

442 

443 This document does not define a naming convention for 

444 time zone identifiers. Implementers may want to use the naming 

445 conventions defined in existing time zone specifications such 

446 as the public-domain TZ database (TZDB). The specification of 

447 globally unique time zone identifiers is not addressed by this 

448 document and is left for future study. 

449""", # noqa: E501 

450) 

451 

452 

453def _default_return_parent() -> enums.RELTYPE: 

454 return enums.RELTYPE.PARENT 

455 

456 

457RELTYPE = string_parameter( 

458 "RELTYPE", 

459 """Specify the type of hierarchical relationship associated with a component. 

460 

461Description: 

462 This parameter can be specified on a property that 

463 references another related calendar. The parameter specifies the 

464 hierarchical relationship type of the calendar component 

465 referenced by the property. The parameter value can be PARENT, to 

466 indicate that the referenced calendar component is a superior of 

467 calendar component; CHILD to indicate that the referenced calendar 

468 component is a subordinate of the calendar component; or SIBLING 

469 to indicate that the referenced calendar component is a peer of 

470 the calendar component. If this parameter is not specified on an 

471 allowable property, the default relationship type is PARENT. 

472 Applications MUST treat x-name and iana-token values they don't 

473 recognize the same way as they would the PARENT value. 

474""", 

475 default=_default_return_parent, 

476 convert=_convert_enum(enums.RELTYPE), 

477) 

478 

479__all__ = [ 

480 "ALTREP", 

481 "CN", 

482 "CUTYPE", 

483 "DELEGATED_FROM", 

484 "DELEGATED_TO", 

485 "DIR", 

486 "FBTYPE", 

487 "LANGUAGE", 

488 "MEMBER", 

489 "PARTSTAT", 

490 "RANGE", 

491 "RELATED", 

492 "ROLE", 

493 "RSVP", 

494 "SENT_BY", 

495 "TZID", 

496 "quoted_list_parameter", 

497 "string_parameter", 

498]