Merge pull request #35 from Kintyre/minor-docs2

Minor doc cleanups

README.rst

@@ -139,14 +139,19 @@ Test for a match with (>=0.3.32)::
 Gaps between date matches
 =========================
 For performance reasons, croniter limits the amount of CPU cycles spent attempting to find the next match.
-By default croniter stops looking for dates more than 50 years away from the current time, and if the next cannot be reached within that span then ``CroniterBadDateError`` is raised.
-This works fine for most "normal" cron expressions, but can be limiting for very rare cron expressions.
+Starting in v0.3.35, this behavior is configurable via the ``max_years_between_matches`` parameter, and the default window has been increased from 1 year to 50 years.
 
-For example, say you're looking to match 4AM Friday January 1st.
-Since January 1 isn't often a Friday, it can be a few years between each occurrence.
-Starting in v0.3.35, croniter provides a ``max_years_between_matches`` parameter that allows more than 50 years default to be extended for scenarios like this::
+The defaults should be fine for many use cases.
+Applications that evaluate multiple cron expressions or handle cron expressions from untrusted sources or end-users should use this parameter.
+Iterating over sparse cron expressions can result in increased CPU consumption or a raised ``CroniterBadDateError`` exception which indicates that croniter has given up attempting to find the next (or previous) match.
+Explicitly specifying ``max_years_between_matches`` provides a way to limit CPU utilization and simplifies the iterable interface by eliminating the need for ``CroniterBadDateError``.
+The difference in the iterable interface is based on the reasoning that whenever ``max_years_between_matches`` is explicitly agreed upon, there is no need for croniter to signal that it has given up; simply stopping the iteration is preferable.
 
-    >>> it = croniter("0 4 1 1 fri", datetime(2000,1,1), day_or=False, max_years_between_matches=100).all_next(datetime)
+This example matches 4 AM Friday, January 1st.
+Since January 1st isn't often a Friday, there may be a few years between each occurrence.
+Setting the limit to 15 years ensures all matches::
+
+    >>> it = croniter("0 4 1 1 fri", datetime(2000,1,1), day_or=False, max_years_between_matches=15).all_next(datetime)
     >>> for i in range(5):
     ...     print(next(it))
     ...
@@ -156,23 +161,8 @@ Starting in v0.3.35, croniter provides a ``max_years_between_matches`` parameter
     2027-01-01 04:00:00
     2038-01-01 04:00:00
 
-Trying this without ``max_years_between_matches`` results in an exception, because there's a full decade between the 2000 start date and the first match in 2010::
-
-    >>> it = croniter("0 4 1 1 fri", datetime(2000,1,1), day_or=False).all_next()
-    >>> next(it)
-    Traceback (most recent call last):
-      File "<stdin>", line 1, in <module>
-      ...
-    croniter.CroniterBadDateError: failed to find next date
-
-One advantage of explicitly specifying ``max_years_between_matches`` is that it simplifies the various iterable interfaces.
-Specifically ``all_next()``, ``all_prev()`` and ``iter()``) stop raising the ``CroniterBadDateError`` exception when a window is specified.
-The rationale is that since you've explicitly told croniter how far to look into the future (or past) to find the next/previous date, there's no need for a special exception.
-Instead, if no match is found then iteration is stopped.
-This makes the these iterable interfaces act as more like normal Python iterators without having to deal with any extra exceptions.
-This distinction allows v0.3.35 and later to keep the same default behavior as earlier versions.
-
-In summary:  For many cron expressions this will never matter.  Use ``max_years_between_matches`` to make iteration simplier.
+However, when only concerned with dates within the next 5 years, simply set ``max_years_between_matches=5`` in the above example.
+This will result in no matches found, but no additional cycles will be wasted on unwanted matches far in the future.
 
 Iterating over a range using cron
 =================================
@@ -227,4 +217,4 @@ If you have contributed and your name is not listed below please let me know.
     - chris-baynes
     - ipartola
     - yuzawa-san
-    - lowell80
+    - lowell80 (Kintyre)

docs/CHANGES.rst

@@ -5,21 +5,23 @@ Changelog
 -------------------
 
 - Nothing changed yet.
+- Updated docs section regarding ``max_years_between_matches`` to be more shorter and hopefully more relevant.
+  [Kintyre]
 
 
 0.3.35 (2020-10-11)
 -------------------
 
 - Handle L in ranges. This fixes #142.
   [kiorky]
-- Add a new initializaton paramter ``max_years_between_matches`` to support finding the next/previous date beyond the default 1 year window, if so desired.  Updated README to include additional notes and example of this usage.  Fixes #145.
+- Add a new initialization parameter ``max_years_between_matches`` to support finding the next/previous date beyond the default 1 year window, if so desired.  Updated README to include additional notes and example of this usage.  Fixes #145.
   [Kintyre]
 - The ``croniter_range()`` function was updated to automatically determines the appropriate ``max_years_between_matches`` value, this preventing handling of the ``CroniterBadDateError`` exception.
   [Kintyre]
 - Updated exception handling classes:  ``CroniterBadDateError`` now only
-  applies during date finding operations (next/prev), and all parsing errors can now be caught using ``CroniterBadCronError``.  The ``CroniterNotAlphaError`` exception is now a subclass of ``CroniterBadCronError``.  A breif description of each exception class was added as an inline docstring.
+  applies during date finding operations (next/prev), and all parsing errors can now be caught using ``CroniterBadCronError``.  The ``CroniterNotAlphaError`` exception is now a subclass of ``CroniterBadCronError``.  A brief description of each exception class was added as an inline docstring.
   [Kintyre]
-- Updated iterable interfaces to replace the ``CroniterBadDateError`` with ``StopIteration`` if (and only if) the ``max_years_between_matches`` argument is provided.  The rationale here is that if the user has specified the max tollernace between matches, then there's no need to further inform them of no additional matches.  Just stop the iteration.  This also keeps backwards compatibility.
+- Updated iterable interfaces to replace the ``CroniterBadDateError`` with ``StopIteration`` if (and only if) the ``max_years_between_matches`` argument is provided.  The rationale here is that if the user has specified the max tolerance between matches, then there's no need to further inform them of no additional matches.  Just stop the iteration.  This also keeps backwards compatibility.
   [Kintyre]
 - Minor docs update
   [Kintyre]
@@ -28,7 +30,7 @@ Changelog
 0.3.34 (2020-06-19)
 -------------------
 
-- Feat croniter_range(start, stop, cron)
+- Feat ``croniter_range(start, stop, cron)``
   [Kintyre]
 - Optimization for poorly written cron expression
   [Kintyre]
@@ -91,7 +93,7 @@ Changelog
 0.3.23 (2018-05-23)
 -------------------
 
-- fix ``get_next`` while perserving the fix of ``get_prev`` in 7661c2aaa
+- fix ``get_next`` while preserving the fix of ``get_prev`` in 7661c2aaa
   [Avikam Agur <avikam@pagaya-inv.com>]
 
 
@@ -183,7 +185,7 @@ Changelog
 0.3.10 (2015-11-29)
 -------------------
 
-- The fuctionality of 'l' as day of month was broken, since the month variable
+- The functionality of 'l' as day of month was broken, since the month variable
   was not properly updated
   [Iddo Aviram <iddo.aviram@similarweb.com>]
 
@@ -224,7 +226,7 @@ Changelog
 ------------------
 
 - Python 3 compat
-- QA Relase
+- QA Release
 
 
 0.3.3 (2012-09-29)