external-systems 0.1.0__py3-none-any.whl

external_systems/__init__.py

@@ -0,0 +1,15 @@
+#  Copyright 2025 Palantir Technologies, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from ._version import __version__ as __version__

external_systems/_version.py

@@ -0,0 +1,19 @@
+#  Copyright 2025 Palantir Technologies, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+
+# The version is set during the publishing step (since we can't know the version in advance)
+# using the autorelease bot
+
+__version__ = "0.1.0"

external_systems/sources/__init__.py

@@ -0,0 +1,38 @@
+#  Copyright 2025 Palantir Technologies, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from ._api import (
+    AwsCredentials,
+    ClientCertificate,
+    ClientCertificateFilePaths,
+    HttpsConnectionParameters,
+    SourceCredentials,
+    SourceParameters,
+)
+from ._connections import HttpsConnection
+from ._refreshable import Refreshable, RefreshHandler
+from ._sources import Source
+
+__all__ = [
+    "ClientCertificate",
+    "ClientCertificateFilePaths",
+    "HttpsConnection",
+    "HttpsConnectionParameters",
+    "Source",
+    "SourceParameters",
+    "RefreshHandler",
+    "Refreshable",
+    "AwsCredentials",
+    "SourceCredentials",
+]

external_systems/sources/_api.py

@@ -0,0 +1,91 @@
+#  Copyright 2025 Palantir Technologies, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Dict, Optional, Union
+
+
+@dataclass(frozen=True)
+class ClientCertificate:
+    """
+    A class representing a client certificate presentable to an external system for authentication
+    Attributes:
+      pem_certificate (str): PEM certificate contents
+      pem_private_key (str): PEM private key contents
+    """
+
+    pem_certificate: str
+    pem_private_key: str
+
+
+@dataclass(frozen=True)
+class ClientCertificateFilePaths:
+    """
+    A class holding the paths of the Source's client certificate
+    Attributes:
+      certificate_file_path (str): Path to the certificate file
+      private_key_file_path (str): Path to the private key file
+    """
+
+    certificate_file_path: str
+    private_key_file_path: str
+
+
+@dataclass(frozen=True)
+class HttpsConnectionParameters:
+    """
+    A class representing HTTPS connection parameters for an external system.
+    Attributes:
+      url (str): The base URL of the external system.
+      headers (Dict[str, str]): A dictionary containing the auth headers for the connection.
+      query_params (Dict[str, str]): A dictionary containing the auth query parameters for the connection.
+    """
+
+    url: str
+    headers: dict[str, str]
+    query_params: dict[str, str]
+
+
+@dataclass(frozen=True)
+class AwsCredentials:
+    access_key_id: str
+    secret_access_key: str
+    session_token: Optional[str] = None
+    expiration: Optional[datetime] = None
+
+
+# Each new credential type must include an expiration field
+SourceCredentials = Union[AwsCredentials]
+
+
+@dataclass(frozen=True)
+class SourceParameters:
+    """
+    A class representing source parameters for an external system.
+    Attributes:
+      secrets (Dict[str, str]): A dictionary containing the secrets contained on the source.
+      proxy_token (Optional[str]): The token for authenticating with the on-prem-proxy service.
+      https_connections (Dict[str, HttpsConnection]): A dictionary containing the https connections on the Source.
+      server_certificates (Dict[str, str]): A dictionary containing the server certificates for the source.
+      client_certificate Optional[ClientCertificate]: The client certificate configured on the source.
+      resolved_source_credentials (Optional[SourceCredentials]): If session credentials are used, this field will contain the resolved credentials.
+    """
+
+    secrets: Dict[str, str]
+    proxy_token: Optional[str]
+    https_connections: Dict[str, HttpsConnectionParameters]
+    server_certificates: Dict[str, str]
+    client_certificate: Optional[ClientCertificate]
+    resolved_source_credentials: Optional[SourceCredentials]

external_systems/sources/_connections.py

