diff --git a/README.rst b/README.rst index 989608b..008e6d9 100644 --- a/README.rst +++ b/README.rst @@ -233,11 +233,11 @@ Skip bad formatted ical events ****************************** Some events may be badly formatted and therefore cannot be handled by recurring-ical-events. -Passing ```skip_bad_events=True``` as ``of()`` argument will totally skip theses events. +Passing ```skip_bad_series=True``` as ``of()`` argument will totally skip theses events. .. code:: Python - of(a_calendar, skip_bad_events=True) + of(a_calendar, skip_bad_series=True) Version Fixing @@ -323,9 +323,36 @@ To release new versions, 6. notify the issues about their release +Architecture +------------ + +.. image:: img/architecture.png + :alt: Architecture Diagram showing the components interacting + +Each icalendar **Calendar** can contain Events, Journal entries, +TODOs and others, called **Components**. +Those entries are grouped by their ``UID``. +Such a ``UID`` defines a **Series** of **Occurrences** that take place at +a given time. +Since each **Component** is different, the **ComponentAdapter** offers a unified +interface to interact with them. +The **Calendar** gets filtered and for each ``UID``, +a **Series** can use one or more **ComponentAdapters** to create +**Occurrences** of what happens in a time span. +These **Occurrences** are used internally and convert to **Components** for further use. + Changelog --------- +- v3.0.0 + + - Change the architecture and add a diagram + - Add type hints, see `Issue 91 `_ + - Rename ``UnfoldableCalendar`` to ``CalendarQuery`` + - Rename ``of(skip_bad_events=None)`` to ``of(skip_bad_series=False)`` + - ``of(components=[...])`` now also takes ``ComponentAdapters`` + - Fix edit sequence problems, see `Issue 151 `_ + - v2.2.3 - Fix: Edits of whole event are now considering RDATE and EXDATE, see `Issue 148 `_ diff --git a/img/architecture.png b/img/architecture.png new file mode 100644 index 0000000..f99732d Binary files /dev/null and b/img/architecture.png differ diff --git a/img/architecture.svg b/img/architecture.svg new file mode 100644 index 0000000..bf8a935 --- /dev/null +++ b/img/architecture.svg @@ -0,0 +1,431 @@ + + + + + + + + + + + + + + Calendar + + + + + CalendarQuery + returned by of(...) + + + + + Component + Event/Journal/Todo + + + has many + filters + + + + + ComponentAdapter + Event-/Journal-/Todo- + + + has 1 + + + + Series + of one UID + + + creates + + has many + + queries + + + Occurrence + e.g. of an event + + + creates + s + + copies and modifies the result + + collectsSeries from + + diff --git a/recurring_ical_events.py b/recurring_ical_events.py index 83690d8..c7fa9f7 100644 --- a/recurring_ical_events.py +++ b/recurring_ical_events.py @@ -910,7 +910,7 @@ def id(self) -> ComponentID: ) -class UnfoldableCalendar: +class CalendarQuery: """A calendar that can unfold its events at a certain time. Functions like at(), between() and after() can be used to query the @@ -1095,11 +1095,11 @@ def after(self, earliest_end) -> Generator[Component]: def of( - a_calendar, + a_calendar : Component, keep_recurrence_attributes=False, components: Sequence[str | type[ComponentAdapter]] = ("VEVENT",), skip_bad_series: bool = False, # noqa: FBT001 -) -> UnfoldableCalendar: +) -> CalendarQuery: """Unfold recurring events of a_calendar - a_calendar is an icalendar VCALENDAR component or something like that. @@ -1109,11 +1109,10 @@ def of( should be returned. """ a_calendar = x_wr_timezone.to_standard(a_calendar) - return UnfoldableCalendar( + return CalendarQuery( a_calendar, keep_recurrence_attributes, components, skip_bad_series ) - __all__ = [ "of", "InvalidCalendar", @@ -1122,6 +1121,9 @@ def of( "is_pytz", "DATE_MIN", "DATE_MAX", - "UnfoldableCalendar", + "CalendarQuery", "ComponentAdapter", + "EventAdapter", + "TodoAdapter", + "JournalAdapter", ] diff --git a/setup.py b/setup.py index eb19054..01b2eb5 100644 --- a/setup.py +++ b/setup.py @@ -12,7 +12,7 @@ HERE = os.path.abspath(os.path.dirname(__file__)) sys.path.insert(0, HERE) # for package import -__version__ = "2.2.3" +__version__ = "3.0.0" __author__ = "Nicco Kunzmann" diff --git a/test/test_time_arguments.py b/test/test_time_arguments.py index 3ee6061..157b9d7 100644 --- a/test/test_time_arguments.py +++ b/test/test_time_arguments.py @@ -8,7 +8,7 @@ import pytest from pytz import utc -from recurring_ical_events import UnfoldableCalendar +from recurring_ical_events import CalendarQuery @pytest.mark.parametrize( @@ -25,4 +25,4 @@ ], ) def test_conversion(input_date, output_datetime): - assert UnfoldableCalendar.to_datetime(input_date) == output_datetime + assert CalendarQuery.to_datetime(input_date) == output_datetime