fhir-pyrate 0.2.0b9__py3-none-any.whl → 0.2.2__py3-none-any.whl

fhir_pyrate/util/token_auth.py

@@ -1,10 +1,12 @@
 import logging
-from datetime import datetime, timedelta
+from datetime import timedelta
 from typing import Any, Optional, Union
 
 import jwt
 import requests
 
+from fhir_pyrate.util import now_utc
+
 logger = logging.getLogger(__name__)
 
 
@@ -35,10 +37,10 @@ class TokenAuth(requests.auth.AuthBase):
         username: str,
         password: str,
         auth_url: str,
-        refresh_url: str = None,
-        session: requests.Session = None,
+        refresh_url: Optional[str] = None,
+        session: Optional[requests.Session] = None,
         max_login_attempts: int = 5,
-        token_refresh_delta: Union[int, timedelta] = None,
+        token_refresh_delta: Optional[Union[int, timedelta]] = None,
     ) -> None:
         self._username = username
         self._password = password
@@ -63,11 +65,11 @@ class TokenAuth(requests.auth.AuthBase):
         )
         self.token: Optional[str] = None
         self._authenticate()
-        self.auth_time = datetime.now()
+        self.auth_time = now_utc()
 
     def _authenticate(self) -> None:
         """
-        Authenticates the user using the authentication URL and sets the token.
+        Authenticate the user using the authentication URL and sets the token.
         """
         # Authentication to get the token
         response = self._token_session.get(
@@ -78,7 +80,7 @@ class TokenAuth(requests.auth.AuthBase):
 
     def __call__(self, r: requests.PreparedRequest) -> requests.PreparedRequest:
         """
-        Sets the necessary authentication header of the current request.
+        Set the necessary authentication header of the current request.
 
         :param r: The prepared request that should be sent
         :return: The prepared request
@@ -88,7 +90,7 @@ class TokenAuth(requests.auth.AuthBase):
 
     def is_refresh_required(self) -> bool:
         """
-        Computes whether the token should be refreshed according to the given token and to the
+        Compute whether the token should be refreshed according to the given token and to the
         _token_refresh_delta variable.
 
         :return: Whether the token is about to expire and should thus be refreshed
@@ -109,7 +111,7 @@ class TokenAuth(requests.auth.AuthBase):
             )
             # If there is no expiration time return False
             # If we are already in the last 25% of the time return True