@@ -0,0 +1,71 @@
+#  Copyright 2025 Palantir Technologies, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from typing import Mapping, Optional, Tuple
+
+from frozendict import frozendict
+from requests import Session
+
+from ._api import HttpsConnectionParameters
+from ._proxies import create_session
+
+
+class HttpsConnection:
+    """
+    A class representing an HTTPS connection for an external system.
+    """
+
+    def __init__(
+        self,
+        connection_parameters: HttpsConnectionParameters,
+        client_certificate: Optional[Tuple[str, str]] = None,
+        proxy_uri_with_auth: Optional[str] = None,
+        ca_bundle_path: Optional[str] = None,
+    ):
+        self._client_certificate = client_certificate
+        self._headers = frozendict(connection_parameters.headers)
+        self._url = connection_parameters.url
+        self._query_params = frozendict(connection_parameters.query_params)
+        self._proxies = frozendict({"https": proxy_uri_with_auth}) if proxy_uri_with_auth is not None else None
+        self._ca_bundle_path = ca_bundle_path
+
+    def get_client(self, timeout: int = 30) -> Session:
+        """Get the HTTP client for this connection.
+          This client must be used in order to reach the external system.
+        Args:
+            timeout (int, optional): The request timeout in seconds. Defaults to 30.
+        Returns:
+            requests.Session: A configured requests.Session object for communicating with the external system.
+        """
+
+        return create_session(
+            cert=self._client_certificate,
+            ca_bundle_path=self._ca_bundle_path,
+            headers=self._headers,
+            user_agent="external-systems",
+            proxies=self._proxies,
+            timeout=timeout,
+        )
+
+    @property
+    def headers(self) -> Mapping[str, str]:
+        return self._headers
+
+    @property
+    def query_params(self) -> Mapping[str, str]:
+        return self._query_params
+
+    @property
+    def url(self) -> str:
+        return self._url

external_systems/sources/_proxies.py

