flowtask 5.12.19__tar.gz → 5.13.1__tar.gz

{flowtask-5.12.19 → flowtask-5.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flowtask
-Version: 5.12.19
+Version: 5.13.1
 Summary: Framework for Task orchestration
 Author-email: Jesus Lara <jesuslarag@gmail.com>
 License: Apache-2.0

{flowtask-5.12.19 → flowtask-5.13.1}/flowtask/__main__.py

@@ -185,7 +185,14 @@ def main():
     from .utils.uv import install_uvloop
     from .utils import cPrint
     install_uvloop()
-    loop = asyncio.get_event_loop()
+    # `get_event_loop()` stopped creating a loop when none is set: it is
+    # deprecated on 3.10+, and uvloop 0.22 raises outright instead of falling
+    # back. Without this the CLI dies before the first log line.
+    try:
+        loop = asyncio.get_event_loop()
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
     loop.slow_callback_duration = 0.2
     try:
         result = loop.run_until_complete(task(loop))

{flowtask-5.12.19 → flowtask-5.13.1}/flowtask/components/CopyToPg.py

@@ -10,7 +10,6 @@ from typing import Sequence, Union
 import pandas as pd
 from pandas.api.types import (
     is_datetime64_any_dtype,
-    is_datetime64tz_dtype,
     is_integer_dtype,
     is_float_dtype,
     is_bool_dtype
@@ -461,7 +460,7 @@ class CopyToPg(CopyTo):
                                 utc=True  # parse as UTC if a tz string is present
                             )
                         # After the coercion, act only on tz-aware columns
-                        if is_datetime64tz_dtype(self.data[col]):
+                        if isinstance(self.data[col].dtype, pd.DatetimeTZDtype):
                             # tz_localize(None) drops the tz info but keeps the *wall time*
                             # e.g. 2025-03-20 19:11:09+00:00 → 2025-03-20 19:11:09
                             self.data[col] = self.data[col].dt.tz_localize(None)

{flowtask-5.12.19 → flowtask-5.13.1}/flowtask/components/MarketClustering.py

@@ -27,12 +27,19 @@ from ..interfaces.OverpassGeocoding import (
     ReverseGeocodeResult,
     DEFAULT_OVERPASS_URL,
 )
+from ..interfaces.GoogleReverseGeocoding import GoogleReverseGeocoder
+from ..interfaces.NominatimGeocoding import (
+    NominatimReverseGeocoder,
+    DEFAULT_NOMINATIM_URL,
+    DEFAULT_NOMINATIM_USER_AGENT,
+    PUBLIC_MIN_INTERVAL,
+)
 from ..exceptions import (
     DataNotFound,
     ConfigError,
     ComponentError,
 )
-from ..conf import ROUTING_DETOUR_FACTOR
+from ..conf import ROUTING_DETOUR_FACTOR, GOOGLE_PLACES_API_KEY
 from ..interfaces.routing import RoutingService, DistanceMatrix
 from .SchedulingVisits import SchedulingVisits
 
@@ -50,6 +57,9 @@ from .SchedulingVisits import SchedulingVisits
 # through the actual RoutingService instance and its own average_speed.
 _INTRA_CLUSTER_AVERAGE_SPEED_MPH = 40.0
 
+# Reverse geocoders accepted by `geocoding_backend` (resolve_centroid_location).
+GEOCODING_BACKENDS = frozenset({'overpass', 'google', 'nominatim'})
+
 
 def meters_to_miles(m):
     return m * 0.000621371
@@ -942,8 +952,9 @@ class MarketClustering(FlowComponent):
             plus ``centroid_city``, ``centroid_state``, ``centroid_county``
             and ``centroid_postcode``. The point resolved is
             ``centroid_lat``/``centroid_lon`` itself — the market's centre,
-            not a member store — at **one Overpass query per market**,
-            issued once the layout is final.
+            not a member store — at **one geocoder query per market**,
+            issued once the layout is final, against the backend chosen by
+            ``geocoding_backend``.
 
             A centroid is a geometric mean and can land on a parking lot or
             an empty field: a point with nothing addressable nearby degrades
@@ -960,6 +971,33 @@ class MarketClustering(FlowComponent):
             rotated through on retry.
         geocode_concurrency (int, default 8): Maximum in-flight
             reverse-geocode queries.
+        geocoding_backend (str, default ``'overpass'``): Reverse geocoder used
+            by ``resolve_centroid_location``. ``'overpass'`` queries
+            ``overpass_url``; ``'google'`` uses the Google Geocoding API
+            (paid, most accurate; needs ``google_api_key`` or
+            ``GOOGLE_PLACES_API_KEY``); ``'nominatim'`` uses OpenStreetMap's
+            Nominatim — the public server by default, throttled to one
+            request per second as its usage policy requires (~2 minutes for
+            120 markets). Google and Nominatim retry HTTP 429/5xx (and
+            Google's ``OVER_QUERY_LIMIT``) with exponential backoff,
+            honouring ``Retry-After``.
+        google_api_key (str, optional): Key for ``geocoding_backend='google'``;
+            defaults to ``GOOGLE_PLACES_API_KEY`` from the configuration.
+        nominatim_url (str, default public server): Nominatim base URL, e.g.
+            a self-hosted ``http://localhost:8080``.
+        nominatim_email (str, optional): Contact address sent to Nominatim,
+            recommended by the public server's usage policy.
+        nominatim_user_agent (str, optional): Identifying ``User-Agent`` for
+            Nominatim; defaults to ``flowtask/<version>``.
+        nominatim_min_interval (float, default 1.0): Seconds between Nominatim
+            requests. Keep 1.0 on the public server; ``0`` for a self-hosted
+            instance.
+        routing_backend (str, optional): Backend for the road-mile lookups
+            made by the sub-cluster anchoring and fly-out probe passes:
+            ``'valhalla'``, ``'osrm'`` or ``'geodesic'`` (offline
+            great-circle × detour factor, zero network calls). Defaults to
+            ``ROUTING_BACKEND`` from the configuration. The
+            ``no_clustering`` path never routes, whatever this is set to.
         isolation_values (list, optional): Values of ``isolation_column``
             forming the isolated partition. Stores inside and outside the
             partition are clustered separately and NEVER share a market —
@@ -1864,6 +1902,40 @@ class MarketClustering(FlowComponent):
         else:
             self.overpass_url_fallback = list(_overpass_fallback)
         self.geocode_concurrency: int = kwargs.pop('geocode_concurrency', 8)
+        # Which reverse geocoder resolve_centroid_location talks to.
+        self.geocoding_backend: str = str(
+            kwargs.pop('geocoding_backend', 'overpass') or 'overpass'
+        ).strip().lower()
+        if self.geocoding_backend not in GEOCODING_BACKENDS:
+            raise ConfigError(
+                f"geocoding_backend must be one of {sorted(GEOCODING_BACKENDS)}, "
+                f"got {self.geocoding_backend!r}"
+            )
+        self.google_api_key: Optional[str] = (
+            kwargs.pop('google_api_key', None) or GOOGLE_PLACES_API_KEY
+        )
+        if (
+            self.resolve_centroid_location
+            and self.geocoding_backend == 'google'
+            and not self.google_api_key
+        ):
+            raise ConfigError(
+                "geocoding_backend='google' needs google_api_key "
+                "(or GOOGLE_PLACES_API_KEY in the environment)"
+            )
+        self.nominatim_url: str = kwargs.pop('nominatim_url', DEFAULT_NOMINATIM_URL)
+        self.nominatim_email: Optional[str] = kwargs.pop('nominatim_email', None)
+        self.nominatim_user_agent: str = kwargs.pop(
+            'nominatim_user_agent', DEFAULT_NOMINATIM_USER_AGENT
+        )
+        self.nominatim_min_interval: float = float(
+            kwargs.pop('nominatim_min_interval', PUBLIC_MIN_INTERVAL)
+        )
+
+        # Road-mile backend for the sub-cluster / fly-out passes. None keeps
+        # RoutingService's configured default (ROUTING_BACKEND); 'geodesic'
+        # runs them fully offline, without a Valhalla instance.
+        self.routing_backend: Optional[str] = kwargs.pop('routing_backend', None)
 
         # -- Global employee-budget mode (FEAT-240) --------------------------
         # A hard cap on total hires for the entire run. Its presence (with
@@ -5284,7 +5356,7 @@ class MarketClustering(FlowComponent):
         n_unplaced = 0
         n_beyond_cap = 0
         stores_beyond_cap = 0
-        async with RoutingService() as routing:
+        async with RoutingService(backend=self.routing_backend) as routing:
             for subcluster in subclusters:
                 medoid = subcluster['medoid']
                 candidates = sorted(
@@ -5536,7 +5608,7 @@ class MarketClustering(FlowComponent):
                 cid = self._data.at[idx, self._cluster_id]
                 by_market.setdefault(cid, []).append(idx)
 
-            async with RoutingService() as routing:
+            async with RoutingService(backend=self.routing_backend) as routing:
                 for cid in sorted(by_market.keys(), key=str):
                     idxs = sorted(by_market[cid])
                     centroid = centroids.get(cid)
@@ -9565,10 +9637,51 @@ class MarketClustering(FlowComponent):
             points[cid] = (float(lat), float(lon))
         return points
 
+    def _geocoder_label(self) -> str:
+        """Human-readable backend + endpoint, for the resolution logs."""
+        if self.geocoding_backend == 'google':
+            return "Google Geocoding"
+        if self.geocoding_backend == 'nominatim':
+            return f"Nominatim ({self.nominatim_url})"
+        return f"Overpass ({self.overpass_url})"
+
+    def _build_reverse_geocoder(
+        self,
+    ) -> Union[OverpassReverseGeocoder, GoogleReverseGeocoder, NominatimReverseGeocoder]:
+        """Instantiate the reverse geocoder selected by `geocoding_backend`.
+
+        Returns:
+            An un-entered geocoder; use it with ``async with``. All three
+            share the ``reverse_many`` contract and return
+            `ReverseGeocodeResult` values.
+        """
+        if self.geocoding_backend == 'google':
+            return GoogleReverseGeocoder(
+                api_key=self.google_api_key,
+                concurrency=self.geocode_concurrency,
+            )
+        if self.geocoding_backend == 'nominatim':
+            # The public server allows one request per second; the
+            # min_interval throttle already serialises, so concurrency
+            # only matters for a self-hosted instance with no throttle.
+            return NominatimReverseGeocoder(
+                url=self.nominatim_url,
+                email=self.nominatim_email,
+                user_agent=self.nominatim_user_agent,
+                min_interval=self.nominatim_min_interval,
+                concurrency=self.geocode_concurrency,
+            )
+        return OverpassReverseGeocoder(
+            url=self.overpass_url,
+            fallback_urls=self.overpass_url_fallback,
+            concurrency=self.geocode_concurrency,
+        )
+
     async def _resolve_centroid_locations(self) -> None:
         """Reverse-geocode each market's centroid into a street address.
 
-        One Overpass query per market — the centroid itself, not a member
+        One query per market against `geocoding_backend` (Overpass, Google
+        or Nominatim) — the centroid itself, not a member
         store — de-duplicated and run with bounded concurrency, so a market
         of 400 stores still costs exactly one lookup.
 
@@ -9593,22 +9706,18 @@ class MarketClustering(FlowComponent):
             )
             return
 
+        label = self._geocoder_label()
         self._logger.info(
             f"Resolving centroid location for {len(points)} markets via "
-            f"Overpass ({self.overpass_url})"
+            f"{label}"
         )
         try:
-            async with OverpassReverseGeocoder(
-                url=self.overpass_url,
-                fallback_urls=self.overpass_url_fallback,
-                concurrency=self.geocode_concurrency,
-            ) as geocoder:
+            async with self._build_reverse_geocoder() as geocoder:
                 resolved = await geocoder.reverse_many(points.values())
         except Exception as exc:  # noqa: BLE001 - never lose a layout over a label
             self._logger.warning(
                 f"Centroid location resolution failed against "
-                f"{self.overpass_url} ({exc}); every centroid_address will "
-                f"be empty."
+                f"{label} ({exc}); every centroid_address will be empty."
             )
             return
 
@@ -9987,7 +10096,7 @@ class MarketClustering(FlowComponent):
         partition = self._partition_mask(self._data)
         total = 0
         for _ in range(max(1, max_rounds)):
-            markets = self._data.loc[idx, self._cluster_id].to_numpy()
+            markets = self._data.loc[idx, self._cluster_id].to_numpy(copy=True)
             # Full headcount (including sub-cluster rows) for capacity
             # checks — they count toward the market even though they
             # cannot be moved by this pass.

{flowtask-5.12.19 → flowtask-5.13.1}/flowtask/components/OpenStreetMap.py

@@ -964,6 +964,8 @@ class OpenStreetMap(FlowComponent):
                 clon = float(row[self.lon_column])
             except (TypeError, ValueError, KeyError):
                 return idx, None
+            if pd.isna(clat) or pd.isna(clon):
+                return idx, None
             query = self._build_geocode_query(row, clat, clon)
             if query is None:
                 return idx, None

{flowtask-5.12.19 → flowtask-5.13.1}/flowtask/components/ParrotAgent.py

@@ -452,7 +452,10 @@ class ParrotAgent(ParrotAgentConfigMixin, AgentBase, FlowComponent):
         # keeps its fields inside `output_column` rather than as columns of
         # their own, so look there too — otherwise `attach_columns` would work
         # per row (where the result is merged into the context) but not here.
-        for column in {c for ch in config.channels for c in ch.attach_columns}:
+        columns = {c for ch in config.channels for c in ch.attach_columns}
+        if config.storage is not None:
+            columns |= set(config.storage.columns)
+        for column in columns:
             values = self._collect_paths(df, column)
             if values:
                 context[column] = values[: config.max_attachments]

{flowtask-5.12.19 → flowtask-5.13.1}/flowtask/components/SchedulingVisits.py

@@ -564,7 +564,7 @@ class SchedulingVisits(FlowComponent):
         `_pack_visits()` relies on to pick the ISO-week vs. monthly window.
         """
         frequency = visit_frequency
-        if cadence:
+        if isinstance(cadence, str) and cadence:
             parsed = self._parse_cadence(cadence)
             if parsed:
                 frequency = parsed[1]  # only the frequency label, not the rule
@@ -591,7 +591,7 @@ class SchedulingVisits(FlowComponent):
         # Uses _parse_cadence() which regexes the full leading integer —
         # the old ``int(cadence[0])`` parsed only the first character, so
         # ``"10xWeek"`` silently became 1 visit (defect 4 fix).
-        if cadence:
+        if isinstance(cadence, str) and cadence:
             parsed = self._parse_cadence(cadence)
             if parsed:
                 visit_rule, visit_frequency = parsed

{flowtask-5.12.19 → flowtask-5.13.1}/flowtask/components/TableSchema.py

@@ -287,7 +287,7 @@ class TableSchema(QSSupport, FlowComponent):
                     **arguments,
                 )
             else:
-                self.params = {"infer_datetime_format": True}
+                self.params = {}
                 arguments = {**self.params}
                 if hasattr(self, "pd_args") and isinstance(self.pd_args, dict):
                     arguments = {**self.params, **self.pd_args}

{flowtask-5.12.19 → flowtask-5.13.1}/flowtask/components/TransformRows/TransformRows.py

@@ -556,7 +556,7 @@ class TransformRows(FlowComponent):
         if hasattr(elem, "clean_str"):
             df.is_copy = None
             u = df.select_dtypes(include=["object", "string"])
-            u = u.applymap(lambda x: x.strip() if isinstance(x, str) else x)
+            u = u.map(lambda x: x.strip() if isinstance(x, str) else x)
             df[u.columns] = df[u.columns].fillna("")
         if hasattr(elem, "drop_empty"):
             # First filter out those rows which

{flowtask-5.12.19 → flowtask-5.13.1}/flowtask/components/TransformRows/functions.py

@@ -425,7 +425,7 @@ def drop_timezone(
             column = field
 
         series = df[column]
-        if pandas.api.types.is_datetime64tz_dtype(series):
+        if isinstance(series.dtype, pandas.DatetimeTZDtype):
             # This is a regular tz-aware pandas Series
             df[field] = series.dt.tz_localize(None)
             return df
@@ -1427,7 +1427,7 @@ def to_integer(df: pandas.DataFrame, field: str):
         df[field] = pandas.to_numeric(df[field], errors="coerce")
         # Replace non-finite values (NaN, inf, -inf) with pd.NA before converting to int64
         df[field] = df[field].where(np.isfinite(df[field]), pandas.NA)
-        df[field] = df[field].astype("Int64", copy=False)
+        df[field] = df[field].astype("Int64")
     except TypeError as err:
         print(f"TO Integer {field}: Unable to safely cast non-equivalent float to int.")
         numeric_col = pandas.to_numeric(df[field], errors="coerce")
@@ -1458,7 +1458,7 @@ def to_float(
     :return: Modified pandas DataFrame with the values converted to floats.
     """
     try:
-        df[field] = pandas.to_numeric(df[field], errors="coerce").astype("float64", copy=False)
+        df[field] = pandas.to_numeric(df[field], errors="coerce").astype("float64")
     except Exception as err:
         print(f"TO Float {field}: An error occurred during conversion.")
         print(err)