resolvekit 0.1.5__tar.gz → 0.1.7__tar.gz

{resolvekit-0.1.5 → resolvekit-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: resolvekit
-Version: 0.1.5
+Version: 0.1.7
 Summary: Entity and place resolution system that maps messy place/entity strings and codes to canonical entities
 Keywords: entity-resolution,geocoding,place-names,data-commons,iso-codes,offline,disambiguation,normalization
 Author: Jorge Rivera

{resolvekit-0.1.5 → resolvekit-0.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "resolvekit"
-version = "0.1.5"
+version = "0.1.7"
 description = "Entity and place resolution system that maps messy place/entity strings and codes to canonical entities"
 requires-python = ">=3.12"
 

{resolvekit-0.1.5 → resolvekit-0.1.7}/src/resolvekit/core/api/loading/module_catalog.py

@@ -134,41 +134,26 @@ def _load_and_separate_datapacks(
     return base_packs, overlay_packs
 
 
-def _remote_dependency_uncached(
-    module_id: str,
-    available: dict[str, Path],
-    manifest_overrides: dict[str, dict[str, object]],
-) -> bool:
-    """Return True if ``module_id`` is a remote-distribution module whose data
-    is not in the local cache.
-
-    Such a dependency may be absent from a load set without error: remote
-    packs the user hasn't downloaded are not hard errors (partial caches are
-    first-class, and ``Resolver.auto()`` never triggers a network fetch).
-    Bundled dependencies and unknown module ids stay hard errors.
-    """
-    from resolvekit.core.module_registry import load_module_metadata
-    from resolvekit.core.remote import is_cached
-
-    if module_id not in available:
-        return False
-    path = available[module_id]
-    if not (path / "metadata.json").exists():
-        return False
-    metadata = load_module_metadata(module_id, path, overrides=manifest_overrides)
-    return metadata.distribution == "remote" and not is_cached(metadata)
-
-
 def _validate_module_dependencies(
     base_packs: dict[str, LoadedDataPack],
     overlay_packs: dict[str, LoadedDataPack],
     pack_filter: set[str],
 ) -> None:
-    from resolvekit.core.module_registry import get_manifest_overrides
-
+    """Log any declared ``module_dependencies`` absent from the load set.
+
+    ``module_dependencies`` are advisory cross-reference links, not hard load
+    requirements. An explicit selection is authoritative and ``auto()`` loads
+    whatever is locally available, so a declared dependency not being in the
+    load set is expected — partial loads are first-class, a deployed image may
+    ship a subset, and a dependency may simply not be installed in this
+    environment. None of that is an error here; it is logged for diagnostics.
+
+    (Naming an unknown module in the *request* is a different matter — that
+    raises ``DataModuleNotFoundError`` from :func:`_resolve_requested_module_paths`.
+    Hard structural requirements, overlay → base, are enforced separately by
+    :func:`_validate_overlay_relationships`.)
+    """
     available_module_ids = set(base_packs) | set(overlay_packs)
-    registry: dict[str, Path] | None = None
-    manifest_overrides: dict[str, dict[str, object]] | None = None
     for loaded in [*base_packs.values(), *overlay_packs.values()]:
         if pack_filter and loaded.pack_id not in pack_filter:
             continue
@@ -179,23 +164,12 @@ def _validate_module_dependencies(
             if module_id not in available_module_ids
         ]
         if missing:
-            # An absent dependency is only a hard error when its data could
-            # have been loaded — a declared dep on a remote pack the user
-            # hasn't downloaded is skipped, mirroring the auto-mode intent in
-            # _resolve_requested_module_paths.
-            if registry is None:
-                registry = list_available_modules()
-                manifest_overrides = get_manifest_overrides()
-            assert manifest_overrides is not None
-            missing = [
-                module_id
-                for module_id in missing
-                if not _remote_dependency_uncached(
-                    module_id, registry, manifest_overrides
-                )
-            ]
-        if missing:
-            raise MissingModuleDependencyError(loaded.module_id, missing)
+            logger.debug(
+                "Module %s declares dependencies absent from the load set: %s "
+                "(advisory; honoring authoritative selection)",
+                loaded.module_id,
+                ", ".join(sorted(missing)),
+            )
 
 
 def _validate_overlay_relationships(
@@ -290,29 +264,23 @@ def _resolve_requested_module_paths(
         resolved[module_id] = path
 
         metadata = load_module_metadata(module_id, path, overrides=manifest_overrides)
-        for dependency in metadata.module_dependencies:
-            if dependency in resolved:
-                continue
-            # In auto mode, silently skip dependencies whose data isn't
-            # locally available (remote packs the user hasn't downloaded
-            # are not hard errors — see v1-scope §225). In explicit mode,
-            # likewise skip remote-uncached dependencies so requesting one
-            # module never transitively forces sibling downloads; unknown
-            # module ids are still queued so the queue-loop's own
-            # ``module_id not in available`` check raises
-            # ``DataModuleNotFoundError``.
-            if auto_mode and (
-                dependency not in available
-                or not _module_data_locally_available(
+        # ``module_dependencies`` are advisory cross-reference links, not load
+        # requirements. Expand them only in auto() mode, where the load set is
+        # "everything locally available" anyway (silently skipping remote packs
+        # the user hasn't downloaded — see v1-scope §225). Explicit ``module_ids``
+        # are AUTHORITATIVE: the load set is exactly what the caller named (plus
+        # overlay bases, which are structural), independent of cache or on-disk
+        # state — so resolution is identical on a dev box with extra packs
+        # downloaded and on a lean deployment that bakes only the named modules.
+        if auto_mode:
+            for dependency in metadata.module_dependencies:
+                if dependency in resolved:
+                    continue
+                if dependency not in available or not _module_data_locally_available(
                     dependency, available[dependency], manifest_overrides
-                )
-            ):
-                continue
-            if not auto_mode and _remote_dependency_uncached(
-                dependency, available, manifest_overrides
-            ):
-                continue
-            queue.append(dependency)
+                ):
+                    continue
+                queue.append(dependency)
         if metadata.is_overlay:
             for dependency in metadata.base_module_ids or []:
                 if dependency in resolved:

{resolvekit-0.1.5 → resolvekit-0.1.7}/src/resolvekit/core/api/resolver.py

@@ -882,7 +882,16 @@ class Resolver:
 
         Args:
             module_ids: Specific module IDs to load (e.g. ``["geo.countries"]``).
-                Pass ``None`` to load all installed modules (same as ``auto()``).
+                Authoritative: the load set is exactly these modules. Declared
+                ``module_dependencies`` are advisory cross-references and are
+                NOT auto-loaded — name every module you want (e.g.
+                ``["geo.cities", "geo.countries"]`` for city resolution backed
+                by country context). The load set therefore depends only on this
+                argument, never on which packs happen to be cached or shipped,
+                so resolution is identical on a dev box and a lean deployment.
+                Overlay base modules are the one exception (an overlay is not a
+                standalone dataset, so its base is always pulled in). Pass
+                ``None`` to load all installed modules (same as ``auto()``).
             domains: Which domain packs to enable (default: all in modules).
             routing_mode: How to route queries (see ``Resolver.__init__`` for full docs).
             trace: Whether to collect trace events.
@@ -1032,8 +1041,9 @@ class Resolver:
         )
 
     # -- Country-level geo module IDs for the lite preset --
-    # Deliberately excludes geo.admin1 and deeper tiers whose dependency
-    # chains (admin2, admin3, cities …) trigger heavy SQLite composition.
+    # Deliberately excludes geo.admin1 and the deeper admin / cities tiers to
+    # keep cold-start time and resident memory small. Selection is authoritative,
+    # so the load set is exactly these IDs — naming a tier loads only that tier.
     # To add admin-1 coverage, pass module_ids=["geo.countries", "geo.admin1"].
     _LITE_GEO_MODULE_IDS: tuple[str, ...] = (
         "geo.countries",

{resolvekit-0.1.5 → resolvekit-0.1.7}/src/resolvekit/core/byod/cache.py

@@ -19,11 +19,11 @@ A cache hit is ``dir.exists() and (dir / "metadata.json").exists()``.
 Atomicity and cleanup
 ---------------------
 On a cache miss the build writes to a sibling ``<key>.tmp`` directory, then
-``os.replace(tmp, dir)`` atomically moves it. The superseded temp dir is
-removed with ``shutil.rmtree(tmp, ignore_errors=True)`` (matching the pattern
-in ``composed_sqlite.py:326``).  When ``cache=False``, the build writes to a
-fresh temp directory that is NOT moved into the cache — it is kept for the
-resolver's lifetime.
+``commit_build`` promotes it to the final location (first-writer-wins: if a
+valid pack already exists at the target it is kept and the redundant build is
+discarded; a corrupt leftover without ``metadata.json`` is cleared first).
+When ``cache=False``, the build writes to a fresh temp directory that is NOT
+moved into the cache — it is kept for the resolver's lifetime.
 """
 
 from __future__ import annotations
@@ -168,20 +168,46 @@ def prepare_build_dir(key: str, *, cache: bool) -> tuple[Path, Path | None]:
 
 
 def commit_build(build_dir: Path, final_dir: Path) -> None:
-    """Atomically promote *build_dir* to *final_dir* and clean up.
+    """Promote *build_dir* into *final_dir*, tolerating an existing pack.
 
-    Uses ``os.replace(build_dir, final_dir)`` for an atomic last-writer-wins
-    swap.  If the parent of *final_dir* does not exist it is created first.
+    The cache key is a content hash, so a pack already present at *final_dir* —
+    left by a concurrent build, a retry, or a re-submit of identical content —
+    is equivalent to the one just built. First writer wins: an existing valid
+    pack is kept and *build_dir* is discarded. A corrupt leftover (a directory
+    without ``metadata.json``) is cleared and replaced.
+
+    ``os.replace`` cannot rename a directory onto a non-empty one (POSIX raises
+    ENOTEMPTY / EEXIST), so the swap is attempted optimistically and the
+    populated-target case is recovered below. An ``OSError`` that does not
+    correspond to a populated *final_dir* (e.g. ENOSPC, a permission error) is
+    re-raised rather than silently swallowed.
 
     Args:
         build_dir: Temp directory where the build was written.
         final_dir: Target cache directory (``cached_pack_dir(key)``).
     """
     final_dir.parent.mkdir(parents=True, exist_ok=True)
-    os.replace(build_dir, final_dir)
-    # Belt-and-suspenders cleanup: ``shutil.rmtree`` with ignore_errors=True
-    # handles both cases (build_dir doesn't exist after replace, or final_dir
-    # was clobbered by a concurrent write) without raising.
+    try:
+        os.replace(build_dir, final_dir)
+    except OSError:
+        if is_cache_hit(final_dir):
+            # A concurrent build, retry, or re-submit already committed an
+            # equivalent pack; keep it and drop our redundant build below.
+            pass
+        elif final_dir.exists():
+            # Corrupt/incomplete leftover (no metadata.json): clear it and move
+            # our build in. If another writer races a valid pack into the slot
+            # first, accept that pack rather than surfacing the error.
+            shutil.rmtree(final_dir, ignore_errors=True)
+            try:
+                os.replace(build_dir, final_dir)
+            except OSError:
+                if not is_cache_hit(final_dir):
+                    raise
+        else:
+            # final_dir is absent, so the failure was not "target populated"
+            # (e.g. ENOSPC, EACCES). Surface it instead of hiding it.
+            raise
     shutil.rmtree(build_dir, ignore_errors=True)