@@ -0,0 +1,134 @@
+#  Copyright 2025 Palantir Technologies, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from functools import cache
+from typing import Any, Mapping, Optional, Union
+
+from requests import PreparedRequest, Response, Session
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+
+class RetryingTimeoutHttpAdapter(HTTPAdapter):
+    def __init__(
+        self,
+        *args: Any,
+        timeout: Optional[Union[float, tuple[float, float], tuple[float, None]]] = None,
+        retries: Optional[Union[Retry, int]] = None,
+        **kwargs: Any,
+    ):
+        self._timeout = timeout
+        retries = retries or Retry(total=10, backoff_factor=0.1, status_forcelist=[503])
+        super().__init__(*args, max_retries=retries, **kwargs)  # type: ignore[misc]
+
+    def send(
+        self,
+        request: PreparedRequest,
+        stream: bool = False,
+        timeout: Optional[Union[float, tuple[float, float], tuple[float, None]]] = None,
+        verify: Union[bool, str] = True,
+        cert: Optional[Union[bytes, str, tuple[Union[bytes, str], Union[bytes, str]]]] = None,
+        proxies: Optional[Mapping[str, str]] = None,
+    ) -> Response:
+        if timeout is None:
+            timeout = self._timeout
+        return super().send(request, stream=stream, timeout=timeout, verify=verify, cert=cert, proxies=proxies)
+
+    def __getstate__(self) -> Any:
+        state: dict[str, Any] = super().__getstate__()  # type: ignore
+        # The HTTPAdapter superclass overrides the __getstate__ method to serialize only selective fields.
+        # Any fields specific to this class must be added here so that these fields will be preserved after being
+        # pickled/unpickled.
+        state["_timeout"] = self._timeout
+        return state
+
+
+class ProxyAdapter(HTTPAdapter):
+    def __init__(self, *args: Any, proxy_auth: dict[str, str], **kwargs: Any):
+        super().__init__(*args, **kwargs)
+        self._proxy_auth = proxy_auth
+
+    def proxy_headers(self, proxy: str) -> dict[str, str]:
+        return {"Proxy-Authorization": self._proxy_auth[proxy]}
+
+    def __getstate__(self) -> Any:
+        state: dict[str, Any] = super().__getstate__()  # type: ignore
+        # The HTTPAdapter superclass overrides the __getstate__ method to serialize only selective fields.
+        # Any fields specific to this class must be added here so that these fields will be preserved after being
+        # pickled/unpickled.
+        state["_proxy_auth"] = self._proxy_auth
+        return state
+
+
+@cache
+def create_proxy_session(proxy_url: str, proxy_token: str) -> Session:
+    """
+    Create a session with proxy authentication.
+    Args:
+        proxy_url (str): The URL of the proxy server.
+        proxy_token (str): The token for authenticating with the proxy server.
+    Returns:
+        Session: A requests session with proxy authentication.
+    """
+
+    adapter = ProxyAdapter(proxy_auth={proxy_url: f"Bearer {proxy_token}"})
+    session = Session()
+    session.mount("http://", adapter)
+    session.mount("https://", adapter)
+    session.proxies = {"all": proxy_url}
+    return session
+
+
+@cache
+def create_session(
+    cert: Optional[Union[str, tuple[str, str]]] = None,
+    ca_bundle_path: Optional[str] = None,
+    headers: Optional[dict[str, str]] = None,
+    user_agent: Optional[str] = None,
+    proxies: Optional[dict[str, str]] = None,
+    timeout: Optional[Union[float, tuple[float, float], tuple[float, None]]] = None,
+) -> Session:
+    """
+    Create a session with optional client certificate and CA bundle path.
+    Args:
+        cert (Optional[Union[str, tuple[str, str]]]): The client certificate to use for authentication.
+        ca_bundle_path (Optional[str]): The path to the CA bundle file.
+        headers (Optional[dict[str, str]]): Additional headers to include in the request.
+        user_agent (Optional[str]): The User-Agent header value.
+        proxies (Optional[dict[str, str]]): Proxies to use for the session.
+        timeout (Optional[Union[float, tuple[float, float], tuple[float, None]]]): Timeout settings for the session.
+    """
+
+    session = Session()
+
+    if cert:
+        session.cert = cert
+
+    if ca_bundle_path:
+        session.verify = ca_bundle_path
+
+    adapter = RetryingTimeoutHttpAdapter(timeout=timeout)
+    session.mount("http://", adapter)
+    session.mount("https://", adapter)
+
+    if headers:
+        session.headers.update(headers)
+
+    if user_agent:
+        session.headers["User-Agent"] = user_agent
+
+    if proxies:
+        session.proxies = proxies
+
+    return session

external_systems/sources/_refreshable.py

