From 28b5a81d19d29afceb31bff2beb6db4516399ad2 Mon Sep 17 00:00:00 2001 From: Ross Patterson Date: Sun, 24 Aug 2025 09:22:57 -0700 Subject: [PATCH] [DOCS] faq: Clarify re-download date TZ margins (#1298) * docs(faq): Clarify re-download date TZ margins From [Discord discussion](https://discord.com/channels/994270357957648404/1102703969266049174/1408092149492224060). * docs(faq): Clarify date_range inclusivity From [PR followup](https://github.com/jmbannon/ytdl-sub/pull/1298#issuecomment-3214598919). --- docs/source/config_reference/plugins.rst | 12 +++++++----- docs/source/faq/index.rst | 7 ++++--- src/ytdl_sub/plugins/date_range.py | 12 +++++++----- src/ytdl_sub/validators/string_datetime.py | 8 +++++--- 4 files changed, 23 insertions(+), 16 deletions(-) diff --git a/docs/source/config_reference/plugins.rst b/docs/source/config_reference/plugins.rst index bc8bf0a3..97c88886 100644 --- a/docs/source/config_reference/plugins.rst +++ b/docs/source/config_reference/plugins.rst @@ -147,9 +147,11 @@ Dates must adhere to a yt-dlp datetime. From their docs: A string in the format YYYYMMDD or (now|today|yesterday|date)[+-][0-9](microsecond|second|minute|hour|day|week|month|year)(s) -Valid examples are ``now-2weeks`` or ``20200101``. Can use override variables in this. -Note that yt-dlp will round times to the closest day, meaning that `day` is the lowest -granularity possible. +Valid examples are ``now-2weeks`` or ``20200101``. Can use override variables in +this. Note that yt-dlp will round times to the closest day, meaning that `day` is +the lowest granularity possible. Also note that, considering time zones, it's best +to include a margin of an extra day on either side to be sure it includes the +intended download files. :Usage: @@ -165,14 +167,14 @@ granularity possible. :expected type: Optional[OverridesFormatter] :description: - Only download videos after this datetime. + Only download videos after or on this datetime, inclusive. ``before`` :expected type: Optional[OverridesFormatter] :description: - Only download videos before this datetime. + Only download videos only before this datetime, not inclusive. ``breaks`` diff --git a/docs/source/faq/index.rst b/docs/source/faq/index.rst index b33a4b55..0a2105c0 100644 --- a/docs/source/faq/index.rst +++ b/docs/source/faq/index.rst @@ -195,9 +195,10 @@ need to be removed: the subscriptions ` to download only the files that you've renamed in the steps above. - Set the appropriate dates and subscription name to include only the files you've - renamed, and re-run. For example, if you've renamed all the files from 2024 in the - ``NOVA PBS`` subscription: + Set the appropriate dates, :ref:`including a sufficient margin + `, and subscription name to include only the + files you've renamed, and re-run. For example, if you've renamed all the files from + 2024 in the ``NOVA PBS`` subscription: .. code-block:: shell diff --git a/src/ytdl_sub/plugins/date_range.py b/src/ytdl_sub/plugins/date_range.py index 34370a1a..478cf938 100644 --- a/src/ytdl_sub/plugins/date_range.py +++ b/src/ytdl_sub/plugins/date_range.py @@ -25,9 +25,11 @@ class DateRangeOptions(ToggleableOptionsDictValidator): A string in the format YYYYMMDD or (now|today|yesterday|date)[+-][0-9](microsecond|second|minute|hour|day|week|month|year)(s) - Valid examples are ``now-2weeks`` or ``20200101``. Can use override variables in this. - Note that yt-dlp will round times to the closest day, meaning that `day` is the lowest - granularity possible. + Valid examples are ``now-2weeks`` or ``20200101``. Can use override variables in + this. Note that yt-dlp will round times to the closest day, meaning that `day` is + the lowest granularity possible. Also note that, considering time zones, it's best + to include a margin of an extra day on either side to be sure it includes the + intended download files. :Usage: @@ -56,7 +58,7 @@ class DateRangeOptions(ToggleableOptionsDictValidator): """ :expected type: Optional[OverridesFormatter] :description: - Only download videos before this datetime. + Only download videos only before this datetime, not inclusive. """ return self._before @@ -65,7 +67,7 @@ class DateRangeOptions(ToggleableOptionsDictValidator): """ :expected type: Optional[OverridesFormatter] :description: - Only download videos after this datetime. + Only download videos after or on this datetime, inclusive. """ return self._after diff --git a/src/ytdl_sub/validators/string_datetime.py b/src/ytdl_sub/validators/string_datetime.py index d50be211..53e7bb52 100644 --- a/src/ytdl_sub/validators/string_datetime.py +++ b/src/ytdl_sub/validators/string_datetime.py @@ -12,9 +12,11 @@ class StringDatetimeValidator(OverridesStringFormatterValidator): A string in the format YYYYMMDD or (now|today|yesterday|date)[+-][0-9](microsecond|second|minute|hour|day|week|month|year)(s) - Valid examples are ``now-2weeks`` or ``20200101``. Can use override variables in this. - Note that yt-dlp will round times to the closest day, meaning that `day` is the lowest - granularity possible. + Valid examples are ``now-2weeks`` or ``20200101``. Can use override variables in + this. Note that yt-dlp will round times to the closest day, meaning that `day` is + the lowest granularity possible. Also note that, considering time zones, it's best + to include a margin of an extra day on either side to be sure it includes the + intended download files. """ _expected_value_type_name = "datetime string"