brushing up examples, documentation, changelog, killing some deprecation warnings from the test code, and covering the basic_usage_examples by the test code

Author: tobixen

CHANGELOG.md

@@ -19,6 +19,10 @@ This project should adhere to [Semantic Versioning](https://semver.org/spec/v2.0
 * `event.component` is now an alias for `event.icalendar_component`.
 * `get_davclient` (earlier called `auto_conn`) is more complete now - it could already read from test config, now it can read from environment (including environment variable for reading from test config and for locating the config file).  While the `auto_conn` itself is tested in the functional tests, the code for reading the config file (and all the corner cases) is not tested.  It's allowable with a yaml config file, but the yaml module is not included in the dependencies yet ... so late imports as for now.  - https://github.com/python-caldav/caldav/pull/502 - https://github.com/python-caldav/caldav/issues/485
 
+### Fixes
+
+* Support for Lark/Feishu got broken in the 1.6-release.  Issue found and fixed by Hongbin Yang (github user @zealseeker) in https://github.com/python-caldav/caldav/issues/505 and https://github.com/python-caldav/caldav/pull/506
+
 ### Changed
 
 * The request library has been in a feature freeze for ages and may seem like a dead end.  There exists a fork of the project niquests, we're migrating to that one.  This means nothing except for one additional dependency.  (httpx was also considered, but it's not a drop-in replacement for the requests library, and it's a risk that such a change will break compatibility with various other servers - see https://github.com/python-caldav/caldav/issues/457 for details).  Work by @ArtemIsmagilov, https://github.com/python-caldav/caldav/pull/455.

docs/source/index.rst

@@ -15,6 +15,7 @@ Contents
    about
    tutorial
    reference
+   examples
 
 ====================
  Indices and tables

docs/source/tutorial.rst

@@ -5,7 +5,9 @@ Tutorial
 In this tutorial you should learn basic usage of the python CalDAV
 client library.  You are encouraged to copy the code examples into a
 file and add a ``breakpoint()`` inside the with-block so you can
-inspect the return objects you get from the library calls.
+inspect the return objects you get from the library calls.  Do not
+name your file `caldav.py` or `calendar.py`, this may break some
+imports.
 
 To follow this tutorial as intended, each code block should be run
 towards a clean-slate Radicale server.  To do this, you need:

examples/basic_usage_examples.py

@@ -8,6 +8,7 @@
 sys.path.insert(0, ".")
 
 import caldav
+from caldav.davclient import get_davclient
 
 ## DO NOT name your file calendar.py or caldav.py!  We've had several
 ## issues filed, things break because the wrong files are imported.
@@ -29,13 +30,10 @@ def run_examples():
     ## The client object stores http session information, username, password, etc.
     ## As of 1.0, Initiating the client object will not cause any server communication,
     ## so the credentials aren't validated.
+    ## get_davclient will try to read credentials and url from environment variables
+    ## and config file.
     ## The client object can be used as a context manager, like this:
-    with caldav.DAVClient(
-        url=caldav_url,
-        username=username,
-        password=password,
-        headers=headers,  # Optional parameter to set HTTP headers on each request if needed
-    ) as client:
+    with get_davclient() as client:
         ## Typically the next step is to fetch a principal object.
         ## This will cause communication with the server.
         my_principal = client.principal()
@@ -132,20 +130,20 @@ def read_modify_event_demo(event):
     ## event.icalendar_instance gives an icalendar instance - which
     ## normally would be one icalendar calendar object containing one
     ## subcomponent.  Quite often the fourth property,
-    ## icalendar_component is preferable - it gives us the component -
-    ## but be aware that if the server returns a recurring events with
-    ## exceptions, event.icalendar_component will ignore all the
-    ## exceptions.
-    uid = event.icalendar_component["uid"]
+    ## icalendar_component (now available just as .component) is
+    ## preferable - it gives us the component - but be aware that if
+    ## the server returns a recurring events with exceptions,
+    ## event.icalendar_component will ignore all the exceptions.
+    uid = event.component["uid"]
 
     ## Let's correct that typo using the icalendar library.
-    event.icalendar_component["summary"] = event.icalendar_component["summary"].replace(
+    event.component["summary"] = event.component["summary"].replace(
         "celebratiuns", "celebrations"
     )
 
     ## timestamps (DTSTAMP, DTSTART, DTEND for events, DUE for tasks,
     ## etc) can be fetched using the icalendar library like this:
-    dtstart = event.icalendar_component.get("dtstart")
+    dtstart = event.component.get("dtstart")
 
     ## but, dtstart is not a python datetime - it's a vDatetime from
     ## the icalendar package.  If you want it as a python datetime,
@@ -156,13 +154,13 @@ def read_modify_event_demo(event):
 
     ## We can modify it:
     if dtstart:
-        event.icalendar_component["dtstart"].dt = dtstart.dt + timedelta(seconds=3600)
+        event.component["dtstart"].dt = dtstart.dt + timedelta(seconds=3600)
 
     ## And finally, get the casing correct
     event.data = event.data.replace("norwegian", "Norwegian")
 
     ## Note that this is not quite thread-safe:
-    icalendar_component = event.icalendar_component
+    icalendar_component = event.component
     ## accessing the data (and setting it) will "disconnect" the
     ## icalendar_component from the event
     event.data = event.data
@@ -184,7 +182,7 @@ def read_modify_event_demo(event):
     calendar = event.parent
     same_event = calendar.event_by_uid(uid)
     assert (
-        same_event.icalendar_component["summary"]
+        same_event.component["summary"]
         == "Norwegian national day celebrations"
     )
 

examples/get_events_example.py

@@ -3,8 +3,9 @@
 
 from caldav.davclient import get_davclient
 
-## Code contributed by Крылов Александр.  Minor changes and quite some
-## comments by Tobias Brox.
+## Code contributed by Крылов Александр.
+## Minor changes by Tobias Brox.
+## All comments by Tobias Brox.
 ## Set CALDAV_USERNAME, CALDAV_URL and CALDAV_PASSWORD through
 ## environment variables before running this example
 
@@ -37,6 +38,9 @@ def fill_event(component, calendar) -> dict[str, str]:
     cur["calendar"] = f"{calendar}"
     cur["summary"] = component.get("summary")
     cur["description"] = component.get("description")
+    ## month/day/year time? Never ever do that!
+    ## It's one of the most confusing date formats ever!
+    ## Use year-month-day time instead ... https://xkcd.com/1179/
     cur["start"] = component.start.strftime("%m/%d/%Y %H:%M")
     endDate = component.end
     if endDate:

examples/scheduling_examples.py

@@ -1,3 +1,7 @@
+## NOTE!  This is currently NOT tested.  It may and may not work.
+## Please reach out if you need help with scheduling ... by https://xkcd.com/1179/
+## or scheduling-help@plann.no
+
 import sys
 import uuid
 from datetime import datetime

examples/sync_examples.py

@@ -3,6 +3,7 @@
 ## similar code in the tests/test_caldav.py file.  Raise a github
 ## issue or reach out by email or write a pull request or send a patch
 ## if there are mistakes in this code) ...
+
 ## USE CASE #1: we'll have a local copy of all calendar contents in a
 ## running python process, and later we'd like to synchronize the
 ## local contents.  (In case of a reboot, all contents will be

tests/test_caldav.py

@@ -1412,15 +1412,15 @@ def testCopyEvent(self):
 
                 ## what will happen with the event in c1 if we modify the event in c2,
                 ## which shares the id with the event in c1?
-                e1_in_c2.instance.vevent.summary.value = "asdf"
+                e1_in_c2.vobject_instance.vevent.summary.value = "asdf"
                 e1_in_c2.save()
                 e1.load()
                 ## should e1.summary be 'asdf' or 'Bastille Day Party'?  I do
                 ## not know, but all implementations I've tested will treat
                 ## the copy in the other calendar as a distinct entity, even
                 ## if the uid is the same.
-                assert e1.instance.vevent.summary.value == "Bastille Day Party"
-                assert c2.events()[0].instance.vevent.uid == e1.instance.vevent.uid
+                assert e1.vobject_instance.vevent.summary.value == "Bastille Day Party"
+                assert c2.events()[0].vobject_instance.vevent.uid == e1.vobject_instance.vevent.uid
 
         ## Duplicate the event in the same calendar, with same uid -
         ## this makes no sense, there won't be any duplication
@@ -1602,17 +1602,17 @@ def testSearchEvent(self):
         ## Even sorting should work out
         all_events = c.search(sort_keys=("summary", "dtstamp"))
         assert len(all_events) == 3
-        assert all_events[0].instance.vevent.summary.value == "Bastille Day Jitsi Party"
+        assert all_events[0].vobject_instance.vevent.summary.value == "Bastille Day Jitsi Party"
 
         ## Sorting by upper case should also wor
         all_events = c.search(sort_keys=("SUMMARY", "DTSTAMP"))
         assert len(all_events) == 3
-        assert all_events[0].instance.vevent.summary.value == "Bastille Day Jitsi Party"
+        assert all_events[0].vobject_instance.vevent.summary.value == "Bastille Day Jitsi Party"
 
         ## Sorting in reverse order should work also
         all_events = c.search(sort_keys=("SUMMARY", "DTSTAMP"), sort_reverse=True)
         assert len(all_events) == 3
-        assert all_events[0].instance.vevent.summary.value == "Our Blissful Anniversary"
+        assert all_events[0].vobject_instance.vevent.summary.value == "Our Blissful Anniversary"
 
         ## A more robust check for the sort key
         all_events = c.search(sort_keys=("DTSTART",))
@@ -2146,7 +2146,7 @@ def testTodos(self):
         assert len(todos) == 3
 
         def uids(lst):
-            return [x.instance.vtodo.uid for x in lst]
+            return [x.vobject_instance.vtodo.uid for x in lst]
 
         ## Default sort order is (due, priority).
         assert uids(todos) == uids([t2, t1, t4])
@@ -2158,9 +2158,9 @@ def uids(lst):
 
         def pri(lst):
             return [
-                x.instance.vtodo.priority.value
+                x.vobject_instance.vtodo.priority.value
                 for x in lst
-                if hasattr(x.instance.vtodo, "priority")
+                if hasattr(x.vobject_instance.vtodo, "priority")
             ]
 
         assert pri(todos) == pri([t4, t2])
@@ -2372,9 +2372,9 @@ def testTodoCompletion(self):
         assert len(todos) == 3
         if not self.check_compatibility_flag("object_by_uid_is_broken"):
             t3_ = c.todo_by_uid(t3.id)
-            assert t3_.instance.vtodo.summary == t3.instance.vtodo.summary
-            assert t3_.instance.vtodo.uid == t3.instance.vtodo.uid
-            assert t3_.instance.vtodo.dtstart == t3.instance.vtodo.dtstart
+            assert t3_.vobject_instance.vtodo.summary == t3.vobject_instance.vtodo.summary
+            assert t3_.vobject_instance.vtodo.uid == t3.vobject_instance.vtodo.uid
+            assert t3_.vobject_instance.vtodo.dtstart == t3.vobject_instance.vtodo.dtstart
 
         t2.delete()
 
@@ -2603,19 +2603,19 @@ def testLookupEvent(self):
         # Verify that we can look it up, both by URL and by ID
         if not self.check_compatibility_flag("event_by_url_is_broken"):
             e2 = c.event_by_url(e1.url)
-            assert e2.instance.vevent.uid == e1.instance.vevent.uid
+            assert e2.vobject_instance.vevent.uid == e1.vobject_instance.vevent.uid
             assert e2.url == e1.url
         if not self.check_compatibility_flag("object_by_uid_is_broken"):
             e3 = c.event_by_uid("20010712T182145Z-123401@example.com")
-            assert e3.instance.vevent.uid == e1.instance.vevent.uid
+            assert e3.vobject_instance.vevent.uid == e1.vobject_instance.vevent.uid
             assert e3.url == e1.url
 
         # Knowing the URL of an event, we should be able to get to it
         # without going through a calendar object
         if not self.check_compatibility_flag("event_by_url_is_broken"):
             e4 = Event(client=self.caldav, url=e1.url)
             e4.load()
-            assert e4.instance.vevent.uid == e1.instance.vevent.uid
+            assert e4.vobject_instance.vevent.uid == e1.vobject_instance.vevent.uid
 
         with pytest.raises(error.NotFoundError):
             c.event_by_uid("0")
@@ -2674,16 +2674,16 @@ def testCreateOverwriteDeleteEvent(self):
                 t2 = c.save_todo(todo, no_create=no_create)
 
             ## this should also work.
-            e2.instance.vevent.summary.value = e2.instance.vevent.summary.value + "!"
+            e2.vobject_instance.vevent.summary.value = e2.vobject_instance.vevent.summary.value + "!"
             e2.save(no_create=no_create)
 
             if todo_ok:
-                t2.instance.vtodo.summary.value = t2.instance.vtodo.summary.value + "!"
+                t2.vobject_instance.vtodo.summary.value = t2.vobject_instance.vtodo.summary.value + "!"
                 t2.save(no_create=no_create)
 
             if not self.check_compatibility_flag("event_by_url_is_broken"):
                 e3 = c.event_by_url(e1.url)
-                assert e3.instance.vevent.summary.value == "Bastille Day Party!"
+                assert e3.vobject_instance.vevent.summary.value == "Bastille Day Party!"
 
         ## "no_overwrite" should throw a ConsistencyError.  But it depends on object_by_uid.
         if not self.check_compatibility_flag("object_by_uid_is_broken"):
@@ -2745,8 +2745,8 @@ def testDateSearchAndFreeBusy(self):
             expand=False,
         )
 
-        assert e.instance.vevent.uid == r1[0].instance.vevent.uid
-        assert e.instance.vevent.uid == r2[0].instance.vevent.uid
+        assert e.vobject_instance.vevent.uid == r1[0].vobject_instance.vevent.uid
+        assert e.vobject_instance.vevent.uid == r2[0].vobject_instance.vevent.uid
         assert len(r1) == 1
         assert len(r2) == 1
 
@@ -2794,7 +2794,7 @@ def testDateSearchAndFreeBusy(self):
         )
         # TODO: assert something more complex on the return object
         assert isinstance(freebusy, FreeBusy)
-        assert freebusy.instance.vfreebusy
+        assert freebusy.vobject_instance.vfreebusy
 
     def testRecurringDateSearch(self):
         """

tests/test_examples.py

@@ -26,3 +26,8 @@ def test_get_events_example(self):
             from examples import get_events_example
 
             get_events_example.fetch_and_print()
+
+    def test_basic_usage_examples(self):
+        from examples import basic_usage_examples
+        basic_usage_examples.run_examples()
+