external-systems 0.2.0__py3-none-any.whl → 0.100.0__py3-none-any.whl

external_systems/_version.py

@@ -16,4 +16,4 @@
 # The version is set during the publishing step (since we can't know the version in advance)
 # using the autorelease bot
 
-__version__ = "0.2.0"
+__version__ = "0.100.0"

external_systems/sources/_sockets.py

@@ -19,6 +19,7 @@ import re
 import socket
 import ssl
 import time
+from typing import Optional
 
 import urllib3
 
@@ -30,15 +31,20 @@ NUM_RETRIES = 10
 RETRYABLE_RESPONSE_CODES = {503, 429}
 
 
-def create_socket(https_proxy_uri: str, target_host: str, target_port: int) -> socket.socket:
+def create_socket(
+    https_proxy_uri: str, target_host: str, target_port: int, custom_ca_bundle_path: Optional[str] = None
+) -> socket.socket:
     """
     Establishes a socket connection through an HTTPS proxy to a target host and port.
-    Parameters:
+
+    Args:
         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.
@@ -55,7 +61,7 @@ def create_socket(https_proxy_uri: str, target_host: str, target_port: int) -> s
     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 = _create_ssl_socket(parsed_proxy_uri.hostname, parsed_proxy_uri.port, custom_ca_bundle_path)
             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())
 
@@ -88,14 +94,16 @@ def create_socket(https_proxy_uri: str, target_host: str, target_port: int) -> s
     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")
+def _create_ssl_socket(proxy_host: str, proxy_port: int, custom_ca_bundle_path: Optional[str] = None) -> socket.socket:
+    ca_bundle_path = (
+        custom_ca_bundle_path if custom_ca_bundle_path is not None else 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")
+        log.warning("The CA_BUNDLE environment variable does not exist or is not a file.")
+        raise ValueError("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")
+        log.warning("The CA_BUNDLE file is not readable.")
+        raise ValueError("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)

external_systems/sources/_sources.py

@@ -241,4 +241,4 @@ class Source:
         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)
+        return create_socket(self._https_proxy_url, target_host, target_port, self._custom_ca_bundle_path)

external_systems-0.100.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.3
+Name: external-systems
+Version: 0.100.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)
+<a href="https://autorelease.general.dmz.palantir.tech/palantir/external-systems"><img src="https://img.shields.io/badge/Perform%20an-Autorelease-success.svg" alt="Autorelease"></a>
+
+> [!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.
+
+## Installation
+
+You can install the Python package using `pip`:
+
+```sh
+pip install external-systems
+```
+
+## Basic Source Usage
+
+### HTTP Client
+
+For REST based sources, a preconfigured HTTP client is provided built on top of the Python requests library. For on-prem systems using [Agent Proxy](https://www.palantir.com/docs/foundry/data-connection/agent-proxy-runtime) the client will be pre-configured with the corresponding proxy
+
+```python
+from external_systems.sources import Source, HttpsConnection
+from requests import Session
+
+my_source: Source = ...
+
+https_connection: HttpsConnection = my_source.get_https_connection()
+
+source_url: str = https_connection.url
+http_client: Session = https_connection.get_client()
+
+response = http_client.get(source_url + "/api/v1/example/", timeout=10)
+```
+
+### Secrets
+
+Source secrets can be referenced using `get_secret("<secret_name>")` on the source.
+
+```python
+from external_systems.sources import Source
+
+my_source: Source = ...
+
+some_secret: str = 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()`. This method will throw if the source is not pre-configured with `AwsCredentials`
+
+_Session credentials may not be available in all Foundry runtime environments_
+
+```python
+from external_systems.sources import Source, Refreshable, AwsCredentials
+
+s3_source: Source = ...
+
+refreshable_credentials: Refreshable[AwsCredentials] = s3_source.get_aws_credentials()
+
+session_credentials: AwsCredentials = refreshable_credentials.get()
+```
+
+## On-prem Connectivity with [Foundry Agent Proxy](https://www.palantir.com/docs/foundry/data-connection/agent-proxy-runtime)
+
+### Socket
+
+For non-HTTP connections to external systems that require connections through Foundry's agent proxy, a pre-configured socket is provided.
+
+#### On-Prem SFTP Server Example
+
+For this example we'll be using the [fabric](https://docs.fabfile.org/en/latest/) library
+
+```python
+import fabric
+
+from external_systems.sources import Source
+from socket import socket
+
+SFTP_HOST = <sftp_host>
+SFTP_PORT = <sftp_port>
+
+on_prem_proxied_source: Source = ...
+
+username: str = on_prem_sftp_server.get_secret("username")
+password: str = on_prem_sftp_server.get_secret("password")
+
+proxy_socket: socket = source.create_socket(SFTP_HOST, SFTP_PORT)
+
+with fabric.Connection(
+    SFTP_HOST,
+    user=username,
+    port=SFTP_PORT,
+    connect_kwargs={
+        "password": password,
+        "sock": proxy_socket,
+    },
+) as conn:
+    sftp = conn.sftp()
+    file_list = sftp.listdir(".")
+```
+
+### Authenticated Proxy URI
+
+For more granular use cases a pre-authenticated proxy URI is provided to allow connections to on-prem external systems.
+
+#### Example
+
+We'll be using the [httpx](https://www.python-httpx.org/) library.
+
+```python
+import httpx
+
+from external_systems.sources import Source
+
+on_prem_system: Source = ...
+
+authenticated_proxy_uri: str = on_prem_system.get_https_proxy_uri()
+
+with httpx.Client(proxy=authenticated_proxy_uri) as client:
+    ...
+```
+

{external_systems-0.2.0.dist-info → external_systems-0.100.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
 external_systems/__init__.py,sha256=xXDUDD6_qRO-nHuXZx-fXp0R0vc3N_OOsB1F5mF_kpU,651
-external_systems/_version.py,sha256=0lRj_OZOFZq3DBCkEhXRBxwz0CJxq1Napd0Pbl0sZXk,747
+external_systems/_version.py,sha256=hjlDjGystUTnz8tbYT4EN9fUv5EDzQW6b4kjmTcz03s,749
 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=zb3QTACRR0MV0y2KZFXPdmWrZAQyrvLaaJ53wnqpP1E,10800
+external_systems/sources/_sockets.py,sha256=XH51adVnloqg8XYVHPxl6K8R_q2BCh6WZ77cq1L8nRg,4473
+external_systems/sources/_sources.py,sha256=-DP1QzuCtXOnsijwTNxI9x2vyEmxgyRB47ZTVQshfXA,10829
 external_systems/sources/_utils.py,sha256=EmUKKiKRDOZ2cZs7FZ4qCSan_lq1K_tquh3kxleB-jA,1004
-external_systems-0.2.0.dist-info/LICENSE.txt,sha256=NAk6Uc9K_N_J5V75k9qECpzUnO-ujT-mKK_jk_mboUE,569
-external_systems-0.2.0.dist-info/METADATA,sha256=4DYu6tUbWETeeerDDAgLdr_ySu0pSew0O-OOvTsLx6w,2694
-external_systems-0.2.0.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
-external_systems-0.2.0.dist-info/RECORD,,
+external_systems-0.100.0.dist-info/LICENSE.txt,sha256=NAk6Uc9K_N_J5V75k9qECpzUnO-ujT-mKK_jk_mboUE,569
+external_systems-0.100.0.dist-info/METADATA,sha256=3OYGduGNMYwz9ZI8KIlZRbBzFsNV9N1cJF3FKo6cxXI,4765
+external_systems-0.100.0.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+external_systems-0.100.0.dist-info/RECORD,,

external_systems-0.2.0.dist-info/METADATA

@@ -1,75 +0,0 @@
-Metadata-Version: 2.3
-Name: external-systems
-Version: 0.2.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)
-<a href="https://autorelease.general.dmz.palantir.tech/palantir/external-systems"><img src="https://img.shields.io/badge/Perform%20an-Autorelease-success.svg" alt="Autorelease"></a>
-
-> [!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)
-```
-