@@ -0,0 +1,130 @@
+#  Copyright 2025 Palantir Technologies, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+import logging
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta
+from typing import Generic, Optional, TypeVar
+
+from external_systems.sources._api import SourceCredentials
+from external_systems.sources._utils import has_expiration_property
+
+log = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+# Time before expiration to refresh the credentials
+REFRESH_TIME_OFFSET_SECONDS = 5
+
+
+class RefreshHandler(ABC, Generic[T]):
+    """
+    This manages how and where to retrieve the new refreshed resource from
+    """
+
+    @abstractmethod
+    def refresh(self) -> Optional[T]:
+        """
+        Returns:
+            T: The refreshed resource.
+        """
+        raise NotImplementedError("refresh() method not implemented")
+
+
+class Refreshable(ABC, Generic[T]):
+    """
+    This manages the lifecycle of a resource that can be refreshed.
+    """
+
+    @abstractmethod
+    def get(self) -> T:
+        """
+        Retrieve the current value of the resource.
+
+        Returns:
+            T: The current value of the resource.
+        """
+        raise NotImplementedError("get() method not implemented")
+
+
+class DefaultSessionCredentialsManager(Refreshable[SourceCredentials]):
+    """
+    Client for refreshing resolved source credentials.
+    Will return credentials if they are not expired.
+    Otherwise will attempt to lazily refresh the credentials on `get()` calls.
+
+    :param source_credentials: SourceCredentials object returned by API representing the source credentials.
+    :param refresh_handler: A provider responsible for performing the refresh.
+    :param refresh_offset_seconds: Represents how many seconds before the credentials expire should we refresh them.
+    """
+
+    def __init__(
+        self,
+        resolved_source_credentials: SourceCredentials,
+        refresh_handler: Optional[RefreshHandler[SourceCredentials]] = None,
+    ) -> None:
+        self._credentials: SourceCredentials = resolved_source_credentials
+        self._refresh_handler = refresh_handler
+
+    def get(self) -> SourceCredentials:
+        """
+        Returns the source's credentials.
+
+        This method automatically refreshes the credentials if they are expired.
+
+        Returns
+            SourceCredentials: The current source credentials.
+
+        Raises
+            ValueError: If the credentials have not been set.
+        """
+        self._maybe_refresh_credentials()
+        if self._credentials is None:
+            raise ValueError("Credentials have not been set")
+        return self._credentials
+
+    def _maybe_refresh_credentials(self) -> None:
+        """
+        Checks if the credentials are expired and delegates the refresh to `_refresh_credentials` if needed.
+        """
+
+        # Don't refresh if expiration time is not set
+        if (
+            self._credentials is None
+            or not has_expiration_property(self._credentials)
+            or self._credentials.expiration is None
+        ):
+            return
+
+        # If the credentials are valid for more than specified seconds, don't refresh
+        time_until_creds_expire = self._credentials.expiration - datetime.now()
+        time_until_creds_expire_with_offset = time_until_creds_expire - timedelta(seconds=REFRESH_TIME_OFFSET_SECONDS)
+        needs_refresh = time_until_creds_expire_with_offset.total_seconds() <= 0
+
+        if not needs_refresh:
+            return
+
+        self._refresh_credentials()
+
+    def _refresh_credentials(self) -> None:
+        if self._refresh_handler is None:
+            # Refresh handler is not set, nothing to refresh
+            return
+
+        maybe_resolved_credentials = self._refresh_handler.refresh()
+
+        if maybe_resolved_credentials is None:
+            raise ValueError("Refresh failed for source")
+
+        self._credentials = maybe_resolved_credentials

external_systems/sources/_sockets.py

