Canonical RFC links + misc #636
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -528,7 +528,7 @@ class Calendar(DAVObject): | |||||
| """ | ||||||
| The `Calendar` object is used to represent a calendar collection. | ||||||
| Refer to the RFC for details: | ||||||
| https://datatracker.ietf.org/doc/html/rfc4791#section-5.3.1 | ||||||
|
Collaborator
There was a problem hiding this comment. https://caldav.readthedocs.io/latest/caldav/collection.html#caldav.collection.Calendar
Suggested change
|
||||||
| """ | ||||||
|
|
||||||
| def __init__( | ||||||
|
|
||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -103,7 +103,7 @@ class TimeRange(BaseElement): | |
|
|
||
| def __init__(self, start: datetime | None = None, end: datetime | None = None) -> None: | ||
| ## start and end should be an icalendar "date with UTC time", | ||
| ## ref https://datatracker.ietf.org/doc/html/rfc4791#section-9.9 | ||
| super(TimeRange, self).__init__() | ||
|
|
||
| if self.attributes is None: | ||
|
|
||
|
Collaborator
There was a problem hiding this comment. I don't know whether you include this file in the docs. It appears to be a TODO list. If so, then this is good, otherwise let me know and we should use the reStructuredText syntax instead. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -29,7 +29,7 @@ This roadmap covers the **remaining gaps** to achieve full RFC compliance and ad | |
|
|
||
| **Priority:** High | ||
| **Estimated effort:** 40-60 hours | ||
| **RFC:** [RFC 3744](https://datatracker.ietf.org/doc/html/rfc3744) | ||
|
|
||
| Current state: The library has basic principal support but lacks ACL manipulation. | ||
|
|
||
|
|
@@ -50,7 +50,7 @@ Current state: The library has basic principal support but lacks ACL manipulatio | |
|
|
||
| **Priority:** High | ||
| **Estimated effort:** 40 hours (partially covered in #599 for v3.2) | ||
| **RFC:** [RFC 6638](https://datatracker.ietf.org/doc/html/rfc6638) | ||
|
|
||
| The v3.2 roadmap covers basic scheduling improvements. Additional work for full compliance: | ||
|
|
||
|
|
@@ -71,7 +71,7 @@ The v3.2 roadmap covers basic scheduling improvements. Additional work for full | |
|
|
||
| **Priority:** Medium | ||
| **Estimated effort:** 16-24 hours | ||
| **RFC:** [RFC 7953](https://datatracker.ietf.org/doc/html/rfc7953) | ||
| **Related issue:** #425 | ||
|
|
||
| **Tasks:** | ||
|
|
@@ -88,7 +88,7 @@ The v3.2 roadmap covers basic scheduling improvements. Additional work for full | |
|
|
||
| **Priority:** Medium | ||
| **Estimated effort:** 8-12 hours | ||
| **RFC:** [RFC 7986](https://datatracker.ietf.org/doc/html/rfc7986) | ||
|
|
||
| **Tasks:** | ||
| - [ ] Support calendar-level properties: `NAME`, `DESCRIPTION`, `COLOR`, `REFRESH-INTERVAL`, `SOURCE` | ||
|
|
@@ -148,7 +148,7 @@ The v3.2 roadmap covers basic scheduling improvements. Additional work for full | |
|
|
||
| **Priority:** Low | ||
| **Estimated effort:** 24-32 hours | ||
| **RFC:** [RFC 8607](https://datatracker.ietf.org/doc/html/rfc8607) | ||
|
|
||
| **Tasks:** | ||
| - [ ] Detect server support for `calendar-managed-attachments` | ||
|
|
@@ -181,7 +181,7 @@ Note: This is a draft standard but widely implemented by major servers. | |
|
|
||
| **Priority:** Low | ||
| **Estimated effort:** 4-8 hours | ||
| **RFC:** [RFC 5689](https://datatracker.ietf.org/doc/html/rfc5689) | ||
|
|
||
| **Tasks:** | ||
| - [ ] Support extended MKCOL as alternative to MKCALENDAR | ||
|
|
@@ -194,7 +194,7 @@ Note: This is a draft standard but widely implemented by major servers. | |
|
|
||
| **Priority:** Low | ||
| **Estimated effort:** 4-8 hours | ||
| **RFC:** [RFC 4331](https://datatracker.ietf.org/doc/html/rfc4331) | ||
|
|
||
| **Tasks:** | ||
| - [ ] Add `calendar.get_quota()` method | ||
|
|
@@ -270,7 +270,7 @@ Note: This is a draft standard but widely implemented by major servers. | |
| **Priority:** Medium | ||
| **Estimated effort:** 16-24 hours | ||
| **Related issue:** #571 | ||
| **RFC:** [RFC 6764 Section 8](https://datatracker.ietf.org/doc/html/rfc6764#section-8) | ||
|
|
||
| **Tasks:** | ||
| - [ ] Add optional DNSSEC validation for SRV/TXT lookups | ||
|
|
@@ -301,7 +301,7 @@ Note: This is a draft standard but widely implemented by major servers. | |
|
|
||
| **Priority:** Low | ||
| **Estimated effort:** 16-24 hours | ||
| **RFC:** [RFC 7265](https://datatracker.ietf.org/doc/html/rfc7265) | ||
|
|
||
| **Tasks:** | ||
| - [ ] Accept `application/calendar+json` responses | ||
|
|
@@ -314,7 +314,7 @@ Note: This is a draft standard but widely implemented by major servers. | |
|
|
||
| **Priority:** Low | ||
| **Estimated effort:** 16-24 hours | ||
| **RFC:** [RFC 6321](https://datatracker.ietf.org/doc/html/rfc6321) | ||
|
|
||
| **Tasks:** | ||
| - [ ] Accept `application/calendar+xml` responses | ||
|
|
@@ -488,23 +488,23 @@ Based on the roadmap, suggested version milestones after v3.2: | |
| ## References | ||
|
|
||
| ### Core Standards | ||
| - [RFC 4791 - CalDAV](https://datatracker.ietf.org/doc/html/rfc4791) | ||
| - [RFC 6638 - CalDAV Scheduling](https://datatracker.ietf.org/doc/html/rfc6638) | ||
| - [RFC 4918 - WebDAV](https://datatracker.ietf.org/doc/html/rfc4918) | ||
| - [RFC 3744 - WebDAV ACL](https://datatracker.ietf.org/doc/html/rfc3744) | ||
| - [RFC 5545 - iCalendar](https://datatracker.ietf.org/doc/html/rfc5545) | ||
|
|
||
| ### Extensions | ||
| - [RFC 6764 - Service Discovery](https://datatracker.ietf.org/doc/html/rfc6764) | ||
| - [RFC 6578 - WebDAV Sync](https://datatracker.ietf.org/doc/html/rfc6578) | ||
| - [RFC 7953 - Calendar Availability](https://datatracker.ietf.org/doc/html/rfc7953) | ||
| - [RFC 7986 - New iCalendar Properties](https://datatracker.ietf.org/doc/html/rfc7986) | ||
| - [RFC 8607 - Managed Attachments](https://datatracker.ietf.org/doc/html/rfc8607) | ||
|
|
||
| ### Related | ||
| - [RFC 5546 - iTIP](https://datatracker.ietf.org/doc/html/rfc5546) | ||
| - [RFC 6321 - xCal](https://datatracker.ietf.org/doc/html/rfc6321) | ||
| - [RFC 7265 - jCal](https://datatracker.ietf.org/doc/html/rfc7265) | ||
| - [CalConnect Developer Guide](https://devguide.calconnect.org/) | ||
|
|
||
| --- | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -65,40 +65,40 @@ Support for Python2 was officially not supported starting from caldav | |||||
| version 1.0. | ||||||
|
|
||||||
|
|
||||||
| :rfc:`4791`, 2518, 5545, 6638 et al | ||||||
|
Collaborator
There was a problem hiding this comment. I'd just make this heading generic. Also headings should not have links in them.
Suggested change
|
||||||
| ------------------------------------ | ||||||
|
|
||||||
| :rfc:`4791` (CalDAV) outlines the standard way of communicating with a | ||||||
| calendar server. :rfc:`4791` is an extension of :rfc:`4918` (WebDAV). The | ||||||
| scope of this library is basically to cover :rfc:`4791`/:rfc:`4918`, the actual | ||||||
|
Collaborator
There was a problem hiding this comment. I think that the rst link syntax won't work without spaces. Haven't checked. In any case, this is grammatically correct.
Suggested change
|
||||||
| communication with the caldav server. (The WebDAV standard also has | ||||||
| quite some extensions, this library supports some of the relevant | ||||||
| extensions as well). | ||||||
|
|
||||||
| There exists another library webdavclient3 for handling :rfc:`4918` | ||||||
| (WebDAV), ideally we should be depending on it rather than overlap it. | ||||||
|
|
||||||
| :rfc:`6638`/:rfc:`6047` is extending the CalDAV and iCalendar protocols for | ||||||
|
Collaborator
There was a problem hiding this comment.
Suggested change
|
||||||
| scheduling purposes, work is in progress to support :rfc:`6638`. Support | ||||||
| for :rfc:`6047` is considered mostly outside the scope of this library, | ||||||
| though for convenience this library may contain methods like accept() | ||||||
| on a calendar invite (which involves fetching the invite from the | ||||||
| server, editing the calendar data and putting it to the server). | ||||||
|
|
||||||
| This library should make it trivial to fetch an event, modify the data | ||||||
| and save it back to the server - but to do that it's also needed to | ||||||
| support :rfc:`5545` (icalendar). It's outside the scope of this library | ||||||
| to implement logic for parsing and modifying :rfc:`5545`, instead we | ||||||
| depend on another library for that. | ||||||
|
|
||||||
| :rfc:`5545` describes the icalendar format. Constructing or parsing | ||||||
| icalendar data was considered out of the scope of this library, but we | ||||||
| do make exceptions - like, there is a method to complete a task - it | ||||||
| involves editing the icalendar data, and now the ``add_event``, | ||||||
| ``add_todo`` and ``add_journal`` methods are able to construct icalendar | ||||||
| data if needed. | ||||||
|
|
||||||
| There exists two libraries supporting :rfc:`5545`, vobject and icalendar. | ||||||
| vobject was unmaintained for several years, but seems to be actively | ||||||
| maintained now. The caldav library originally came with vobject | ||||||
| support, but as many people requested the vobject dependency to be | ||||||
|
|
@@ -109,7 +109,7 @@ Misbehaving server implementations | |||||
| ---------------------------------- | ||||||
|
|
||||||
| Some server implementations may have some "caldav"-support that either | ||||||
| doesn't implement all of :rfc:`4791`, breaks the standard a bit, or has | ||||||
| extra features. As long as it doesn't add too much complexity to the | ||||||
| code, hacks and workarounds for "badly behaving caldav servers" are | ||||||
| considered to be within the scope. Ideally, users of the caldav | ||||||
|
|
@@ -253,7 +253,7 @@ Server-specific highlights | |||||
| VTODOs must be stored in a calendar explicitly created for the ``VTODO`` | ||||||
| component type. | ||||||
|
|
||||||
| * **Calendar creation** is not mandatory under :rfc:`4791`. Most self-hosted | ||||||
| servers support it; Google's CalDAV adapter does not. | ||||||
|
|
||||||
| * **Recurring events and tasks** are non-trivial to implement correctly on | ||||||
|
|
@@ -263,7 +263,7 @@ Server-specific highlights | |||||
| Some notes on CalDAV URLs | ||||||
| ========================= | ||||||
|
|
||||||
| From v2.1, well-known URLs were hard-coded into the compatibility_hints. As of v2.2, auto-detection based on :rfc:`6764` is supported. This protocol is widely used. For servers supporting it, it's sufficient to add something like "demo2.nextcloud.com" in the URL. For well-known calendar providers, it's not needed to enter anything in the URL, it suffices to put i.e. `features="ecloud"` into the connection parameters. | ||||||
|
|
||||||
| CalDAV URLs can be quite confusing, some software requires the URL to the calendar, other requires the URL to the principal. The Python CalDAV library does support accessing calendars and principals using such URLs, but the recommended practice is to configure up the CalDAV root URL and tell the library to find the principal and calendars from that. Typical examples of CalDAV URLs: | ||||||
|
|
||||||
|
|
||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -57,7 +57,7 @@ The ``caldav.aio`` module exports: | |
| * ``AsyncCalendarSet`` - Collection of calendars | ||
| * ``AsyncPrincipal`` - User principal | ||
|
|
||
| **Scheduling (:rfc:`6638`):** | ||
|
|
||
| * ``AsyncScheduleInbox`` - Incoming invitations | ||
| * ``AsyncScheduleOutbox`` - Outgoing invitations | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,9 +5,9 @@ JMAP | |
| **The JMAP support in v3.0 is experimental, the API may change in v3.1 of the library** | ||
|
|
||
| The caldav library includes a JMAP client for servers that speak | ||
| :rfc:`8620` (JMAP Core) and | ||
| the JMAP Calendars protocol (``urn:ietf:params:jmap:calendars``), which uses | ||
| :rfc:`8984` (JSCalendar) as its data format. | ||
| It covers calendar listing, event CRUD, incremental sync, and task CRUD — the same | ||
| operations as the CalDAV client — so the choice of protocol comes down to what the | ||
| server supports. | ||
|
|
@@ -361,7 +361,7 @@ The three specific error classes: | |
| * :class:`~caldav.jmap.error.JMAPCapabilityError` — the server's Session object | ||
| does not advertise ``urn:ietf:params:jmap:calendars``. | ||
| * :class:`~caldav.jmap.error.JMAPMethodError` — a JMAP method call returned an error | ||
| response. The ``error_type`` attribute holds the :rfc:`8620` error type string | ||
| (e.g. ``"invalidArguments"``, ``"notFound"``, ``"stateMismatch"``). | ||
|
|
||
| Configuration File | ||
|
|
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's make these pretty in the API docs. See https://caldav.readthedocs.io/latest/caldav/calendarobjectresource.html#caldav.calendarobjectresource.CalendarObjectResource.is_invite_request for example.