-            return refresh_interval is not None and datetime.now().timestamp() > (
+            return refresh_interval is not None and now_utc().timestamp() > (
                 decoded.get("exp") - refresh_interval
             )
         except jwt.exceptions.PyJWTError:
@@ -118,10 +120,10 @@ class TokenAuth(requests.auth.AuthBase):
             # If it has been specified and the time is almost run out
             return (
                 self._token_refresh_delta is not None
-                and (datetime.now() - self.auth_time) > self._token_refresh_delta
+                and (now_utc() - self.auth_time) > self._token_refresh_delta
             )
 
-    def refresh_token(self, token: str = None) -> None:
+    def refresh_token(self, token: Optional[str] = None) -> None:
         """
         Refresh the current session either by logging in again or by refreshing the token.
 
@@ -139,16 +141,16 @@ class TokenAuth(requests.auth.AuthBase):
             else:
                 response.raise_for_status()
                 self.token = response.text
-            self.auth_time = datetime.now()
+            self.auth_time = now_utc()
         else:
             self._authenticate()
-            self.auth_time = datetime.now()
+            self.auth_time = now_utc()
 
     def _refresh_hook(
         self, response: requests.Response, *args: Any, **kwargs: Any
     ) -> Optional[requests.Response]:
         """
-        Hook that is called after every request, it checks whether the login was successful and
+        Check whether the login was successful and
         if it was not, it either refreshes the token or authenticates the user again.
 
         :param response: The received response
@@ -164,15 +166,17 @@ class TokenAuth(requests.auth.AuthBase):
             # If the state is unauthorized,
             # then we should set how many times we have tried logging in
             if response.status_code == requests.codes.unauthorized:
-                if hasattr(response.request, "login_reattempted_times"):
-                    response.request.login_reattempted_times += 1  # type: ignore
-                    if (
-                        response.request.login_reattempted_times  # type: ignore
-                        >= self._max_login_attempts
-                    ):
-                        response.raise_for_status()
-                else:
-                    response.request.login_reattempted_times = 1  # type: ignore
+                login_attempts: int = getattr(
+                    response.request, "login_reattempted_times", 0
+                )
+                logger.info("Refreshing token because of unauthorized status.")
+                login_attempts += 1
+                if login_attempts >= self._max_login_attempts:
+                    response.raise_for_status()
+                setattr(response.request, "login_reattempted_times", login_attempts)  # noqa
+            else:
+                logger.info("Refreshing token refresh is required.")
+
             # If the token is None, then we were never actually authenticated
             if self.token is None:
                 response.raise_for_status()

fhir_pyrate/util/util.py

@@ -1,9 +1,13 @@
-import datetime
+from datetime import datetime, timezone
 from typing import Any
 
 import pandas as pd
 
 
+def now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
 def string_from_column(
     col: pd.Series,
     separator: str = ", ",
@@ -12,7 +16,7 @@ def string_from_column(
     sort_reverse: bool = False,
 ) -> Any:
     """
-    Transforms the values contained in a pandas Series into a string of (if desired unique) values.
+    Transform the values contained in a pandas Series into a string of (if desired unique) values.
 
     :param col:
     :param separator: The separator for the values
@@ -21,7 +25,7 @@ def string_from_column(
     :param sort_reverse: Whether the values should sorted in reverse order
     :return: A string containing the values of the Series.
     """
-    existing_values = list()
+    existing_values = []
     for el in col.values:
         if not pd.isnull(el) and el != "":
             existing_values.append(el)
@@ -40,9 +44,9 @@ def string_from_column(
 
 def get_datetime(dt_format: str = "%Y-%m-%d %H:%M:%S") -> str:
     """
-    Creates a datetime string according to the given format
+    Create a datetime string according to the given format
 
     :param dt_format: The format to use for the printing
     :return: The formatted string
     """
-    return datetime.datetime.now().strftime(dt_format)
+    return datetime.now().strftime(dt_format)

{fhir_pyrate-0.2.0b9.dist-info → fhir_pyrate-0.2.2.dist-info}/METADATA

@@ -1,28 +1,28 @@
 Metadata-Version: 2.1
 Name: fhir-pyrate
-Version: 0.2.0b9
+Version: 0.2.2
 Summary: FHIR-PYrate is a package that provides a high-level API to query FHIR Servers for bundles of resources and return the structured information as pandas DataFrames. It can also be used to filter resources using RegEx and SpaCy and download DICOM studies and series.
 Home-page: https://github.com/UMEssen/FHIR-PYrate
 License: MIT
 Keywords: python,fhir,data-science,fhirpath,healthcare
 Author: Rene Hosch
 Author-email: rene.hosch@uk-essen.de
-Requires-Python: >=3.8,<4.0
+Requires-Python: >=3.10,<4.0
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: all
 Provides-Extra: downloader
 Provides-Extra: miner
 Requires-Dist: PyJWT (>=2.4.0,<3.0.0)
 Requires-Dist: SimpleITK (>=2.0.2,<3.0.0) ; extra == "downloader" or extra == "all"
 Requires-Dist: dicomweb-client (>=0.52.0,<0.53.0) ; extra == "downloader" or extra == "all"
-Requires-Dist: fhirpathpy (>=0.1.0,<0.2.0)
-Requires-Dist: numpy (>=1.22,<2.0)
-Requires-Dist: pandas (>=1.3.0,<2.0.0)
+Requires-Dist: fhirpathpy (>=0.2.2,<0.3.0)
+Requires-Dist: numpy (>=2.0.0,<3.0.0)
+Requires-Dist: pandas (>=2.0.0,<3.0.0)
 Requires-Dist: pydicom (>=2.1.2,<3.0.0) ; extra == "downloader" or extra == "all"
 Requires-Dist: requests (>=2.28.0,<3.0.0)
 Requires-Dist: requests-cache (>=0.9.7,<0.10.0)
@@ -32,22 +32,22 @@ Project-URL: Repository, https://github.com/UMEssen/FHIR-PYrate
 Description-Content-Type: text/markdown
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Supported Python version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/release/python-380/)
+[![Supported Python version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-31011/)
 [![Stable Version](https://img.shields.io/pypi/v/fhir-pyrate?label=stable)](https://pypi.org/project/fhir-pyrate/)
 [![Pre-release Version](https://img.shields.io/github/v/release/UMEssen/fhir-pyrate?label=pre-release&include_prereleases&sort=semver)](https://pypi.org/project/fhir-pyrate/#history)
 [![DOI](https://zenodo.org/badge/456893108.svg)](https://zenodo.org/badge/latestdoi/456893108)
+[![Affiliated with RTG WisPerMed](https://img.shields.io/badge/Affiliated-RTG%202535%20WisPerMed-blue)](https://wispermed.org/)
 
 <!-- PROJECT LOGO -->
-<br />
-<div align="center">
-  <a href="https://github.com/UMEssen/FHIR-PYrate">
-    <img src="https://raw.githubusercontent.com/UMEssen/FHIR-PYrate/main/images/logo.svg" alt="Logo" width="440" height="338">
-  </a>
-</div>
+![Pyrate-Banner](images/pyrate-banner.png)
 
 This package is meant to provide a simple abstraction to query and structure FHIR resources as
 pandas DataFrames. Want to use R instead? Try out [fhircrackr](https://github.com/POLAR-fhiR/fhircrackr)!
 
+**If you use this package, please cite:**
+
+Hosch, R., Baldini, G., Parmar, V. et al. FHIR-PYrate: a data science friendly Python package to query FHIR servers. BMC Health Serv Res 23, 734 (2023). https://doi.org/10.1186/s12913-023-09498-1
+
 There are four main classes:
 * [Ahoy](https://github.com/UMEssen/FHIR-PYrate/blob/main/fhir_pyrate/ahoy.py): Authenticate on the FHIR API
 ([Example 1](https://github.com/UMEssen/FHIR-PYrate/blob/main/examples/1-simple-json-to-df.ipynb),
@@ -71,11 +71,6 @@ our institute. If there is anything in the code that only applies to our server,
 problems with the authentication (or anything else really), please just create an issue or
 [email us](mailto:giulia.baldini@uk-essen.de).
 
-<br />
-<div align="center">
-  <img src="https://raw.githubusercontent.com/UMEssen/FHIR-PYrate/main/images/resources.svg" alt="Resources" width="630" height="385">
-</div>
-
 <!-- TABLE OF CONTENTS -->
 Table of Contents:
 
@@ -236,10 +231,12 @@ The Pirate functions do one of three things:
 | trade_rows_for_dataframe                |  3   |       Yes       |    Yes    |      DataFrame       |
 
 
-**BETA FEATURE**: It is also possible to cache the bundles using the `bundle_caching` parameter,
-which specifies a caching folder. This has not yet been tested extensively and does not have any
-cache invalidation mechanism.
-
+**CACHING**: It is also possible to cache the bundles using the `cache_folder` parameter.
+This unfortunately does not currently work with multiprocessing, but saves a lot of time if you
+need to download a lot of data and you are always doing the same requests.
+You can also specify how long the cache should be valid with the `cache_expiry_time` parameter.
+Additionally, you can also specify whether the requests should be retried using the `retry_requests`
+parameter. There is an example of this in the docstrings of the Pirate class.
 
 A toy request for ImagingStudy:
 
@@ -429,7 +426,65 @@ parameters specified in `df_constraints` as columns of the final DataFrame.
 You can find an example in [Example 3](https://github.com/UMEssen/FHIR-PYrate/blob/main/examples/3-patients-for-condition.ipynb).
 Additionally, you can specify the `with_columns` parameter, which can add any columns from the original
 DataFrame. The columns can be either specified as a list of columns `[col1, col2, ...]` or as a
-list of tuples `[(new_name_for_col1, col1), (new_name_for_col2, col2), ...]`
+list of tuples `[(new_name_for_col1, col1), (new_name_for_col2, col2), ...]`.
+
+Currently, whenever a column is completely empty (i.e., no resources
+have a corresponding value for that column), it is just removed from the DataFrame.
+This is to ensure that we output clean DataFrames when we are handling multiple resources.
+More on that in the following section.
+
+#### Note on Querying Multiple Resources
+
+Not all FHIR servers allow this (at least not the public ones that we have tried),
+but it is also possible to obtain multiple resources with just one query:
+```python
+search = ...
+result_dfs = search.steal_bundles_to_dataframe(
+    resource_type="ImagingStudy",
+    request_params={
+        "_lastUpdated": "ge2022-12",
+        "_count": "3",
+        "_include": "ImagingStudy:subject",
+    },
+    fhir_paths=[
+        "id",
+        "started",
+        ("modality", "modality.code"),
+        ("procedureCode", "procedureCode.coding.code"),
+        (
+            "study_instance_uid",
+            "identifier.where(system = 'urn:dicom:uid').value.replace('urn:oid:', '')",
+        ),
+        ("series_instance_uid", "series.uid"),
+        ("series_code", "series.modality.code"),
+        ("numberOfInstances", "series.numberOfInstances"),
+        ("family_first", "name[0].family"),
+        ("given_first", "name[0].given"),
+    ],
+    num_pages=1,
+)
+```
+In this case, a dictionary of DataFrames is returned, where the keys are the resource types.
+You can then select the single dictionary by doing `result_dfs["ImagingStudy"]`
+or `result_dfs["Patient"]`.
+You can find an example of this in [Example 2](https://github.com/UMEssen/FHIR-PYrate/blob/main/examples/2-condition-to-imaging-study.ipynb)
+where the `ImagingStudy` resource is queried.
+
+In theory, it would be smarter to specify the resource name in front of the FHIRPaths,
+e.g. `ImagingStudy.series.uid` instead of `series.uid`, and for each DataFrame only return the
+corresponding attributes.
+However, we do not want to force the user to always specify the resource type, and in the current
+version the DataFrames
+coming from multiple resources have the same columns, because
+we cannot filter which resource was actually intended.
+Currently, we solved this by just removing all columns that do not have any results.
+Which means however, that if you are actually requesting an attribute for a specific resource and it
+is not found, that that column will not appear.
+In the future, [we plan to do a smarter filtering of the FHIRPaths](https://github.com/UMEssen/FHIR-PYrate/issues/120),
+such that only the ones containing
+the actual resource name are kept if the resource name is specified in the path,
+and that a column full of `None`s is obtained in case no resource type is specified.
+
 
 ### [Miner](https://github.com/UMEssen/FHIR-PYrate/blob/main/fhir_pyrate/miner.py)
 

fhir_pyrate-0.2.2.dist-info/RECORD

@@ -0,0 +1,15 @@
+fhir_pyrate/__init__.py,sha256=GrVFlghs2Q8pGCVLdNjD40R0Xt8ptvF5NhCtT1FUazk,864
+fhir_pyrate/ahoy.py,sha256=dOw94Khg3_4fXnJHAnZFlazxy_Tbb32Yi0HGOYVaHLU,5611
+fhir_pyrate/dicom_downloader.py,sha256=GNoOSlyt_pdykdcfvHS287iXMrVBHeyY1WIeegHnbvk,28215
+fhir_pyrate/miner.py,sha256=wydCL6zmVHSf4ctwz2760mZAfe9byVQciUWUQyRHVtQ,7331
+fhir_pyrate/pirate.py,sha256=xNqmz5g5EnB3-RLZM46JYXkoGISFVmYEQUg2M-bTcKA,70318
+fhir_pyrate/util/__init__.py,sha256=-P4jBpsH6XzQELrLAod2_P9oBocfaYUOWb_LQ-QjyKI,193
+fhir_pyrate/util/bundle_processing_templates.py,sha256=EERL26gbv2hkYCoxWj1ZguJK5TKJ3e03zMAJuKSkczY,4519
+fhir_pyrate/util/fhirobj.py,sha256=nTkSUbsmOisgDDgD_cEggF8hlPVjm7CWVSrkA8dOq3E,903
+fhir_pyrate/util/imports.py,sha256=3s0hvuonX_susm5anw4fZORh7V3JMJ4hoLPBVSoj7Lw,4333
+fhir_pyrate/util/token_auth.py,sha256=mfLzlZxCnWbiOOMZh_IDYgREp_9fhI3FshB8mDULtaQ,7862
+fhir_pyrate/util/util.py,sha256=1qIdoriWNksD3DRYm7qSRCli5t9524wa3mVf21fETgs,1507
+fhir_pyrate-0.2.2.dist-info/LICENSE,sha256=1IS7y51_JRtpCVVbUpYyztTMj3A6FskEZJBQkAQ9w9o,1084
+fhir_pyrate-0.2.2.dist-info/METADATA,sha256=V5L-hgjfdmrikX1nmZNsBHbf1utdOj-zSsQfKeV6ybQ,29679
+fhir_pyrate-0.2.2.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+fhir_pyrate-0.2.2.dist-info/RECORD,,

{fhir_pyrate-0.2.0b9.dist-info → fhir_pyrate-0.2.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.5.1
+Generator: poetry-core 1.9.1
 Root-Is-Purelib: true
 Tag: py3-none-any

fhir_pyrate-0.2.0b9.dist-info/RECORD

@@ -1,15 +0,0 @@
-fhir_pyrate/__init__.py,sha256=-25N2f8w3P0YXynSIqZcp2naR5lq0Q4_Xag2TZ4Ln7g,864
-fhir_pyrate/ahoy.py,sha256=E5P_V27kqRbuPsnI7pmH8sTmREwagSjbiVIw3BuotW8,5171
-fhir_pyrate/dicom_downloader.py,sha256=wGPMhyY94hdvxCQN1ew1xMsR_UccdnHaNBVixlJuSSM,26196
-fhir_pyrate/miner.py,sha256=sCiRhvBRUB548g2M9PcV8AptODdTQzd_KXJ8YccZKNU,7327
-fhir_pyrate/pirate.py,sha256=bgim3eWDZtRElFxekS3N0_4LgZ7kFpFYNmXG34oxMls,69421
-fhir_pyrate/util/__init__.py,sha256=YapXW-zC11qNTIHJi9IXgLMJmMsVbT3FR_laB-6CxYE,188
-fhir_pyrate/util/bundle_processing_templates.py,sha256=rxeUCRKiMMblT_-c55kYm1JofdAAbmDgu5spfBy99uE,4448
-fhir_pyrate/util/fhirobj.py,sha256=GX6iwbXtBYpe_DiRag0fYF3qenaLD2bQh31WYPDke44,883
-fhir_pyrate/util/imports.py,sha256=jKxiMYTDjbmstqbGCGYjr6EAdbTsvOrZ7GSZo1W6y2g,4336
-fhir_pyrate/util/token_auth.py,sha256=Ay6C1mmgotppZZt9RSkEZtWzVxWCdx1QUBMdMQO7cwY,7818
-fhir_pyrate/util/util.py,sha256=tE9T9F6WUdhTlQxpWnx-j4P5TqdQr3rimqpFyrlhrGw,1431
-fhir_pyrate-0.2.0b9.dist-info/LICENSE,sha256=1IS7y51_JRtpCVVbUpYyztTMj3A6FskEZJBQkAQ9w9o,1084
-fhir_pyrate-0.2.0b9.dist-info/METADATA,sha256=YliJr4z4I4YyQEeXyltkQ5nVE2O1uK_aeuga7nmj3zk,26670
-fhir_pyrate-0.2.0b9.dist-info/WHEEL,sha256=kLuE8m1WYU0Ig0_YEGrXyTtiJvKPpLpDEiChiNyei5Y,88
-fhir_pyrate-0.2.0b9.dist-info/RECORD,,