@@ -0,0 +1,104 @@
+#  Copyright 2025 Palantir Technologies, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+import base64
+import logging
+import os
+import re
+import socket
+import ssl
+import time
+
+import urllib3
+
+log = logging.getLogger(__name__)
+
+
+STATUS_LINE_PATTERN = re.compile(r"^HTTP/\d\.\d (\d{3}) .*$")
+NUM_RETRIES = 10
+RETRYABLE_RESPONSE_CODES = {503, 429}
+
+
+def create_socket(https_proxy_uri: str, target_host: str, target_port: int) -> socket.socket:
+    """
+    Establishes a socket connection through an HTTPS proxy to a target host and port.
+    Parameters:
+        https_proxy_uri (str): The URI of the HTTPS proxy, must include auth if required.
+        target_host (str): The hostname of the target server to connect to.
+        target_port (int): The port number of the target server to connect to.
+    Returns:
+        socket.socket: A connected SSL socket to the target host and port through the proxy.
+    Raises:
+        ValueError: If the proxy URI does not specify a hostname or port, or if the connection fails after retrying, with an invalid response code.
+        RuntimeError: If there is an exception during the socket creation process.
+    """
+
+    parsed_proxy_uri = urllib3.util.parse_url(https_proxy_uri)
+
+    if parsed_proxy_uri.hostname is None:
+        raise ValueError("proxy uri has no hostname specified")
+
+    if parsed_proxy_uri.port is None:
+        raise ValueError("proxy uri has no port specified")
+
+    last_response_code = -1
+    for _ in range(NUM_RETRIES):
+        try:
+            proxy_socket = _create_ssl_socket(parsed_proxy_uri.hostname, parsed_proxy_uri.port)
+            proxy_socket.sendall(f"CONNECT {target_host}:{target_port} HTTP/1.1\r\n".encode())
+            proxy_socket.sendall(f"Host: {target_host}:{target_port}\r\n".encode())
+
+            if parsed_proxy_uri.auth is not None:
+                basic_auth_payload = base64.b64encode(parsed_proxy_uri.auth.encode()).decode()
+                proxy_socket.sendall(f"Proxy-Authorization: Basic {basic_auth_payload}\r\n".encode())
+
+            proxy_socket.sendall(b"\r\n")
+            response_line = proxy_socket.recv(4096).decode().split("\r\n")[0]
+
+            match = STATUS_LINE_PATTERN.match(response_line)
+
+            if match is None:
+                raise ValueError("status line pattern did not match")
+
+            response_code = int(match.group(1))
+
+            if response_code == 200:
+                return proxy_socket
+
+            last_response_code = response_code
+            if response_code in RETRYABLE_RESPONSE_CODES:
+                log.info("Received retryable response code from proxy, retrying after 0.5 seconds: %s", response_code)
+                time.sleep(0.5)
+            else:
+                break
+        except Exception as e:
+            raise RuntimeError("Failed to create socket") from e
+
+    raise ValueError(f"Failed to establish tunnel, invalid response code: {last_response_code}")
+
+
+def _create_ssl_socket(proxy_host: str, proxy_port: int) -> socket.socket:
+    ca_bundle_path = os.environ.get("REQUESTS_CA_BUNDLE")
+    if not ca_bundle_path or not os.path.isfile(ca_bundle_path):
+        log.warning("The REQUESTS_CA_BUNDLE environment variable does not exist or is not a file.")
+        raise ValueError("REQUESTS_CA_BUNDLE does not exist")
+    if not os.access(ca_bundle_path, os.R_OK):
+        log.warning("The REQUESTS_CA_BUNDLE file is not readable.")
+        raise ValueError("REQUESTS_CA_BUNDLE is not readable")
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    context.load_verify_locations(ca_bundle_path)
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    wrapped_sock = context.wrap_socket(sock, server_hostname=proxy_host)
+    wrapped_sock.connect((proxy_host, proxy_port))
+    return wrapped_sock

external_systems/sources/_sources.py

