hubble-sdk-python 0.3.1__tar.gz → 0.3.2__tar.gz

{hubble_sdk_python-0.3.1 → hubble_sdk_python-0.3.2}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.2](https://github.com/hubble-dot-ai/hubble-sdks/compare/hubble-sdk-python-v0.3.1...hubble-sdk-python-v0.3.2) (2026-11-05)
+
+
+### Bug Fixes
+
+* expose combined PDF exports through high-level clients ([#85](https://github.com/hubble-dot-ai/hubble-sdks/issues/85)) ([1365b65](https://github.com/hubble-dot-ai/hubble-sdks/commit/1365b65248e81137b8f814cc895440e1ba009400))
+
 ## [0.3.1](https://github.com/hubble-dot-ai/hubble-sdks/compare/hubble-sdk-python-v0.3.0...hubble-sdk-python-v0.3.1) (2026-11-05)
 
 

{hubble_sdk_python-0.3.1 → hubble_sdk_python-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hubble-sdk-python
-Version: 0.3.1
+Version: 0.3.2
 Summary: Python client for the Hubble Patient Access API.
 Project-URL: Homepage, https://github.com/hubble-dot-ai/hubble-sdks
 Project-URL: Repository, https://github.com/hubble-dot-ai/hubble-sdks
@@ -81,6 +81,27 @@ export = hub.export_pdf(consent_id, connection=connection_id)         # one sour
 
 Reuse one `Hubble` client so its token is reused too.
 
+### Combined PDF exports
+
+Pass `version`, `connection`, and `combined=True` to download one PDF containing
+the source's summary and documents. The helper requests background generation,
+waits for completion, and downloads the file.
+
+```python
+export = hub.export_pdf(
+    consent_id,
+    version="2026-11-01",
+    connection=connection_id,
+    combined=True,
+)
+# export.content contains the PDF bytes; export.content_type is "application/pdf".
+```
+
+`session.export_pdf` accepts the same options without the consent ID. With a
+version and `combined` omitted or false, the result is a records archive (ZIP).
+Calls without a version keep their existing behavior. `timeout` controls the
+wait for background generation in seconds and defaults to ten minutes.
+
 ### The device flow
 
 Existing integrations can keep using the device flow, which waits for the

{hubble_sdk_python-0.3.1 → hubble_sdk_python-0.3.2}/README.md

@@ -49,6 +49,27 @@ export = hub.export_pdf(consent_id, connection=connection_id)         # one sour
 
 Reuse one `Hubble` client so its token is reused too.
 
+### Combined PDF exports
+
+Pass `version`, `connection`, and `combined=True` to download one PDF containing
+the source's summary and documents. The helper requests background generation,
+waits for completion, and downloads the file.
+
+```python
+export = hub.export_pdf(
+    consent_id,
+    version="2026-11-01",
+    connection=connection_id,
+    combined=True,
+)
+# export.content contains the PDF bytes; export.content_type is "application/pdf".
+```
+
+`session.export_pdf` accepts the same options without the consent ID. With a
+version and `combined` omitted or false, the result is a records archive (ZIP).
+Calls without a version keep their existing behavior. `timeout` controls the
+wait for background generation in seconds and defaults to ten minutes.
+
 ### The device flow
 
 Existing integrations can keep using the device flow, which waits for the

{hubble_sdk_python-0.3.1 → hubble_sdk_python-0.3.2}/hubble_sdk/_hubble.py

@@ -132,6 +132,19 @@ def _require_fhir_namespace(base_url: str, url: httpx.URL, shown: str) -> None:
         raise HubbleError(f"Invalid FHIR path: {shown!r}")
 
 
+def _pdf_export_url(
+    base_url: str, connection: str | None, version: str | None, combined: bool
+) -> httpx.URL:
+    if combined and (not version or not connection):
+        raise HubbleError("A combined PDF requires version and connection.")
+    url = _fhir_url(base_url, "Patient/$pdf")
+    if connection is not None:
+        url = url.copy_set_param("connection", connection)
+    if combined:
+        url = url.copy_set_param("combined", "true")
+    return url
+
+
 def _pdf_export(
     resp: httpx.Response, file: httpx.Response | None = None, version: str | None = None
 ) -> PdfExport:
@@ -330,6 +343,7 @@ class Hubble:
         *,
         connection: str | None = None,
         version: str | None = None,
+        combined: bool = False,
         timeout: float = _EXPORT_TIMEOUT,
     ) -> PdfExport:
         """The patient's records as PDF via ``Patient/$pdf``: a ZIP of per-source
@@ -337,10 +351,10 @@ class Hubble:
 
         Pass ``version`` (a ``Hubble-Version``, such as ``"2026-11-01"``) for that
         version's export instead. It is built in the background, so this waits up
-        to ``timeout`` seconds for it, then downloads it."""
-        url = _fhir_url(self.base_url, "Patient/$pdf")
-        if connection is not None:
-            url = url.copy_set_param("connection", connection)
+        to ``timeout`` seconds for it, then downloads it. Set ``combined=True``
+        with ``version`` and ``connection`` for one PDF containing that source's
+        summary and documents instead of the archive. Defaults to false."""
+        url = _pdf_export_url(self.base_url, connection, version, combined)
         if version is None:
             return _pdf_export(self._consent_get(consent_id, url, None))
         return _versioned_pdf_export(
@@ -676,6 +690,7 @@ class PatientSession:
         *,
         connection: str | None = None,
         version: str | None = None,
+        combined: bool = False,
         timeout: float = _EXPORT_TIMEOUT,
     ) -> PdfExport:
         """Export the patient's records as PDF via ``Patient/$pdf``.
@@ -689,11 +704,11 @@ class PatientSession:
 
         Pass ``version`` (a ``Hubble-Version``, such as ``"2026-11-01"``) for that
         version's export instead. It is built in the background, so this waits up
-        to ``timeout`` seconds for it, then downloads it."""
+        to ``timeout`` seconds for it, then downloads it. Set ``combined=True``
+        with ``version`` and ``connection`` for one PDF containing that source's
+        summary and documents instead of the archive. Defaults to false."""
         retry = self.refresh_token is not None
-        url = _fhir_url(self._hubble.base_url, "Patient/$pdf")
-        if connection is not None:
-            url = url.copy_set_param("connection", connection)
+        url = _pdf_export_url(self._hubble.base_url, connection, version, combined)
         if version is None:
             return _pdf_export(self._fhir_request(url, retry))
         return _versioned_pdf_export(
@@ -779,8 +794,8 @@ class PdfExport:
     ``content`` is the raw body — a ZIP of per-source PDFs (with a
     ``manifest.json`` naming each file and marking it complete/partial/failed),
     or a single PDF when ``connection`` was set. With a ``version``, it is that
-    version's export, described in the API reference. The counts come from the
-    response headers; a non-zero ``sources_failed`` means some records are
+    version's archive, or one PDF if ``combined=True`` was requested. The counts
+    come from the response headers; a non-zero ``sources_failed`` means some records are
     missing. ``version`` is the ``Hubble-Version`` served, or ``None`` when none
     was asked for."""
 

{hubble_sdk_python-0.3.1 → hubble_sdk_python-0.3.2}/pyproject.toml

@@ -3,7 +3,7 @@
 # none); this file and the build config are not.
 [project]
 name = "hubble-sdk-python"
-version = "0.3.1"
+version = "0.3.2"
 description = "Python client for the Hubble Patient Access API."
 readme = "README.md"
 requires-python = ">=3.11"

{hubble_sdk_python-0.3.1 → hubble_sdk_python-0.3.2}/tests/test_hubble.py

@@ -493,6 +493,64 @@ def _versioned_export_routes(poll_url: str = "/api/v1/fhir/exports/exp_1"):
     return start, poll, download
 
 
+@respx.mock
+@pytest.mark.parametrize("application", [True, False])
+def test_combined_pdf_download_through_high_level_client(application):
+    if application:
+        _token_route(return_value=httpx.Response(200, json=APP_TOKEN))
+    start, poll, download = _versioned_export_routes()
+    download.mock(return_value=httpx.Response(
+        200, content=b"%PDF combined", headers={"Content-Type": "application/pdf"}
+    ))
+    client = hub() if application else hub().session("cat_abc")
+    args = ("cns_1",) if application else ()
+
+    result = client.export_pdf(*args, version=VERSION, connection="conn_1", combined=True)
+
+    request = start.calls.last.request
+    assert request.url.params["combined"] == "true"
+    assert request.url.params["connection"] == "conn_1"
+    assert request.headers["Hubble-Version"] == VERSION
+    assert request.headers["Prefer"] == "respond-async"
+    assert request.headers["Authorization"] == ("Bearer app_tok_1" if application else "Bearer cat_abc")
+    assert poll.call_count == 2
+    if application:
+        assert request.url.params["consent"] == "cns_1"
+        assert all(c.request.url.params["consent"] == "cns_1" for c in poll.calls)
+    assert "Authorization" not in download.calls.last.request.headers
+    assert result.content == b"%PDF combined"
+    assert result.content_type == "application/pdf"
+    assert result.version == VERSION
+
+
+@respx.mock
+@pytest.mark.parametrize("application", [True, False])
+def test_combined_false_preserves_archive_behavior(application):
+    if application:
+        _token_route(return_value=httpx.Response(200, json=APP_TOKEN))
+    start, _, _ = _versioned_export_routes()
+    client = hub() if application else hub().session("cat_abc")
+    args = ("cns_1",) if application else ()
+
+    result = client.export_pdf(*args, version=VERSION, combined=False)
+
+    assert "combined" not in start.calls.last.request.url.params
+    assert result.content_type == "application/zip"
+
+
+@respx.mock
+@pytest.mark.parametrize("application", [True, False])
+@pytest.mark.parametrize("options", [
+    {}, {"connection": "conn_1"}, {"version": VERSION}, {"version": VERSION, "connection": ""},
+])
+def test_combined_requires_version_and_connection_before_any_request(application, options):
+    client = hub() if application else hub().session("cat_abc")
+    args = ("cns_1",) if application else ()
+    with pytest.raises(HubbleError, match="A combined PDF requires version and connection"):
+        client.export_pdf(*args, combined=True, **options)
+    assert not respx.calls
+
+
 @respx.mock
 def test_export_pdf_with_a_version_polls_then_downloads_without_the_token():
     start, poll, download = _versioned_export_routes()
@@ -504,6 +562,7 @@ def test_export_pdf_with_a_version_polls_then_downloads_without_the_token():
     assert started.headers["Hubble-Version"] == VERSION
     assert started.headers["Prefer"] == "respond-async"
     assert started.url.params["connection"] == "epic"
+    assert "combined" not in started.url.params
     assert poll.call_count == 2
     assert poll.calls.last.request.headers["Authorization"] == "Bearer cat_abc"
     assert "Authorization" not in download.calls.last.request.headers