doc & example: update: setting up proxy

README.md

@@ -54,6 +54,36 @@ exp_client = elabapi_python.ExperimentsApi(api_client)
 items_client = elabapi_python.ItemsApi(api_client)
 ~~~
 
+## Using a proxy
+
+The simplest way to route API traffic through a proxy is to set standard environment variables before running your script.
+
+~~~bash
+export HTTP_PROXY="http://127.0.0.1:8080"
+export HTTPS_PROXY="http://127.0.0.1:8080"
+# Avoid proxying local targets to prevent loops:
+export NO_PROXY=localhost,127.0.0.1
+export REQUESTS_CA_BUNDLE=/path/to/your/proxy-ca.pem
+~~~
+
+### Configuration for the client
+
+~~~python
+import os
+import elabapi_python
+# Initialize a configuration object from the library
+configuration = elabapi_python.Configuration()
+# Set the host
+configuration.host = "https://eln.example.org/api/v2"
+# Set a proxy URL (supports HTTP and HTTPS)
+configuration.proxy = os.getenv("HTTPS_PROXY") or os.getenv("HTTP_PROXY")
+# or using Docker, something close to "http://host.docker.internal:8080"
+# Optionally, specify a path to a custom CA certificate (e.g. mitmproxy)
+configuration.ssl_ca_cert = os.getenv("CA_PATH") or os.getenv("REQUESTS_CA_BUNDLE")
+# Create an API client object with the configuration
+api_client = elabapi_python.ApiClient(configuration)
+~~~
+
 # Unofficial documentation
 
 From TU Graz, Shared RDM Project:
@@ -68,13 +98,13 @@ From TU Graz, Shared RDM Project:
 
 The primary tool for generating the library is swagger-codegen. However, you can also use OpenAPI Generator as an alternative, if it better suits your requirements or you encounter issues with the default.
 
-```bash
+~~~bash
 # Option 1: Generate using Swagger Codegen
 ./helper.sh generate
 
 # Option 2: Generate using OpenAPI Generator
 GENERATOR_TOOL=openapi ./helper.sh generate
-```
+~~~
 
 ### Or Generate from a local OpenAPI Specification
 Ensure the `openapi.yaml` file is located in the current working directory, then run:
@@ -83,9 +113,9 @@ Ensure the `openapi.yaml` file is located in the current working directory, then
 ~~~
 
 ### Build packages
-```bash
+~~~bash
 ./helper.sh build
-```
+~~~
 
 ## Installing the library for dev
 

examples/client.py

@@ -26,6 +26,27 @@
 # Set this flag to True to get more verbose output
 configuration.debug = False
 
+# PROXY CONFIG
+# Typical usage:
+#   export HTTP_PROXY="http://127.0.0.1:8080"
+#   export HTTPS_PROXY="http://127.0.0.1:8080"
+#   export NO_PROXY=localhost,127.0.0.1
+#   export REQUESTS_CA_BUNDLE=/path/to/mitmproxy-ca.pem
+# Many libraries (e.g. 'requests') read HTTP(S)_PROXY from the environment automatically.
+# However the generated elabapi_python client uses a generated Configuration + urllib3
+# which may not read those env vars. That is why we set the env vars along with 'configuration.proxy'
+# and 'configuration.ssl_ca_cert' so the generated client itself uses the proxy and trust bundle.
+proxy_url = os.getenv("HTTPS_PROXY") or os.getenv("HTTP_PROXY")
+if proxy_url:
+    configuration.proxy = proxy_url
+
+# set CA for both requests and the elabapi-client
+ca_path = os.getenv("CA_PATH") or os.getenv("REQUESTS_CA_BUNDLE")
+if ca_path:
+    configuration.ssl_ca_cert = ca_path
+    if not os.getenv("REQUESTS_CA_BUNDLE"):
+        os.environ["REQUESTS_CA_BUNDLE"] = ca_path
+
 # Create an API client object with our configuration
 api_client = elabapi_python.ApiClient(configuration)