@@ -0,0 +1,235 @@
+#  Copyright 2025 Palantir Technologies, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+import logging
+import os
+import random
+import socket
+from functools import cached_property
+from tempfile import NamedTemporaryFile
+from typing import Any, Mapping, Optional, Tuple
+
+import urllib3.util
+from frozendict import frozendict
+from requests import Session
+
+from ._api import AwsCredentials, ClientCertificateFilePaths, SourceCredentials, SourceParameters
+from ._connections import HttpsConnection
+from ._proxies import create_proxy_session
+from ._refreshable import DefaultSessionCredentialsManager, Refreshable, RefreshHandler
+from ._sockets import create_socket
+
+log = logging.getLogger(__name__)
+
+
+class Source:
+    """
+    A class representing a Source for an external systems.
+    """
+
+    def __init__(
+        self,
+        source_parameters: SourceParameters,
+        on_prem_proxy_service_uris: list[str],
+        egress_proxy_service_uris: list[str],
+        egress_proxy_token: Optional[str],
+        source_configuration: Optional[Any],
+        credentials_refresh_handler: Optional[RefreshHandler[SourceCredentials]] = None,
+    ):
+        self._source_parameters = source_parameters
+        self._on_prem_proxy_service_uris = on_prem_proxy_service_uris
+        self._egress_proxy_service_uris = egress_proxy_service_uris
+        self._source_configuration = source_configuration
+        self._egress_proxy_token = egress_proxy_token
+        self._credentials_refresh_handler = credentials_refresh_handler
+
+    @cached_property
+    def secrets(self) -> Mapping[str, str]:
+        """A dictionary containing plaintext secrets on the Source keyed by secret API name."""
+        return frozendict(self._source_parameters.secrets)
+
+    @property
+    def client_certificate(self) -> Optional[ClientCertificateFilePaths]:
+        """
+        The client certificate file name and private key file name if present on the Source.
+        Returns:
+            Optional[ClientCertificateFilePaths]: If a client certificate is present on the source, otherwise None.
+        """
+        return ClientCertificateFilePaths(*self._client_certificate) if self._client_certificate is not None else None
+
+    @cached_property
+    def _https_connections(self) -> Mapping[str, HttpsConnection]:
+        return frozendict(
+            {
+                key: HttpsConnection(params, self._client_certificate, self._https_proxy_url, self._ca_bundle_path)
+                for key, params in self._source_parameters.https_connections.items()
+            }
+        )
+
+    @cached_property
+    def _ca_bundle_path(self) -> Optional[str]:
+        if self._source_parameters.server_certificates is None:
+            return None
+
+        new_ca_contents = []
+
+        # If requests env var is set, add all existing CAs
+        requests_ca_bundle_path = os.environ.get("REQUESTS_CA_BUNDLE")
+        if requests_ca_bundle_path is not None:
+            with open(requests_ca_bundle_path) as requests_ca_bundle_file:
+                new_ca_contents.append(requests_ca_bundle_file.read())
+
+        # Add all CAs for the source
+        for required_ca in self._source_parameters.server_certificates.values():
+            new_ca_contents.append(required_ca)
+
+        with NamedTemporaryFile(delete=False, mode="w") as ca_bundle_file:
+            ca_bundle_file.write(os.linesep.join(new_ca_contents) + os.linesep)
+            return ca_bundle_file.name
+
+    @cached_property
+    def _client_certificate(self) -> Optional[Tuple[str, str]]:
+        if self._source_parameters.client_certificate is None:
+            return None
+
+        cert_file = NamedTemporaryFile(delete=False, mode="w")  # pylint: disable=consider-using-with
+        cert_file.write(self._source_parameters.client_certificate.pem_certificate)
+
+        private_key_file = NamedTemporaryFile(delete=False, mode="w")  # pylint: disable=consider-using-with
+        private_key_file.write(self._source_parameters.client_certificate.pem_private_key)
+
+        return cert_file.name, private_key_file.name
+
+    @cached_property
+    def _proxy_session(self) -> Session:
+        egress_proxy_configured = self._egress_proxy_token is not None
+        on_prem_proxy_configured = self._source_parameters.proxy_token is not None
+
+        if on_prem_proxy_configured:
+            if egress_proxy_configured:
+                log.warning(
+                    "both egress proxy and on-prem proxy are configured for this source. preferring on-prem proxy"
+                )
+            if len(self._on_prem_proxy_service_uris) == 0:
+                raise ValueError(
+                    "on-prem proxy was configured for this source, but on-prem proxy URIs were not present"
+                )
+            return create_proxy_session(
+                random.choice(self._on_prem_proxy_service_uris), self._source_parameters.proxy_token
+            )
+        elif egress_proxy_configured:
+            # we checked this earlier, but assert again here to make mypy happy
+            assert (
+                self._egress_proxy_token is not None
+            ), "no egress proxy parameters found while configuring egress proxy session"
+            if len(self._egress_proxy_service_uris) == 0:
+                raise ValueError("egress proxy was configured for this source, but egress proxy URIs were not present")
+            return create_proxy_session(self._https_proxy_url, self._egress_proxy_token)
+        else:
+            raise ValueError(
+                "neither egress proxy nor on-prem proxy were configured. unable to construct a proxy session"
+            )
+
+    @cached_property
+    def _https_proxy_url(self) -> Optional[str]:
+        if self._source_parameters.proxy_token is not None:
+            parsed = urllib3.util.parse_url(random.choice(self._on_prem_proxy_service_uris))
+            parsed = parsed._replace(auth=f"user:{self._source_parameters.proxy_token}")
+            return parsed.url
+
+        if self._egress_proxy_token is not None:
+            parsed = urllib3.util.parse_url(random.choice(self._egress_proxy_service_uris))
+            parsed = parsed._replace(auth=f"user:{self._egress_proxy_token}")
+            return parsed.url
+
+        return None
+
+    @cached_property
+    def _maybe_refreshable_resolved_source_credentials(self) -> Optional[Refreshable[SourceCredentials]]:
+        if self._source_parameters.resolved_source_credentials is None:
+            return None
+
+        return DefaultSessionCredentialsManager(
+            self._source_parameters.resolved_source_credentials, self._credentials_refresh_handler
+        )
+
+    @cached_property
+    def source_configuration(self) -> Any:
+        """
+        Full configuration of the Source.
+        Throws if source configuration is not supported by public API.
+        """
+        if self._source_configuration is None:
+            raise ValueError("Source configuration is not available for this Source.")
+        return self._source_configuration
+
+    def get_aws_credentials(self) -> Refreshable[AwsCredentials]:
+        """
+        Get the AWS credentials from the Source.
+
+        Supported Sources:
+            - S3
+        """
+        if self._maybe_refreshable_resolved_source_credentials is None:
+            raise ValueError("Resolved source credentials are not present on the Source.")
+        if not isinstance(self._maybe_refreshable_resolved_source_credentials.get(), AwsCredentials):
+            raise ValueError("Resolved source credentials are not of type AwsCredentials.")
+        return self._maybe_refreshable_resolved_source_credentials
+
+    def get_secret(self, key: str) -> str:
+        """Get the plaintext value for the provided secret key, as configured in the Source secrets."""
+        secret = self.secrets.get(key)
+        if not secret:
+            raise ValueError(f"Secret with name {key} not found on the Source.")
+        return secret
+
+    def get_https_connection(self) -> HttpsConnection:
+        """Get the HTTPS Connection from the Source.
+        Raises:
+            ValueError: If there are multiple connections on the source.
+        Returns:
+            HttpsConnection: The requested HttpsConnection object.
+        """
+
+        if len(self._https_connections) != 1:
+            raise ValueError("Only single connection sources are supported.")
+        return next(iter(self._https_connections.values()))
+
+    def get_https_proxy_uri(self) -> Optional[str]:
+        """Get the HTTPS proxy URI that must be used to communicate with the external system
+        when using an Agent Proxy source.
+        The format of the proxy URI will be "https://user:password@proxy-server.com:443".
+        If a proxy is not required, the function will return None.
+        This is useful if you can't use the provided requests client and need to use a different HTTP client or an SDK.
+        """
+        return self._https_proxy_url
+
+    def create_socket(self, target_host: str, target_port: int) -> socket.socket:  # pylint: disable=too-many-locals
+        """
+        Create a socket connection to the host and port in the HTTPS connection through the Agent Proxy.
+        The socket returned by this method MUST be closed by the caller to avoid hanging connections in the proxy.
+        It is recommended to use the `contextlib.closing` context manager to ensure the socket is closed:
+            from contextlib import closing
+            with closing(source.create_socket(target_host, target_port)) as sock:
+                # Use the socket here
+        Returns:
+            socket.socket: A socket object connected to the target host and port through the HTTPS proxy.
+        Raises:
+            ValueError: If the configured proxy is not an HTTPS proxy or if the tunnel cannot be established.
+            RuntimeError: If there is a failure during socket creation.
+        """
+        if not self._https_proxy_url:
+            raise ValueError("Only usable with Agent Proxy Sources")
+
+        return create_socket(self._https_proxy_url, target_host, target_port)

