macrotrace 0.2.2__tar.gz → 0.3.0__tar.gz

{macrotrace-0.2.2 → macrotrace-0.3.0}/.github/workflows/docs.yml

@@ -49,7 +49,7 @@ jobs:
           if [[ "$VERSION" =~ (rc|a|b|dev|alpha|beta) ]]; then
             uv run mike deploy --push "$VERSION"
           else
-            uv run mike deploy --push --update-aliases "$VERSION" latest
+            uv run mike deploy --push --update-aliases --alias-type copy "$VERSION" latest
             uv run mike set-default --push latest
           fi
 

{macrotrace-0.2.2 → macrotrace-0.3.0}/CHANGELOG.md

@@ -3,6 +3,22 @@
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 versions follow [SemVer](https://semver.org/).
 
+## 0.3.0 — 2026-06-15
+
+- **Breaking:** Naive date inputs (`as_of`, the vintage/data windows,
+  `vintage_comparison`) are read on the source's clock instead of UTC.
+  This fixes same-day vintages being silently skipped for FRED,
+  which stamps releases at midnight US Central:
+  `as_of("2018-03-16")` now returns the 2018-03-16 vintage, and a
+  `data_end_date` on a period boundary no longer drops the final observation.
+  Timezone-aware datetimes still compare as exact instants.
+- **Breaking:** Date strings must be `YYYY-MM-DD`; `datetime.date` objects
+  are now accepted. Free-text parsing is gone (along with the `dateutil`
+  dependency), so ambiguous formats like `"03/04/2018"` are rejected instead
+  of guessed.
+- **Fixed:** `created_at` columns stamped each row with the process start
+  time instead of its actual creation time.
+
 ## 0.2.2 — 2026-06-12
 
 - **Vintage matching:** `identify_vintage` now interprets a tz-naive index in

{macrotrace-0.2.2 → macrotrace-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macrotrace
-Version: 0.2.2
+Version: 0.3.0
 Summary: A Python library for managing and analyzing macroeconomic time series data with vintage awareness.
 Project-URL: Homepage, https://github.com/john-ramsey/macrotrace
 Project-URL: Repository, https://github.com/john-ramsey/macrotrace

macrotrace-0.3.0/macrotrace/_time.py

@@ -0,0 +1,19 @@
+from datetime import datetime, tzinfo
+from typing import Optional
+
+
+def ensure_timezone(dt: Optional[datetime], tz: tzinfo) -> Optional[datetime]:
+    """
+    Return the datetime made aware in ``tz``, or None.
+
+    Naive datetimes keep their wall clock while aware ones are converted. Uses pytz's
+    ``localize()`` when available so the real historical offset is picked
+    instead of pytz's first entry for the zone (LMT).
+    """
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        if hasattr(tz, "localize"):
+            return tz.localize(dt)
+        return dt.replace(tzinfo=tz)
+    return dt.astimezone(tz)

{macrotrace-0.2.2 → macrotrace-0.3.0}/macrotrace/models/db.py

@@ -40,6 +40,11 @@ def is_valid_dateoffset(value: str) -> bool:
         return False
 
 
+def _utc_now() -> datetime.datetime:
+    """Callable default so each row stamps its own creation time, not the import time."""
+    return datetime.datetime.now(tz=datetime.timezone.utc)
+
+
 class StrictDateTimeField(DateTimeField):
     """DateTimeField that enforces timezone-aware datetime objects in ISO 8601 format."""
 
@@ -122,9 +127,7 @@ class DatasetDimension(DataBaseModel):
     # Validity period for this dimension definition, null valid_to means currently valid
     valid_from = StrictDateTimeField()
     valid_to = StrictDateTimeField(null=True)
-    created_at = StrictDateTimeField(
-        default=datetime.datetime.now(tz=datetime.timezone.utc)
-    )
+    created_at = StrictDateTimeField(default=_utc_now)
 
     class Meta:
         constraints = [
@@ -152,9 +155,7 @@ class Release(DataBaseModel):
     )
     release_date = StrictDateTimeField()
     additional_metadata = JSONField(null=True)
-    created_at = StrictDateTimeField(
-        default=datetime.datetime.now(tz=datetime.timezone.utc)
-    )
+    created_at = StrictDateTimeField(default=_utc_now)
 
     class Meta:
         constraints = [SQL("UNIQUE(dataset_id, release_date)")]
@@ -182,9 +183,7 @@ class ReleaseDimension(DataBaseModel):
         backref="release_dimensions",
         on_delete="CASCADE",
     )
-    created_at = StrictDateTimeField(
-        default=datetime.datetime.now(tz=datetime.timezone.utc)
-    )
+    created_at = StrictDateTimeField(default=_utc_now)
 
     class Meta:
         constraints = [SQL("UNIQUE(release_id, dimension_id)")]
@@ -199,9 +198,7 @@ class ReleaseDimension(DataBaseModel):
 class Series(DataBaseModel):
     dataset = ForeignKeyField(Dataset, backref="series", on_delete="CASCADE")
     series_key = JSONField()
-    created_at = StrictDateTimeField(
-        default=datetime.datetime.now(tz=datetime.timezone.utc)
-    )
+    created_at = StrictDateTimeField(default=_utc_now)
 
     def __repr__(self):
         return (
@@ -249,9 +246,7 @@ class Observation(DataBaseModel):
 
     observation_timestamp = StrictDateTimeField()
     value = FloatField(null=True)  # null if the observation is missing
-    created_at = StrictDateTimeField(
-        default=datetime.datetime.now(tz=datetime.timezone.utc)
-    )
+    created_at = StrictDateTimeField(default=_utc_now)
 
     class Meta:
         constraints = [SQL("UNIQUE(release_id, observation_timestamp)")]

{macrotrace-0.2.2 → macrotrace-0.3.0}/macrotrace/models/mt/analysis.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from typing import Any, Dict, List, Optional, Tuple, TYPE_CHECKING, Union
+import datetime
 import logging
 
 import numpy as np
@@ -510,7 +511,6 @@ class MTTimeSeriesAnalysis:
         darts_ts = self.ts.to_darts_timeseries()
 
         if len(darts_ts) >= (min_train_size + 1):
-
             for i in range(min_train_size, len(darts_ts)):
                 train = darts_ts[:i]
                 test = darts_ts[i : i + 1]
@@ -629,7 +629,10 @@ class MTTimeSeriesAnalysis:
         )
 
     def vintage_comparison(
-        self, vintage_dates: List[str], mode: str = "growth", strategy: str = "all"
+        self,
+        vintage_dates: List[str | datetime.datetime | datetime.date],
+        mode: str = "growth",
+        strategy: str = "all",
     ) -> "VintageComparison":
         """
         Compare vintages across summary measures describing revisions of a
@@ -677,7 +680,9 @@ class MTTimeSeriesAnalysis:
                   period-over-period change in the level changes sign between vintages.
 
         Args:
-            vintage_dates (List[str]): A list of vintage identifiers to compare.
+            vintage_dates (List[str | datetime | date]): The vintages to
+                compare, each resolved through ``as_of()`` — a ``YYYY-MM-DD``
+                string or date for a calendar day, or a datetime for an exact instant.
             mode (str): The mode of comparison ("growth" or "levels").
             strategy (str): The strategy for comparison ("sequential", "final", or "all").
 

{macrotrace-0.2.2 → macrotrace-0.3.0}/macrotrace/models/mt/plotter.py

@@ -1,5 +1,5 @@
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
-from datetime import datetime
+from datetime import date, datetime
 import warnings
 
 import numpy as np
@@ -147,9 +147,8 @@ class MTTimeSeriesPlotter:
             go.Figure: Plotly figure showing observation revisions over time.
         """
         if isinstance(observation_datetime, str):
-            observation_datetime = self.ts._parse_string_date(
-                observation_datetime
-            )  # Returns UTC timezone
+            # Resolves to the source's midnight on that day
+            observation_datetime = self.ts._parse_string_date(observation_datetime)
         elif not isinstance(observation_datetime, datetime):
             raise ValueError(
                 f"Invalid observation datetime type: {type(observation_datetime)}. Must be a string or a datetime."
@@ -588,7 +587,7 @@ class MTTimeSeriesPlotter:
 
     def timeseries_comparison(
         self,
-        vintage_dates: List[str | datetime],
+        vintage_dates: List[str | datetime | date],
         chart_type: str = "bar",
         mode: str = "default",
         y_axis_zero_indexed: bool = False,
@@ -597,7 +596,7 @@ class MTTimeSeriesPlotter:
         Plots a comparison of time series vintages.
 
         Args:
-            vintage_dates (List[str | datetime]): List of vintage identifiers. Ex. '2025-11-01'
+            vintage_dates (List[str | datetime | date]): List of vintage identifiers, resolved via ``as_of``. Ex. '2025-11-01'
             chart_type (str, optional): Type of chart to plot. Either "bar" or "line". Defaults to "bar".
             mode (str, optional): The mode for which the dataframe is provided. Supports "default", "first_difference", and "pct_change". Defaults to "default".
             y_axis_zero_indexed (bool, optional): Sets base of the y-axis to zero.
@@ -610,14 +609,6 @@ class MTTimeSeriesPlotter:
                 f"Invalid mode: {mode}. Supported modes are 'default', 'first_difference', and 'pct_change'."
             )
 
-        for vintage_date in vintage_dates:
-            if (not isinstance(vintage_date, str)) and (
-                not isinstance(vintage_date, datetime)
-            ):
-                raise TypeError(
-                    "Vintage dates must be provided as strings or datetime objects."
-                )
-
         fig = go.Figure()
         all_values = []
         hoverinfo = "x+y+name"
@@ -626,7 +617,7 @@ class MTTimeSeriesPlotter:
             df = self.ts.as_of(vintage_date).to_dataframe(mode=mode)
             vintage_date = (
                 vintage_date.strftime("%Y-%m-%d")
-                if isinstance(vintage_date, datetime)
+                if isinstance(vintage_date, date)
                 else vintage_date
             )
             if chart_type == "bar":

{macrotrace-0.2.2 → macrotrace-0.3.0}/macrotrace/models/mt/time_series.py

@@ -1,7 +1,6 @@
 from typing import TYPE_CHECKING, List, Optional, Dict, Any, Tuple
 from dataclasses import dataclass, replace
-from dateutil import parser
-from datetime import datetime, timedelta, timezone, tzinfo
+from datetime import date, datetime, timedelta, timezone, tzinfo
 
 import numpy as np
 import pandas as pd
@@ -10,6 +9,7 @@ from tabulate import tabulate
 from darts import TimeSeries
 from peewee import JOIN
 
+from macrotrace._time import ensure_timezone
 from macrotrace.models.db import (
     Dataset,
     DatasetDimension,
@@ -141,7 +141,6 @@ class VintageMatch:
 
 
 class MTTimeSeries:
-
     def __init__(
         self,
         dataset_id: str,
@@ -150,12 +149,12 @@ class MTTimeSeries:
         # vintage_start_date and vintage_end_date define the vintage window returned
         # by this MTTimeSeries instance. Update managers may still backfill outside
         # the requested window so future loads can move backward without data loss.
-        vintage_start_date: Optional[str | datetime] = None,
-        vintage_end_date: Optional[str | datetime] = None,
+        vintage_start_date: Optional[str | datetime | date] = None,
+        vintage_end_date: Optional[str | datetime | date] = None,
         # Recall we want to only filter the observations returned, not the data fetched.
         # Filtering data before writing to the db may cause incomplete vintage chains.
-        data_start_date: Optional[str | datetime] = None,
-        data_end_date: Optional[str | datetime] = None,
+        data_start_date: Optional[str | datetime | date] = None,
+        data_end_date: Optional[str | datetime | date] = None,
         update_prior_to_load: bool = True,
         db_path: Optional[str] = None,
         cache_path: Optional[str] = None,
@@ -166,10 +165,19 @@ class MTTimeSeries:
             dataset_id: Dataset identifier (e.g., "GDP", "UNRATE")
             source: Data source ("FRED", "ONS", etc.)
             series_key: Dictionary of dimension filters for multi-dimensional datasets
-            vintage_start_date: Start date for vintage window
-            vintage_end_date: End date for vintage window
-            data_start_date: Filter observations after this date
-            data_end_date: Filter observations before this date
+
+            All four date windows are inclusive and accept a ``YYYY-MM-DD``
+            string, a ``datetime.date``, or a datetime. Naive input is read on
+            the source's own clock. A date becomes the source's midnight on that day,
+            matching how sources stamp their releases and observations — so e.g.
+            ``vintage_end_date="2018-03-16"`` includes FRED's 2018-03-16
+            release even though it is stored at midnight US Central.
+            Pass an aware datetime to bound by an exact instant instead.
+
+            vintage_start_date: Only load vintages released on or after this date
+            vintage_end_date: Only load vintages released on or before this date
+            data_start_date: Only keep observations stamped on or after this date
+            data_end_date: Only keep observations stamped on or before this date
             update_prior_to_load: Whether to fetch new data from API before loading
             db_path: Path to the SQLite database. Resolution: this argument,
                 then the ``MACROTRACE_DB`` env var, then ``MacroTrace.db`` in
@@ -414,36 +422,39 @@ class MTTimeSeries:
             self._analysis = MTTimeSeriesAnalysis(self)
         return self._analysis
 
-    def as_of(self, target_date: datetime | str) -> Optional["MTTimeSeries"]:
+    def as_of(self, target_date: datetime | str | date) -> Optional["MTTimeSeries"]:
         """
         Returns the most recent vintage as of a specific date.
 
+        A date string (``"YYYY-MM-DD"``), a ``datetime.date``, or a naive datetime
+        is read on the source's own clock, so a calendar date lands at the source's midnight
+        and matches how the source stamps its releases. A timezone-aware datetime is compared as the exact instant it denotes.
+
         Raises:
-            ValueError: If no vintages are available.
+            ValueError: If the target is a string not in ``YYYY-MM-DD`` form,
+                lies on a future calendar day in the source's timezone, or no
+                vintage exists on or before it.
 
         Args:
-            target_date (datetime | str): The target date to check against.
-                If a string is provided, it will be parsed into a datetime object.
-                If no timezone is provided, it is assumed to be in UTC.
+            target_date (datetime | str | date): The target date. Pass a
+                ``YYYY-MM-DD`` string or a date for a calendar day, or a
+                datetime for a specific moment.
 
         Returns:
-            MTTimeSeries: The latest available vintage on or before the target_date.
+            MTTimeSeries: The latest available vintage as of the target_date.
         """
-        if type(target_date) is str:
-            target_date = self._parse_string_date(target_date)
-        elif isinstance(target_date, datetime):
-            if target_date.tzinfo is None:
-                logger.warning(
-                    "Datetime object provided without timezone info. Assuming UTC."
-                )
-                target_date = target_date.replace(tzinfo=timezone.utc)
-        elif not isinstance(target_date, datetime):
+        if not isinstance(target_date, (str, date)):
             raise ValueError(
-                f"Invalid target date type: {type(target_date)}. Must be a string or a datetime."
+                f"Invalid target date type: {type(target_date)}. Must be a string, a date, or a datetime."
             )
+        target_date = self._clean_date(target_date)
 
-        # ensure the target date is not in the future
-        if target_date > datetime.now().astimezone():
+        # Guard against targets on a future calendar day. Comparing dates on
+        # the source's clock (not instants) keeps "as of today" valid even
+        # while the source's calendar day still lags UTC's.
+        native_tz = self._native_observation_timezone()
+        now_local = datetime.now(timezone.utc).astimezone(native_tz)
+        if target_date.astimezone(native_tz).date() > now_local.date():
             raise ValueError("The target date cannot be in the future.")
 
         eligible_vintages = self._find_eligible_vintages(target_date)
@@ -1255,28 +1266,30 @@ class MTTimeSeries:
 
     def _parse_string_date(self, dt: str) -> datetime:
         """
-        Parses a string date into a datetime object.
+        Parses a ``YYYY-MM-DD`` string to the source's midnight on that day.
+
+        Date strings denote calendar days, never instants, so only the
+        unambiguous ISO 8601 calendar form is accepted. Please pass a datetime
+        object when a specific time matters. The day is anchored at midnight
+        in the source's native timezone, which is how every source stamps its
+        release dates and observation timestamps.
 
         Args:
-            dt (str): The datetime string to parse.
+            dt (str): The date string to parse, in ``YYYY-MM-DD`` form.
 
         Returns:
-            datetime: The parsed datetime object.
+            datetime: The source-local midnight starting that calendar day.
+
+        Raises:
+            ValueError: If the string is not in ``YYYY-MM-DD`` form.
         """
         try:
-            parsed_dt = parser.parse(dt)
-            if parsed_dt.tzinfo is None:
-                # If no timezone is provided, assume UTC
-                logger.warning(
-                    f"Assuming datetime string {dt} is UTC timezone. Please provide a datetime object with timezone info if this is not the case."
-                )
-                parsed_dt = parsed_dt.replace(tzinfo=timezone.utc)
-            return parsed_dt
-
+            parsed_dt = datetime.strptime(dt, "%Y-%m-%d")
         except ValueError:
             raise ValueError(
-                f"Invalid date string format {dt}. Please provide a datetime or a date string which can be parsed by dateutil.parser."
+                f"Invalid date string format {dt}. Date strings must be 'YYYY-MM-DD'; pass a datetime object to target a specific time."
             )
+        return ensure_timezone(parsed_dt, self._native_observation_timezone())
 
     def _set_source(self, source: str):
         """Validate and set the data source."""
@@ -1287,23 +1300,29 @@ class MTTimeSeries:
             )
         self.source = source_upper
 
-    def _clean_date(self, dt: str | datetime) -> datetime:
-        """Convert a date string to a datetime object. Returns None if dt is None."""
+    def _clean_date(self, dt: str | datetime | date) -> Optional[datetime]:
+        """
+        Normalize a date input to an aware datetime on the source's clock.
+        """
         if dt is None:
             return None
         if isinstance(dt, str):
-            dt = parser.isoparse(dt)
-        elif isinstance(dt, datetime):
-            pass  # No need to parse, already a datetime object
-        else:
-            raise TypeError(f"Invalid date format: {dt}")  # Not a string or datetime
-
-        if dt.tzinfo is None:
-            logger.warning(
-                "Datetime object provided without timezone info. Assuming UTC."
+            return self._parse_string_date(dt)
+        if isinstance(dt, datetime):
+            if dt.tzinfo is None:
+                logger.warning(
+                    "Datetime object provided without timezone info. "
+                    "Interpreting it in the source's native timezone (%s).",
+                    self._native_observation_timezone(),
+                )
+                dt = ensure_timezone(dt, self._native_observation_timezone())
+            return dt
+        if isinstance(dt, date):
+            return ensure_timezone(
+                datetime(dt.year, dt.month, dt.day),
+                self._native_observation_timezone(),
             )
-            dt = dt.replace(tzinfo=timezone.utc)
-        return dt
+        raise TypeError(f"Invalid date format: {dt}")  # Not a string or datetime
 
     def _get_series_dimension_from_key(self, state) -> List[DatasetDimension]:
         """

{macrotrace-0.2.2 → macrotrace-0.3.0}/macrotrace/sources/fred.py

@@ -1,14 +1,13 @@
 import os
 from datetime import datetime
 from typing import Any, List, Optional, Dict
-from dateutil import parser
 
 import numpy as np
 import pytz
 
 from tqdm import tqdm
 
-
+from macrotrace._time import ensure_timezone
 from macrotrace.sources.base import (
     APIClient,
     UpdateManager,
@@ -115,36 +114,15 @@ class FredDatasetManager(DatasetManager):
 
     def _parse_date(self, date_str: str) -> Optional[datetime]:
         """
-        Parse the FRED date string from FRED API into a datetime object.
-        FRED uses "9999-12-31" to indicate an ongoing dimension, which we convert to None.
-
-        Args:
-            date_str (str): The date string from FRED API.
-        Returns:
-            Optional[datetime]: A datetime object representing valid_to, or None if ongoing.
+        Parse a FRED API date (always YYYY-MM-DD) to midnight US Central.
+        FRED uses "9999-12-31" to indicate an ongoing dimension -> None.
         """
-        try:
-            date = parser.parse(date_str)
-            if date.tzinfo is None:
-                # Use pytz.localize() rather than .replace(tzinfo=...) — the latter
-                # binds pytz's first historical entry for America/Chicago (LMT,
-                # -05:50:36) instead of CST/CDT, which silently drifts dates by
-                # ~9 minutes and causes downstream day-rollback bugs after
-                # tz_convert + normalize. See tests/sources/fred/test_fred_tz_handling.py.
-                date = US_CENTRAL.localize(date)
-            if date.year == 9999 and date.month == 12 and date.day == 31:
-                logger.debug("Parsed ongoing dimension date (9999-12-31) as None")
-                return None
-            return date
-        except (ValueError, OverflowError) as e:
-            # FRED uses 9999-12-31 to indicate "ongoing" check for parsing errors "date value out of range"
-            if "out of range" in str(e):
-                logger.debug(
-                    f"Date {date_str} out of range, treating as ongoing (None)"
-                )
-                return None
-            else:
-                raise e
+        if date_str == "9999-12-31":
+            logger.debug("Parsed ongoing dimension date (9999-12-31) as None")
+            return None
+        return ensure_timezone(
+            datetime.strptime(date_str, FRED_DATE_FORMAT), US_CENTRAL
+        )
 
     def _convert_frequency(self, fred_frequency: str) -> Optional[str]:
         """
@@ -287,24 +265,6 @@ class FredReleaseManager(ReleaseManager):
     def __init__(self, api_client: FredAPIClient):
         super().__init__(api_client)
 
-    def _ensure_us_central(self, dt: datetime) -> datetime:
-        """
-        Ensure the given datetime is in US Central timezone.
-
-        Args:
-            dt (datetime): The datetime to check.
-        Returns:
-            datetime: The datetime in US Central timezone.
-        """
-        if dt is None:
-            return None
-        if dt.tzinfo is None:
-            # Assume US Central if no timezone info. Use pytz.localize() so the
-            # CST/CDT offset is selected per-date instead of LMT (-05:50:36).
-            return US_CENTRAL.localize(dt)
-        # Otherwise, convert to US Central
-        return dt.astimezone(US_CENTRAL)
-
     def fetch_new_releases(
         self,
         state: UpdateState,
@@ -322,8 +282,8 @@ class FredReleaseManager(ReleaseManager):
             List[Release]: A list of new Release objects to be created.
         """
         # Convert release_start_date and release_end_date to US Central timezone if they are not None and have no timezone info
-        state.release_start_date = self._ensure_us_central(state.release_start_date)
-        state.release_end_date = self._ensure_us_central(state.release_end_date)
+        state.release_start_date = ensure_timezone(state.release_start_date, US_CENTRAL)
+        state.release_end_date = ensure_timezone(state.release_end_date, US_CENTRAL)
 
         # Get the appropriate API start date (handles backfilling)
         api_start_date = self._get_api_start_date(

{macrotrace-0.2.2 → macrotrace-0.3.0}/macrotrace/sources/ons.py

@@ -9,6 +9,7 @@ from tenacity import (
     retry_if_exception,
 )
 
+from macrotrace._time import ensure_timezone
 from macrotrace.models.db import (
     Dataset,
     DatasetDimension,
@@ -750,8 +751,10 @@ class ONSReleaseManager(ReleaseManager):
                 skipped_count += 1
                 continue
             else:
-                release_date = datetime.fromisoformat(release_date_str).replace(
-                    tzinfo=UTC
+                # ensure_timezone converts (rather than overwrites) the offset
+                # should the API ever return a non-UTC time.
+                release_date = ensure_timezone(
+                    datetime.fromisoformat(release_date_str), UTC
                 )
 
             if self._skip_release(release_date, state, current_release_dates):

{macrotrace-0.2.2 → macrotrace-0.3.0}/macrotrace/sources/rtdsm.py

@@ -53,6 +53,7 @@ from tenacity import (
 )
 from tqdm import tqdm
 
+from macrotrace._time import ensure_timezone
 from macrotrace.models.db import (
     DatasetDimension,
     Observation,
@@ -611,20 +612,6 @@ def _parse_workbook(
     return ParsedVintageFile(vintages=vintages, cells=cells)
 
 
-def _ensure_utc(dt: Optional[datetime]) -> Optional[datetime]:
-    """
-    Return the datetime as a timezone-aware UTC value, or None.
-
-    RTDSM release dates are stored in UTC, so any caller-supplied window bound
-    must also be timezone-aware to compare correctly.
-    """
-    if dt is None:
-        return None
-    if dt.tzinfo is None:
-        return dt.replace(tzinfo=UTC)
-    return dt.astimezone(UTC)
-
-
 class RTDSMAPIClient(APIClient):
     """
     Downloads and parses a single RTDSM spreadsheet.
@@ -822,8 +809,8 @@ class RTDSMReleaseManager(ReleaseManager):
         Returns:
             List[Release]: The new releases.
         """
-        state.release_start_date = _ensure_utc(state.release_start_date)
-        state.release_end_date = _ensure_utc(state.release_end_date)
+        state.release_start_date = ensure_timezone(state.release_start_date, UTC)
+        state.release_end_date = ensure_timezone(state.release_end_date, UTC)
 
         parsed = self.api_client.get_parsed_file()
         current_release_dates = self._get_current_releases_in_db(state.dataset.id)

{macrotrace-0.2.2 → macrotrace-0.3.0}/scripts/backstop_ingest.py

@@ -21,7 +21,6 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Dict, List, Optional
 from dotenv import load_dotenv
-from dateutil import parser as date_parser
 
 from macrotrace import MTTimeSeries
 from macrotrace._paths import resolve_db_path
@@ -181,13 +180,6 @@ def _reset_local_db() -> None:
     LOGGER.info("Reset local DB %s (dropped %d tables)", db_path, len(tables))
 
 
-def _parse_date_to_utc(date_value: str) -> datetime:
-    dt = date_parser.isoparse(date_value)
-    if dt.tzinfo is None:
-        dt = dt.replace(tzinfo=timezone.utc)
-    return dt.astimezone(timezone.utc)
-
-
 def _is_placeholder_value(value: object) -> bool:
     if isinstance(value, str):
         return value.startswith("__REPLACE_")
@@ -204,7 +196,7 @@ def _ingest_one(
     source: str,
     source_name: str,
     dataset_id: str,
-    vintage_start_date: datetime,
+    vintage_start_date: str,
     series_key: Optional[Dict[str, str]] = None,
 ) -> IngestResult:
     start = time.perf_counter()
@@ -256,7 +248,7 @@ def _build_cli() -> argparse.ArgumentParser:
     parser.add_argument(
         "--vintage-start-date",
         default="2019-01-01",
-        help="ISO-8601 release start date to limit ingest volume (default: 2019-01-01).",
+        help="Release start date (YYYY-MM-DD) to limit ingest volume (default: 2019-01-01).",
     )
     parser.add_argument(
         "--max-failures",
@@ -293,7 +285,9 @@ def main() -> int:
         LOGGER.error("FRED_API_KEY is not set; FRED ingestion cannot run.")
         return 2
 
-    vintage_start_date = _parse_date_to_utc(args.vintage_start_date)
+    # Passed through to MTTimeSeries, which reads the calendar date on each
+    # source's own clock.
+    vintage_start_date = args.vintage_start_date
     results: List[IngestResult] = []
 
     LOGGER.info("Starting FRED ingest (%d sources)", len(FRED_SOURCES))