feat: --since= on the command line, and since=DATE. #26

Author: nedbat

README.rst

@@ -114,7 +114,8 @@ clause sets defaults for the digest options in the rest of the file.  Each
   units of weeks, days, hours, minutes and seconds, and can also be
   abbreviated, like ``1d6h``. Using ``since: forever`` will include all
   activity regardless of when it happened.  If ``since`` is omitted, it
-  defaults to one week.
+  defaults to one week.  You can specify ``--since=<SINCE>`` on the dinghy
+  command line to provide an explicit value.
 
 - The ``items`` setting is a list of things to report on, specified in a few
   different ways:

dev-requirements.txt

@@ -2,6 +2,7 @@
 black
 build
 check-manifest
+freezegun
 pylint
 pytest
 readme_renderer

scriv.d/20230730_211636_nedbat.rst

@@ -0,0 +1,10 @@
+Added
+.....
+
+- The ``since`` date can now be specified on the command line with ``--since``.
+  This will override any specification in the YAML file.
+
+- The ``since`` value can be specified as a specific ISO 8601 date,
+  implementing part of `issue 26`_.
+
+.. _issue 26: https://github.com/nedbat/dinghy/issues/26

setup.cfg

@@ -36,6 +36,7 @@ package_dir =
 install_requires =
     aiofiles>=0.8
     aiohttp>3
+    backports-datetime-fromisoformat
     click>8
     click-log>0.3
     emoji

src/dinghy/cli.py

@@ -42,9 +42,10 @@ def main_run(coro):
 @click.command()
 @click_log.simple_verbosity_option(logger)
 @click.version_option()
+@click.option("--since", metavar="DELTA-OR-DATE", help="Specify a since date.")
 @click.argument("_input", metavar="[INPUT]", default="dinghy.yaml")
 @click.argument("digests", metavar="[DIGEST ...]", nargs=-1)
-def cli(_input, digests):
+def cli(since, _input, digests):
     """
     Generate HTML digests of GitHub activity.
 
@@ -58,6 +59,6 @@ def cli(_input, digests):
     if "://" in _input:
         coro = make_digest([_input])
     else:
-        coro = make_digests_from_config(_input, digests or None)
+        coro = make_digests_from_config(_input, digests or None, since=since)
 
     main_run(coro)

src/dinghy/digest.py

@@ -16,7 +16,7 @@
 
 from . import __version__
 from .graphql_helpers import build_query, GraphqlHelper
-from .helpers import DinghyError, json_save, parse_timedelta
+from .helpers import DinghyError, json_save, parse_since
 from .jinja_helpers import render_jinja_to_file
 
 
@@ -506,12 +506,8 @@ async def make_digest(items, since="1 week", digest="digest.html", **options):
         digest (str): the HTML file name to write.
 
     """
-    if since == "forever":
-        show_date = False
-        since_date = datetime.datetime(year=1980, month=1, day=1)
-    else:
-        show_date = True
-        since_date = datetime.datetime.now() - parse_timedelta(since)
+    show_date = since != "forever"
+    since_date = parse_since(since)
     digester = Digester(since=since_date, options=options)
 
     coros = []
@@ -544,13 +540,14 @@ async def make_digest(items, since="1 week", digest="digest.html", **options):
     logger.info(f"Wrote digest: {digest}")
 
 
-async def make_digests_from_config(conf_file, digests=None):
+async def make_digests_from_config(conf_file, digests=None, since=None):
     """
     Make all the digests specified by a configuration file.
 
     Args:
         conf_file (str): a file path to read as a config file.
-
+        digests (list of str): the digest names to make.
+        since (str): the spec for since when.
     """
     try:
         with open(conf_file, encoding="utf-8") as cf:
@@ -567,6 +564,8 @@ async def make_digests_from_config(conf_file, digests=None):
         args = {**defaults, **spec}
         if digests is not None and args["digest"] not in digests:
             continue
+        if since is not None:
+            args["since"] = since
         coros.append(make_digest(**args))
     await asyncio.gather(*coros)
 

src/dinghy/helpers.py

@@ -7,6 +7,9 @@
 import re
 
 import aiofiles
+from backports.datetime_fromisoformat import MonkeyPatch
+
+MonkeyPatch.patch_fromisoformat()
 
 
 class DinghyError(Exception):
@@ -29,7 +32,7 @@ def parse_timedelta(timedelta_str):
         timedelta_str (str): A string identifying a duration, like "2h13m".
 
     Returns:
-        A datetime.timedelta object.
+        A datetime.timedelta object, or None if it can't be parsed.
 
     """
     parts = re.match(
@@ -45,11 +48,34 @@ def parse_timedelta(timedelta_str):
         timedelta_str.replace(" ", ""),
     )
     if not timedelta_str or parts is None:
-        raise ValueError(f"Couldn't parse time delta from {timedelta_str!r}")
+        return None
     kwargs = {name: float(val) for name, val in parts.groupdict().items() if val}
     return datetime.timedelta(**kwargs)
 
 
+def parse_since(since):
+    """
+    Parse a since specification:
+
+    - "forever" uses a long-ago date.
+    - A time delta (like "1 week") computes that long ago.
+    - A specific time (like "2023-07-30") is used as-is.
+
+    """
+    if since == "forever":
+        since_date = datetime.datetime(year=1980, month=1, day=1)
+    else:
+        delta = parse_timedelta(since)
+        if delta is not None:
+            since_date = datetime.datetime.now() - delta
+        else:
+            try:
+                since_date = datetime.datetime.fromisoformat(since)
+            except ValueError:
+                raise DinghyError("Can't parse since: {since!r}") from None
+    return since_date
+
+
 def find_dict_with_key(d, key):
     """Return the subdict of `d` that has `key`."""
     if key in d:

tests/test_helpers.py

@@ -4,9 +4,10 @@
 
 import datetime
 
+import freezegun
 import pytest
 
-from dinghy.helpers import find_dict_with_key, parse_timedelta
+from dinghy.helpers import find_dict_with_key, parse_since, parse_timedelta
 
 
 @pytest.mark.parametrize(
@@ -37,8 +38,23 @@ def test_parse_timedelta(tds, kwargs):
     ],
 )
 def test_bad_parse_timedelta(tds):
-    with pytest.raises(ValueError, match=f"Couldn't parse time delta from {tds!r}"):
-        parse_timedelta(tds)
+    assert parse_timedelta(tds) is None
+
+
+@freezegun.freeze_time("2023-06-16")
+@pytest.mark.parametrize(
+    "since, dtargs",
+    [
+        ("20230730", (2023, 7, 30)),
+        ("2023-06-16T12:34:56", (2023, 6, 16, 12, 34, 56)),
+        ("forever", (1980, 1, 1)),
+        ("1day", (2023, 6, 15)),
+        ("2 weeks", (2023, 6, 2)),
+        ("1 week 1 day", (2023, 6, 8)),
+    ],
+)
+def test_parse_since(since, dtargs):
+    assert parse_since(since) == datetime.datetime(*dtargs)
 
 
 @pytest.mark.parametrize(