external_systems/sources/_utils.py

@@ -0,0 +1,25 @@
+#  Copyright 2025 Palantir Technologies, Inc.
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+from ._api import SourceCredentials
+
+JAVA_OFFSET_DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+
+def has_expiration_property(source_credentials: SourceCredentials) -> bool:
+    """
+    Checks if the source credentials provided have an expiration property.
+    """
+
+    return hasattr(source_credentials, "expiration")

external_systems-0.1.0.dist-info/LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright {YEAR} Palantir Technologies, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

external_systems-0.1.0.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.3
+Name: external-systems
+Version: 0.1.0
+Summary: A Python library for interacting with Foundry Sources
+License: Apache-2.0
+Keywords: Palantir,Foundry,Sources,Compute Modules,Python Functions,Transforms
+Author: Palantir Technologies, Inc.
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Dist: frozendict (>=2.4.6,<3.0.0)
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Project-URL: Repository, https://github.com/palantir/external-systems
+Description-Content-Type: text/markdown
+
+# External Systems
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/external-systems)
+[![PyPI](https://img.shields.io/pypi/v/external-systems)](https://pypi.org/project/external-systems/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-lightgrey.svg)](https://opensource.org/licenses/Apache-2.0)
+
+
+> [!WARNING]
+> This SDK is incubating and subject to change.
+
+
+## About Foundry Sources
+
+The External Systems library is Python SDK built as an interface to reference [Foundry Sources](https://www.palantir.com/docs/foundry/data-connection/set-up-source) from code.
+
+<a id="installation"></a>
+## Installation
+You can install the Python package using `pip`:
+
+```sh
+pip install external-systems
+```
+
+<a id="basic-usage"></a>
+## Basic Source Usage
+
+### Credentials
+
+Long lived credentials can be referenced using `get_secret()` on the source.
+
+```python
+my_source: Source = ...
+
+some_secret = my_source.get_secret("SECRET_NAME")
+```
+
+For sources using session credentials we support credentials generation and refresh management. Currently on an S3 source you can access session credentials using `get_aws_credentials()`.
+
+```python
+s3_source: Source = ...
+
+refreshable_credentials: Refreshable[AwsCredentials] = s3_source.get_aws_credentials()
+
+session_credentials: AwsCredentials = refreshable_credentials.get()
+```
+
+### HTTP Client
+For REST based sources, a preconfigured HTTP client is provided built on top of the Python requests library.
+
+```python
+source_url = my_source.get_https_connection().url
+http_client = my_source.get_https_connection().get_client()
+
+response = http_client.get(source_url + "/api/v1/example/", timeout=10)
+```
+

external_systems-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+external_systems/__init__.py,sha256=xXDUDD6_qRO-nHuXZx-fXp0R0vc3N_OOsB1F5mF_kpU,651
+external_systems/_version.py,sha256=edsEuFM8fnpvqgnm1a9kDAaQcgfl58B_iUMYwpkVdRw,747
+external_systems/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+external_systems/sources/__init__.py,sha256=aqXbMIy_pnyIC1uPRzQfApLCbhYB4N8iRFnpOX4RdAk,1156
+external_systems/sources/_api.py,sha256=NV7oNIgzSWz4ROFW8uPpUJjDN5vfFzdTs3yKC37S39k,3262
+external_systems/sources/_connections.py,sha256=h82npEks29NALAAfMHrXcSnB7TY_OLeXgL3QN9Cssus,2509
+external_systems/sources/_proxies.py,sha256=igWRL-kpQ_IlZyJwI_s66rDe0oQ68ltGeFNydgoiR4w,5071
+external_systems/sources/_refreshable.py,sha256=0pa5XW0_2gTMW-ZymKhlhh3Kka_bWTWffThKvrTTifc,4421
+external_systems/sources/_sockets.py,sha256=oCCUEpLvHLhYXljRiBc11YAWJCZOd-wpUFjl8CaueX0,4285
+external_systems/sources/_sources.py,sha256=fYEkVOVCuEHpJytRWw-TCXzHmefoAhAny5853fONajU,10529
+external_systems/sources/_utils.py,sha256=_GDyJOzPHQudEbrPsRhXMs8u6AaHpgJQIq8H9xSYJZk,913
+external_systems-0.1.0.dist-info/LICENSE.txt,sha256=NAk6Uc9K_N_J5V75k9qECpzUnO-ujT-mKK_jk_mboUE,569
+external_systems-0.1.0.dist-info/METADATA,sha256=isfctYmHoIoGFyNpoFu1W0GqOyW-mTK79UG1nvsVVMI,2513
+external_systems-0.1.0.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+external_systems-0.1.0.dist-info/RECORD,,

external_systems-0.1.0.dist-info/WHEEL

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