doc & example: update: setting up proxy

README.md

@@ -54,6 +54,47 @@ exp_client = elabapi_python.ExperimentsApi(api_client)
 items_client = elabapi_python.ItemsApi(api_client)
 ~~~
 
+## Using a proxy
+
+If you need to route your API traffic through a proxy (for example, to inspect requests with `mitmproxy` or to access eLabFTW behind a corporate network), you can configure it directly in the API client.
+
+### Using environment variables
+
+The simplest way is to define proxy settings via 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"
+export NO_PROXY=localhost,127.0.0.1
+~~~
+
+Open a new terminal and run a proxy (e.g., mitmproxy)
+
+~~~bash
+pip install mitmproxy
+mitmdump --listen-host 0.0.0.0 --listen-port 8080 --ssl-insecure
+~~~
+
+Now run your script and confirm requests go through the proxy.
+
+### Using the Configuration object
+
+Alternatively, you can set the proxy directly in your code:
+
+~~~python
+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 = "http://127.0.0.1:8080"
+# or using Docker, something like "http://host.docker.internal:8080"
+# Optionally, specify a path to a custom CA certificate (e.g. mitmproxy)
+configuration.ssl_ca_cert = "/path/to/mitmproxy-ca.pem"
+# Create an API client object with the configuration
+api_client = elabapi_python.ApiClient(configuration)
+~~~
+
 # Unofficial documentation
 
 From TU Graz, Shared RDM Project:
@@ -68,13 +109,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 +124,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,35 @@
 # 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
+# setup proxy to elabapi client's config
+proxy_url = os.getenv("HTTPS_PROXY") or os.getenv("HTTP_PROXY")
+if proxy_url:
+    # make sure underlying libraries also see the proxy (requests / subprocesses)
+    os.environ.setdefault("HTTPS_PROXY", proxy_url)
+    os.environ.setdefault("HTTP_PROXY", proxy_url)
+    try:
+        configuration.proxy = proxy_url
+    except Exception:
+        # some generated clients don't expose 'proxy', so ignore safely
+        pass
+
+# set CA for both requests and the elabapi-client
+ca_path = os.getenv("CA_PATH") or os.getenv("REQUESTS_CA_BUNDLE")
+if ca_path:
+    # let requests (and other libs) use this CA bundle unless already set
+    os.environ.setdefault("REQUESTS_CA_BUNDLE", ca_path)
+    try:
+        configuration.ssl_ca_cert = ca_path
+    except Exception:
+        # attribute may not exist on all generated configurations
+        pass
+
 # Create an API client object with our configuration
 api_client = elabapi_python.ApiClient(configuration)