pysof 0.2.0__tar.gz → 0.2.1__tar.gz

{pysof-0.2.0 → pysof-0.2.1}/Cargo.toml

@@ -17,13 +17,16 @@ crate-type = ["cdylib"]
 
 [dependencies]
 pyo3 = { version = ">=0.29", features = ["extension-module", "generate-import-lib"] }
-helios-sof = { path = "../sof", version = "0.2.0", default-features = false }
-helios-fhir = { path = "../fhir", version = "0.2.0", default-features = false }
+helios-sof = { path = "../sof", version = "0.2.1", default-features = false }
+helios-fhir = { path = "../fhir", version = "0.2.1", default-features = false }
 serde = { workspace = true }
 serde_json = { workspace = true }
 chrono = { version = "0.4", features = ["serde"] }
 pythonize = "0.29"
 csv = "1.3"
+# Drives helios-sof's async remote-resolve functions from the synchronous
+# PyO3 entry points via a current-thread runtime.
+tokio = { version = "1", default-features = false, features = ["rt", "net", "time"] }
 
 [features]
 default = ["R4"]

{pysof-0.2.0 → pysof-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pysof
-Version: 0.2.0
+Version: 0.2.1
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -176,6 +176,44 @@ result = pysof.run_view_definition_with_options(
 )
 ```
 
+### Remote `resolve()` (Trusted Servers)
+
+`resolve()` dereferences references against the input bundle by default. You can
+optionally let it fetch references that point at **explicitly trusted** FHIR
+servers and fold them into the resolution pool before rows are generated. This is
+**off by default** and gated by a strict allowlist (matching scheme + host + port
++ path-prefix; private/loopback addresses are blocked unless opted in).
+
+```python
+import pysof
+
+config = pysof.RemoteResolveConfig(
+    ["https://fhir.example.org/r4"],   # trusted base URLs (allowlist)
+    max_fetches=256,                    # per-run/-stream fetch cap
+    max_depth=1,                        # chained-reference rounds
+    allow_private_addresses=False,      # allow internal LBs (e.g. Traefik) by hostname
+    bearer_tokens={"fhir.example.org": "TOKEN"},  # optional per-host auth
+)
+
+# Or build it from SOF_RESOLVE_* environment variables:
+# config = pysof.RemoteResolveConfig.from_env()
+
+result = pysof.run_view_definition_remote(
+    view_definition, bundle, "json", config, fhir_version="R4"
+)
+
+# Streaming NDJSON with remote resolve() (one shared cache across chunks):
+stats = pysof.process_ndjson_to_file_remote(
+    view_definition, "input.ndjson", "output.json", "ndjson", config, chunk_size=1000
+)
+```
+
+When `config.is_active()` is `False` (disabled or empty allowlist) these behave
+exactly like their non-remote counterparts. Enabling remote resolution makes
+output depend on remote server state at run time. See the
+[SQL-on-FHIR guide](../../book/src/ch06-sql-on-fhir.md) for the full security
+model and configuration reference.
+
 ### Utility Functions
 
 ```python

{pysof-0.2.0 → pysof-0.2.1}/README.md

@@ -147,6 +147,44 @@ result = pysof.run_view_definition_with_options(
 )
 ```
 
+### Remote `resolve()` (Trusted Servers)
+
+`resolve()` dereferences references against the input bundle by default. You can
+optionally let it fetch references that point at **explicitly trusted** FHIR
+servers and fold them into the resolution pool before rows are generated. This is
+**off by default** and gated by a strict allowlist (matching scheme + host + port
++ path-prefix; private/loopback addresses are blocked unless opted in).
+
+```python
+import pysof
+
+config = pysof.RemoteResolveConfig(
+    ["https://fhir.example.org/r4"],   # trusted base URLs (allowlist)
+    max_fetches=256,                    # per-run/-stream fetch cap
+    max_depth=1,                        # chained-reference rounds
+    allow_private_addresses=False,      # allow internal LBs (e.g. Traefik) by hostname
+    bearer_tokens={"fhir.example.org": "TOKEN"},  # optional per-host auth
+)
+
+# Or build it from SOF_RESOLVE_* environment variables:
+# config = pysof.RemoteResolveConfig.from_env()
+
+result = pysof.run_view_definition_remote(
+    view_definition, bundle, "json", config, fhir_version="R4"
+)
+
+# Streaming NDJSON with remote resolve() (one shared cache across chunks):
+stats = pysof.process_ndjson_to_file_remote(
+    view_definition, "input.ndjson", "output.json", "ndjson", config, chunk_size=1000
+)
+```
+
+When `config.is_active()` is `False` (disabled or empty allowlist) these behave
+exactly like their non-remote counterparts. Enabling remote resolution makes
+output depend on remote server state at run time. See the
+[SQL-on-FHIR guide](../../book/src/ch06-sql-on-fhir.md) for the full security
+model and configuration reference.
+
 ### Utility Functions
 
 ```python

{pysof-0.2.0 → pysof-0.2.1}/crates/fhir/Cargo.toml

@@ -24,9 +24,9 @@ xml = ["helios-serde-support/xml"]
 serde = { workspace = true }
 serde_json = { workspace = true, features = ["raw_value"] }
 clap = { version = "4.0", features = ["derive"] }
-helios-fhir-macro = { path = "../fhir-macro", version = "0.2.0" }
-helios-serde-support = { path = "../serde-support", version = "0.2.0" }
-helios-fhirpath-support = { path = "../fhirpath-support", version = "0.2.0" }
+helios-fhir-macro = { path = "../fhir-macro", version = "0.2.1" }
+helios-serde-support = { path = "../serde-support", version = "0.2.1" }
+helios-fhirpath-support = { path = "../fhirpath-support", version = "0.2.1" }
 time = "0.3"
 chrono = { workspace = true }
 # Re-add serde-with-arbitrary-precision, keep macros

{pysof-0.2.0 → pysof-0.2.1}/crates/fhir-macro/Cargo.toml

@@ -20,4 +20,4 @@ proc-macro2 = "1.0"
 serde = { workspace = true }
 serde_json = { workspace = true }
 heck = "0.5" # For case conversion
-helios-fhirpath-support = { path = "../fhirpath-support", version = "0.2.0" }
+helios-fhirpath-support = { path = "../fhirpath-support", version = "0.2.1" }

{pysof-0.2.0 → pysof-0.2.1}/crates/fhirpath/Cargo.toml

@@ -18,8 +18,8 @@ R5 = ["helios-fhir/R5"]
 R6 = ["helios-fhir/R6"]
 
 [dependencies]
-helios-fhir = { path = "../fhir", version = "0.2.0", default-features = false }
-helios-fhirpath-support = { path = "../fhirpath-support", version = "0.2.0" }
+helios-fhir = { path = "../fhir", version = "0.2.1", default-features = false }
+helios-fhirpath-support = { path = "../fhirpath-support", version = "0.2.1" }
 chumsky = "0.10"
 roxmltree = "0.20"
 chrono = { workspace = true } # For date/time parsing and functions

{pysof-0.2.0 → pysof-0.2.1}/crates/fhirpath/src/evaluator.rs

@@ -423,6 +423,25 @@ impl EvaluationContext {
             .push(resource);
     }
 
+    /// Replaces the pool of resources available for resolution.
+    ///
+    /// This swaps the (`Arc`-shared) set of resources that `resolve()` searches —
+    /// see [`crate::resolve_function`] — **without** changing `this`, the FHIR
+    /// version, or `%context` / `%resource` / `%rootResource` semantics. Those all
+    /// derive from `this` (with `resources[0]` used only as a fallback when `this`
+    /// is `None`), so callers that have already set `this` to the resource under
+    /// evaluation can widen the resolution pool freely.
+    ///
+    /// SQL-on-FHIR uses this to expose the *entire input bundle* so that
+    /// `Reference.resolve()` can reach sibling resources elsewhere in the bundle,
+    /// not just the resource currently being processed and its `contained`
+    /// children. Sharing via `Arc` keeps this cheap across the many per-resource
+    /// (and per-iteration) contexts SOF creates, and it survives `Clone` into
+    /// lambda/child contexts.
+    pub fn set_resolution_scope(&mut self, resources: Arc<Vec<FhirResource>>) {
+        self.resources = resources;
+    }
+
     /// Sets a variable in the context to a string value
     ///
     /// This method is provided for backward compatibility with code that expects

{pysof-0.2.0 → pysof-0.2.1}/crates/pysof/Cargo.toml

@@ -18,13 +18,16 @@ crate-type = ["cdylib"]
 
 [dependencies]
 pyo3 = { version = ">=0.29", features = ["extension-module", "generate-import-lib"] }
-helios-sof = { path = "../sof", version = "0.2.0", default-features = false }
-helios-fhir = { path = "../fhir", version = "0.2.0", default-features = false }
+helios-sof = { path = "../sof", version = "0.2.1", default-features = false }
+helios-fhir = { path = "../fhir", version = "0.2.1", default-features = false }
 serde = { workspace = true }
 serde_json = { workspace = true }
 chrono = { version = "0.4", features = ["serde"] }
 pythonize = "0.29"
 csv = "1.3"
+# Drives helios-sof's async remote-resolve functions from the synchronous
+# PyO3 entry points via a current-thread runtime.
+tokio = { version = "1", default-features = false, features = ["rt", "net", "time"] }
 
 [features]
 default = ["R4"]

{pysof-0.2.0 → pysof-0.2.1}/crates/pysof/README.md

@@ -147,6 +147,44 @@ result = pysof.run_view_definition_with_options(
 )
 ```
 
+### Remote `resolve()` (Trusted Servers)
+
+`resolve()` dereferences references against the input bundle by default. You can
+optionally let it fetch references that point at **explicitly trusted** FHIR
+servers and fold them into the resolution pool before rows are generated. This is
+**off by default** and gated by a strict allowlist (matching scheme + host + port
++ path-prefix; private/loopback addresses are blocked unless opted in).
+
+```python
+import pysof
+
+config = pysof.RemoteResolveConfig(
+    ["https://fhir.example.org/r4"],   # trusted base URLs (allowlist)
+    max_fetches=256,                    # per-run/-stream fetch cap
+    max_depth=1,                        # chained-reference rounds
+    allow_private_addresses=False,      # allow internal LBs (e.g. Traefik) by hostname
+    bearer_tokens={"fhir.example.org": "TOKEN"},  # optional per-host auth
+)
+
+# Or build it from SOF_RESOLVE_* environment variables:
+# config = pysof.RemoteResolveConfig.from_env()
+
+result = pysof.run_view_definition_remote(
+    view_definition, bundle, "json", config, fhir_version="R4"
+)
+
+# Streaming NDJSON with remote resolve() (one shared cache across chunks):
+stats = pysof.process_ndjson_to_file_remote(
+    view_definition, "input.ndjson", "output.json", "ndjson", config, chunk_size=1000
+)
+```
+
+When `config.is_active()` is `False` (disabled or empty allowlist) these behave
+exactly like their non-remote counterparts. Enabling remote resolution makes
+output depend on remote server state at run time. See the
+[SQL-on-FHIR guide](../../book/src/ch06-sql-on-fhir.md) for the full security
+model and configuration reference.
+
 ### Utility Functions
 
 ```python

pysof-0.2.1/crates/pysof/python-tests/test_remote_resolve.py

@@ -0,0 +1,141 @@
+"""Tests for the remote resolve() Python bindings.
+
+These exercise the RemoteResolveConfig class and the *_remote entry points
+without requiring network access: an *inactive* config (no allowlist) drives the
+same async pipeline as the active one but performs no fetches, so it still does
+bundle-level (in-scope) resolution. End-to-end remote fetching against a server is
+covered by the Rust integration tests (crates/sof/tests/resolve_remote_tests.rs).
+"""
+
+import json
+from typing import Any, Dict
+
+import pysof
+
+
+def encounter_with_subject_view() -> Dict[str, Any]:
+    return {
+        "resourceType": "ViewDefinition",
+        "status": "active",
+        "resource": "Encounter",
+        "select": [
+            {"column": [{"name": "encounter_id", "path": "id"}]},
+            {
+                "forEach": "subject.resolve()",
+                "column": [
+                    {"name": "patient_id", "path": "id"},
+                    {"name": "patient_family", "path": "name.family"},
+                ],
+            },
+        ],
+    }
+
+
+def bundle_with_sibling_patient() -> Dict[str, Any]:
+    return {
+        "resourceType": "Bundle",
+        "type": "collection",
+        "entry": [
+            {
+                "resource": {
+                    "resourceType": "Patient",
+                    "id": "pat-1",
+                    "name": [{"family": "Sibling"}],
+                }
+            },
+            {
+                "resource": {
+                    "resourceType": "Encounter",
+                    "id": "enc-1",
+                    "status": "finished",
+                    "subject": {"reference": "Patient/pat-1"},
+                }
+            },
+        ],
+    }
+
+
+def test_remote_symbols_exported() -> None:
+    for name in [
+        "RemoteResolveConfig",
+        "run_view_definition_remote",
+        "process_ndjson_to_file_remote",
+    ]:
+        assert name in pysof.__all__
+        assert hasattr(pysof, name)
+
+
+def test_remote_resolve_config_construction() -> None:
+    cfg = pysof.RemoteResolveConfig(
+        ["https://fhir.example.org/r4"],
+        max_fetches=10,
+        max_depth=2,
+        allow_private_addresses=True,
+        bearer_tokens={"fhir.example.org": "tok"},
+    )
+    assert cfg.is_active() is True  # enabled (default) + non-empty allowlist
+
+    # Disabled or empty allowlist => inactive.
+    assert pysof.RemoteResolveConfig([]).is_active() is False
+    assert (
+        pysof.RemoteResolveConfig(
+            ["https://fhir.example.org/r4"], enabled=False
+        ).is_active()
+        is False
+    )
+
+    # from_env() is constructible and inactive by default (no env set).
+    assert isinstance(pysof.RemoteResolveConfig.from_env(), pysof.RemoteResolveConfig)
+
+
+def test_run_view_definition_remote_inactive_does_in_bundle_resolution() -> None:
+    # With an inactive remote config (no allowlist), no fetch happens, but the
+    # bundle-level resolution pool still resolves Encounter.subject to the sibling
+    # Patient in the same bundle.
+    cfg = pysof.RemoteResolveConfig([])  # inactive
+    result = pysof.run_view_definition_remote(
+        encounter_with_subject_view(),
+        bundle_with_sibling_patient(),
+        "json",
+        cfg,
+    )
+    rows = json.loads(result)
+    assert len(rows) == 1
+    assert rows[0]["encounter_id"] == "enc-1"
+    assert rows[0]["patient_id"] == "pat-1"
+    assert rows[0]["patient_family"] == "Sibling"
+
+
+def test_process_ndjson_to_file_remote_inactive(tmp_path: Any) -> None:
+    # Two Encounters referencing patients that are not in the stream; with an
+    # inactive config nothing is fetched, so the resolved columns are null, but
+    # the call succeeds and returns stats.
+    input_path = tmp_path / "in.ndjson"
+    output_path = tmp_path / "out.json"
+    lines = [
+        json.dumps(
+            {
+                "resourceType": "Encounter",
+                "id": f"enc-{i}",
+                "status": "finished",
+                "subject": {"reference": f"Patient/p{i}"},
+            }
+        )
+        for i in range(2)
+    ]
+    input_path.write_text("\n".join(lines))
+
+    cfg = pysof.RemoteResolveConfig([])  # inactive
+    stats = pysof.process_ndjson_to_file_remote(
+        encounter_with_subject_view(),
+        str(input_path),
+        str(output_path),
+        "json",
+        cfg,
+        chunk_size=1,
+    )
+    assert stats["resources_processed"] == 2
+    rows = json.loads(output_path.read_text())
+    assert len(rows) == 2
+    for row in rows:
+        assert row["patient_family"] is None