From 8c25e0049743903e607e17b4a4b03a747a66141f Mon Sep 17 00:00:00 2001 From: MoustaphaCamara Date: Mon, 6 Oct 2025 16:53:27 +0200 Subject: [PATCH 1/8] doc: update: setting up proxy with elabapi client configuration and other options --- README.md | 41 +++++++++++++++++++++++++++++++++++++++++ examples/client.py | 18 ++++++++++++++++++ 2 files changed, 59 insertions(+) diff --git a/README.md b/README.md index c3e9f42..52ba927 100644 --- a/README.md +++ b/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: diff --git a/examples/client.py b/examples/client.py index 9a6ebc3..8f33fec 100644 --- a/examples/client.py +++ b/examples/client.py @@ -26,6 +26,24 @@ # 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: + 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) From 2adffd2dbc2dbe2d87e8092e4a1e7a99c12e9374 Mon Sep 17 00:00:00 2001 From: MoustaphaCamara Date: Mon, 6 Oct 2025 16:56:24 +0200 Subject: [PATCH 2/8] safety: requests and other sub libs may not present same attributes --- examples/client.py | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/examples/client.py b/examples/client.py index 8f33fec..3f523c2 100644 --- a/examples/client.py +++ b/examples/client.py @@ -35,14 +35,26 @@ # 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 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 + # 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) From f730270d83cb8986d4cb65dc85fe7c0ecaa71ab7 Mon Sep 17 00:00:00 2001 From: MoustaphaCamara Date: Mon, 6 Oct 2025 17:26:09 +0200 Subject: [PATCH 3/8] harmonize code delimiters & remove leftover config proxy attribution --- README.md | 20 ++++++++++---------- examples/client.py | 1 - 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 52ba927..cb928b5 100644 --- a/README.md +++ b/README.md @@ -61,18 +61,18 @@ If you need to route your API traffic through a proxy (for example, to inspect r ### Using environment variables The simplest way is to define proxy settings via standard environment variables before running your script: -```bash +~~~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 +~~~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. @@ -80,7 +80,7 @@ Now run your script and confirm requests go through the proxy. Alternatively, you can set the proxy directly in your code: -```python +~~~python import elabapi_python # Initialize a configuration object from the library configuration = elabapi_python.Configuration() @@ -93,7 +93,7 @@ configuration.proxy = "http://127.0.0.1:8080" 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 @@ -109,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: @@ -124,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 diff --git a/examples/client.py b/examples/client.py index 3f523c2..bb35541 100644 --- a/examples/client.py +++ b/examples/client.py @@ -43,7 +43,6 @@ except Exception: # some generated clients don't expose 'proxy', so ignore safely pass - 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") From fa7b7e4a8a9d1955ce10f3de1f1774b133f3498e Mon Sep 17 00:00:00 2001 From: MoustaphaCamara Date: Tue, 7 Oct 2025 09:51:42 +0200 Subject: [PATCH 4/8] :koala: review, simplify client execution code & comments --- examples/client.py | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/examples/client.py b/examples/client.py index bb35541..750df92 100644 --- a/examples/client.py +++ b/examples/client.py @@ -32,28 +32,20 @@ # 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 +# 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: - # 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 + 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: - # 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 + 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) From 302cc755b4d8792d338147919965cdf8ed2bf86a Mon Sep 17 00:00:00 2001 From: MoustaphaCamara Date: Tue, 7 Oct 2025 10:18:56 +0200 Subject: [PATCH 5/8] :koala: update readme --- README.md | 35 +++-------------------------------- 1 file changed, 3 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index cb928b5..41b68de 100644 --- a/README.md +++ b/README.md @@ -56,43 +56,14 @@ 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. +The simplest way to route API traffic through a proxy is to set standard environment variables before running your script. -### 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" +# Avoid proxying local targets to prevent loops: 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) +export REQUESTS_CA_BUNDLE=/path/to/your/proxy-ca.pem ~~~ # Unofficial documentation From 213eec0d25c4fb1b6e5f7be35e8c82d8e5d24b0b Mon Sep 17 00:00:00 2001 From: MoustaphaCamara Date: Tue, 7 Oct 2025 17:54:42 +0200 Subject: [PATCH 6/8] update doc --- README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.md b/README.md index 41b68de..1f4adf2 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,18 @@ export NO_PROXY=localhost,127.0.0.1 export REQUESTS_CA_BUNDLE=/path/to/your/proxy-ca.pem ~~~ +### Configuration for the client + +~~~python +# 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: From 399d46cdda7b381afce8e453a3374d0dd7ea2b2d Mon Sep 17 00:00:00 2001 From: MoustaphaCamara Date: Tue, 7 Oct 2025 18:12:51 +0200 Subject: [PATCH 7/8] consistency --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 1f4adf2..fc0c4f6 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,12 @@ 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" From ed9101ebc37a203b76ad44d52698ab7fd01503c1 Mon Sep 17 00:00:00 2001 From: MoustaphaCamara Date: Fri, 24 Oct 2025 10:37:18 +0200 Subject: [PATCH 8/8] less verbose on the code & more on the text --- README.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index fc0c4f6..93b4307 100644 --- a/README.md +++ b/README.md @@ -56,32 +56,31 @@ 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. +To route API traffic through a proxy, set the standard environment variables before running the script. These variables are used by both the Python HTTP stack and the eLabFTW client. +### Environment configuration + +Set the following variables according to your proxy setup: + +- `HTTP_PROXY` and `HTTPS_PROXY`: Define the proxy server address, including the protocol and port (for example, `http://127.0.0.1:8080`). +- `NO_PROXY`: Specify hostnames or IPs that should bypass the proxy (for example, localhost or internal domains). +- `REQUESTS_CA_BUNDLE`: Optional path to a custom CA certificate file, required if the proxy intercepts HTTPS traffic with a self-signed certificate. + +Example: ~~~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 +export NO_PROXY="localhost,127.0.0.1" +export REQUESTS_CA_BUNDLE="/path/to/proxy-ca.pem" ~~~ -### Configuration for the client +### Client configuration + +The client automatically detects these environment variables. To set the proxy manually, use the configuration object: ~~~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