=============
How-To Guides
=============

Editing Calendar Data
---------------------

Calendar objects (events, todos, journals) can be accessed and modified
using the icalendar or vobject libraries.

Reading Data
~~~~~~~~~~~~

For read-only access, use methods that return copies:

.. code-block:: python

    # Get raw iCalendar string
    data = event.get_data()

    # Get icalendar object (a copy - safe to inspect)
    ical = event.get_icalendar_instance()
    for comp in ical.subcomponents:
        print(comp.get("SUMMARY"))

    # Get vobject object (a copy)
    vobj = event.get_vobject_instance()

Modifying Data
~~~~~~~~~~~~~~

To edit an object, use context managers that "borrow" the object:

.. code-block:: python

    # Edit using icalendar
    with event.edit_icalendar_instance() as cal:
        for comp in cal.subcomponents:
            if comp.name == "VEVENT":
                comp["SUMMARY"] = "New summary"
    event.save()

    # Edit using vobject
    with event.edit_vobject_instance() as vobj:
        vobj.vevent.summary.value = "New summary"
    event.save()

While inside the ``with`` block, the object is exclusively borrowed.
Attempting to borrow a different representation will raise ``RuntimeError``.

Quick Access
~~~~~~~~~~~~

For simple read access, use the ``component`` property:

.. code-block:: python

    # Read properties
    summary = event.component["SUMMARY"]
    start = event.component.start

Backing Up a Calendar
---------------------

Use :func:`caldav.get_calendar` (available since v2.0) to fetch all objects
from a specific calendar and write them to disk:

.. code-block:: python

    import pathlib
    from caldav import get_calendar

    backup_dir = pathlib.Path("backup")
    backup_dir.mkdir(exist_ok=True)

    with get_calendar(calendar_name="Work") as cal:
        for obj in cal.search():
            uid = obj.icalendar_instance.subcomponents[0]["UID"]
            (backup_dir / f"{uid}.ics").write_text(obj.data)

To restore, iterate over the saved ``.ics`` files and call ``cal.add_event()``
(or ``add_todo()``/``add_journal()`` as appropriate).

For more on server-specific connection details and known incompatibilities,
see :ref:`about:Compatibility` and :ref:`about:Some notes on CalDAV URLs`.