feat: add @date_iterator decorator

README.md

@@ -1,12 +1,14 @@
 # annual
 [![PyPI - Version](https://img.shields.io/pypi/v/annual?logo=pypi)](https://pypi.org/project/nnual)
 ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/tom65536/annual/ci.yml?logo=github)
-[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8996/badge)](https://www.bestpractices.dev/projects/8996)
+[![Documentation Status](https://readthedocs.org/projects/annual/badge/?version=latest)](https://annual.readthedocs.io/latest/?badge=latest)
+[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/075ffea9b1b8406d95b090e3a56a3313)](https://app.codacy.com/gh/tom65536/annual/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/075ffea9b1b8406d95b090e3a56a3313)](https://app.codacy.com/gh/tom65536/annual/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
 [![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
-[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/075ffea9b1b8406d95b090e3a56a3313)](https://app.codacy.com/gh/tom65536/annual/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
 ![OSS Lifecycle](https://img.shields.io/osslifecycle/tom65536/annual)
-[![Codacy Badge](https://app.codacy.com/project/badge/Grade/075ffea9b1b8406d95b090e3a56a3313)](https://app.codacy.com/gh/tom65536/annual/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8996/badge)](https://www.bestpractices.dev/projects/8996)
+
 
 ## Synopsis
 The Python package _annual_ provides date calculations
@@ -68,7 +70,7 @@ please read our [Contribution Guidelines](CONTRIBUTING.md).
 Our documentation is hosted on Read the Docs and is kept up-to-date
 with each release. You can find the full documentation at:
 
-[https://annual.readthedocs.io](https://annuam.readthedocs.io)
+[https://annual.readthedocs.io](https://annual.readthedocs.io)
 
 If you can't find the information you're looking for, please [open an issue](https://github.com/tom6t536/annual/issues) on our GitHub repository. We're always looking to improve our documentation and appreciate your feedback!
 

docs/source/conf.py

@@ -15,13 +15,16 @@
 
 extensions = [
     'autoapi.extension',
+    'sphinx_copybutton',
+    'sphinx_tabs.tabs',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
     'sphinx_rtd_theme',
     'sphinx_tabs.tabs',
     'sphinx-prompt',
     'sphinx_toolbox',
+    'sphinx_toolbox.decorators',
     'sphinx_toolbox.installation',
     'sphinx_toolbox.sidebar_links',
 ]

docs/source/extending.rst

@@ -0,0 +1,268 @@
+.. _extension-mechanism:
+
+Extension Mechanism
+===================
+
+While the ``annual`` package provides a robust set of rules for evaluating date
+recurrence, some date patterns may be too complex or unique to express using
+standard rules.
+To address this, ``annual`` offers a flexible plugin mechanism that allows users
+to extend the package's functionality by adding custom Python functions for
+computing additional dates for a given year.
+
+How It Works
+------------
+
+The extension mechanism enables you to define and integrate your own date
+computation functions and iterators seamlessly into the ``annual`` framework.
+These custom functions can handle specific date patterns or complex calculations
+that fall outside the scope of the built-in recurrence rules.
+
+The custom extensions may be provided and registered in two different ways:
+
+#. The author of the extension may choose to provide a package that properly
+   registers itself as a plugin. Any instance of the
+   :py:class:`annual.registry.FunctionRegistry` class, by default,
+   discovers all registered date functions and iterators and adds them to
+   the output function set.
+#. Any function or iterator, provided the right signature, may be
+   registered explicitly by invoking one of the methods
+
+   -  :py:meth:`annual.registry.FunctionRegistry.add_date_function`
+      adding a single function,
+
+   -  :py:meth:`annual.registry.FunctionRegistry.add_date_iterator`
+      adding a single iterator,
+
+   -  :py:meth:`annual.registry.FunctionRegistry.add_from_module`
+      adding all properly decorated functions and iterators
+      of the named module
+
+   -  :py:meth:`annual.registry.FunctionRegistry.add_from_plugins`
+      adding all properly decorated functions and iterators
+      from registered plugins (filters may be applied)
+
+
+Adding a new Function
+---------------------
+
+This example demonstrates how to use the ``convertdate`` package
+to calculate the date of `Eid al-Fitr`_ for a given Gregorian year
+and pass the result to an instance of the class
+:py:class:`annual.registry.FunctionRegistry`.
+
+Eid al-Fitr is an important Islamic holiday that marks the end of Ramadan,
+the month of fasting.
+Its date varies each year according to the Islamic lunar calendar.
+
+.. _Eid al-Fitr: https://en.m.wikipedia.org/wiki/Eid_al-Fitr
+
+
+Prerequisites
+~~~~~~~~~~~~~
+
+Before running this example, ensure you have the ``convertdate`` package
+installed..
+
+.. installation:: convertdate
+   :pypi:
+
+
+Defining a Date Function
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+A date function is a callable mapping an integer number representing the
+Gregorian year to a :py:class:`datetime.date` or ``None``, where the former
+is expected to be a date in the given year while a value of ``None``
+represents the case when an event does not occur in the given year.
+
+Eid al-Fitr occurs at least once in any Gregorian year, so the case
+of returning ``None`` does not apply in this example.
+
+.. note::
+
+   Conversely, since the islamic year is shorter than a Gregorian year
+   the case of celebrating Eid al-Fitr twice in one year can well happen.
+   This is the case, for example, in 2033. The given example does not account
+   for that case. Instead you would have to define a second date function
+   with a different name returning the second occurrence of Eid al-Fitr
+   in those rare cases and ``None`` in all other years.
+
+.. code-block:: python
+
+   import datetime
+
+   from annual.decorators import date_function
+
+   import convertdate
+
+
+   @date_function('eid-al-fidr')
+   def eid_al_fidr(year: int) -> datetime.date:
+      return datetime.date(*convertdate.holidays.eid_alfitr(year))
+
+
+The function is simply a thin wrapper converting the ``(year, month, day}``
+tuple returned from the ``convertdate`` library to a :py:class:`datetime.date`.
+The decorator :deco:`date_function` has a two-fold role:
+
+-  It marks the decorated function ``eid_al_fidr`` to be discoverable
+   by the methods
+   :py:meth:`annual.registry.FunctionRegistry.add_from_module` and
+   :py:meth:`annual.registry.FunctionRegistry.add_from_plugins`.
+   This is strictly-speeking not necessary in this example where we are
+   going to register the function directly using
+   :py:meth:`annual.registry.FunctionRegistry.add_date_function`.
+   However, it is good practice to express our intent for documentation
+   purposes.
+
+-  Providing an argument (``'eid-al-fidr'``)
+   it overwrites the name under which the function will be registered.
+   You may as well omit the argument in which case the function would
+   be registered with its true function name (``eid_al_fidr``) instead.
+
+.. note::
+
+   Function name syntax requires a name to start with an ASCII letter,
+   followed by any number of alphanumeric ASCII characters.
+   Any two letters or digits may be separated by an underscore, dot
+   or minus. Valid names are for example ``Eid_al-Fidr`` or
+   ``my.Feast-1`` but not ``Eid al-Fidr`` (space) or
+   ``1st-of-june`` (starts with a digit).
+
+Using the Date Function
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The preferred way of using custom date functions is by registering
+them with a n instance of the class
+:py:class:`annual.registry.FunctionRegistry`.
+
+.. code-block:: python
+
+   from annual.registry import FunctionRegistry
+
+   reg = FunctionRegistry()
+   reg.add_date_function(eid_all_fidr)
+
+By default, the function registry is initialized by scanning all
+installed plugins. As the ``annual`` package itself is a plugin as well
+the registry ``reg`` would contain not only ``eid-al-fidr`` which we have
+added explicitly but also some standard functions such as ``easter``,
+which are provided by the ``annual`` package. You may change this
+behavior by passing ``False`` as a function argument to the constructor.
+
+.. code-block:: python
+
+   reg = FunctionRegistry(False)
+
+
+The method :py:meth:`annual.registry.FunctionRegistry.evaluate`
+returns a dictionary with the actual dates of all registered functions
+for the given year. This dictionary may be passed s anarguent when creating
+a rule parser.
+
+.. code-block:: python
+
+   from annual.ruleparser import rule_parser
+
+   year = 2025
+   dates: dict[str, datetime.date | None] = reg.evaluate(year)
+   parser = rule_parser(year, dates)
+
+   assert parser.parse('Monday after eid-al-fidr') == datetime.date(2025, 4, 7)
+
+
+
+A Sample Plugin
+---------------
+
+In the previous example the date function has been added explicitly to the
+function registry by invoking
+:py:meth:`annual.registry.FunctionRegistry.add_date_function`.
+
+This example adds two modifications:
+
+-  Instead of a date function a date iterator is defined.
+
+-  The date iterator is defined as part of a plugin and therefore needs no
+   explicit registrtion.
+
+The date iterator yields all dates of full-moon using the package
+'`PMeeus`'.
+
+.. _PyMeeus:: https://pypi.org/project/PyMeeus/
+
+The date functions and date iterators belonging to one plugin
+must be collected in one module. The sample module below defines
+
+.. code-block:: python
+
+   """ Assume this file is src/my_plugin/full_moon.py."""
+   import datetime
+   from typing import Iterator
+
+   from annual.decorators import date_iterator
+
+   from pymeeus.Moon import Moon
+   from pymeeus.Epoch import Epoch
+
+
+   @date_iterator()
+   def enumerate_full_moons(year: int) -> Iterator[tuple[str, datetime.date]]:
+      """
+      Compute all full moon dates for a given year.
+
+      Arguments
+      ---------
+      year : int
+         The year for which to compute full moon dates.
+
+      Returns
+      -------
+      Iterator[tuple[str, datetime.date]]
+         Iterates over full moon dates.
+      """
+
+      # Start from December 1st of the previous year to catch any full moons
+      # that might occur in the first few days of the given year
+      current_date = datetime.date(year - 1, 12, 31)
+
+      idx = 0
+
+      while current_date.year <= year:
+         epoch = Epoch(current_date)
+
+         next_full = Moon.moon_phase(epoch, target="full")
+         y, m, d = next_full.get_date()
+         current_date = datetime.date(y, m, int(d))
+         if current_date.year == year:
+            yield (f'full-moon-{idx}', current_date)
+            idx += 1
+
+         current_date = current_date + datetime.timedelta(days=1)
+
+
+
+.. tabs::
+   .. tab:: pyproject.toml
+
+      .. code-block:: toml
+
+         x = "y"a
+
+   .. tab:: setup.cfg
+
+      .. code-block:: ini
+
+         x =  = fooo
+
+
+client code
+
+
+.. code-block:: python
+
+   from annual.registry import FunctionRegistry
+
+   reg = FunctionRegistry()
+   print(reg.evaluate(2024))

docs/source/index.rst

@@ -14,6 +14,7 @@ Welcome to annual's documentation!
    user_guide
    tutorials
    syntax
+   extending
    faq
 
    gherkin/gherkin

docs/source/requirements.txt

@@ -1,6 +1,7 @@
-
 sphinx~=7.3
 sphinx-autoapi~=3.1
+sphinx-copybutton~=0.5
 sphinx-gherkindoc~=3.6
+sphinx-tabs~=3.4
 sphinx-toolbox~=3.7
 sphinx_rtd_theme~=2.0

pyproject.toml

@@ -29,6 +29,10 @@ email = "[email protected]"
 [project.urls]
 Home = "https://github.com/tom65536/annual"
 Source = "https://github.com/tom65536/annual"
+Documentation = "https://annual.readthedocs.io/latest/"
+Pypi = "https://pypi.org/project/annual/"
+Issues = "https://github.com/tom65536/annual/issues"
+Changelog = "https://github.com/tom65536/annual/blob/main/CHANGELOG.md"
 
 [project.entry-points.annual]
 annual = 'annual.functions'

src/annual/decorators.py

@@ -29,7 +29,7 @@
 def date_function(
     name: str | None = None,
 ) -> Callable[[DateFunction], DateFunction]:
-    """Mark a date function to be made available in the parser.
+    """Mark a date function to be made available in the registry.
 
     The function name is used in the registry if no name is
     passed explicitly.
@@ -42,14 +42,14 @@ def date_function(
     Return
     ------
     Callable[[DateFunction], DateFunction]
-        the actual decortor
+        the actual decorator
     """
 
     def decorator_func(date_func: DateFunction) -> DateFunction:
         """Add the wrapper."""
 
         @wraps(date_func)
-        def wrapper(year: int) -> datetime.date | None:
+        def wrapper(year: int) -> MaybeDate:
             """Wrap the function.."""
             return date_func(year)
 
@@ -61,6 +61,31 @@ def wrapper(year: int) -> datetime.date | None:
     return decorator_func
 
 
+def date_iterator() -> Callable[[DateIterator], DateIterator]:
+    """Mark a date iterator to be made available in the registry.
+
+    The function name is used in the registry.
+
+    Return
+    ------
+    Callable[[DateIterator], DateIterator]
+        the actual decorator
+    """
+
+    def decorator_func(date_func: DateIterator) -> DateIterator:
+        """Add the wrapper."""
+
+        @wraps(date_func)
+        def wrapper(year: int) -> Iterator[tuple[str, MaybeDate]]:
+            """Wrap the function.."""
+            return date_func(year)
+
+        mark_decorator(wrapper, date_iterator.__name__)
+        return wrapper
+
+    return decorator_func
+
+
 @no_type_check
 def mark_decorator(
     wrapper: Callable[[int], MaybeDate],