@@ -6,10 +6,33 @@ on:
       - master
     tags:
       - '*'
+  pull_request:
 
 jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install -r requirements.txt
+    - name: Test with pytest (offline tests only, no API key needed)
+      run: |
+        python -m pytest -m "not api"
+
   build-n-publish:
     name: Build and publish to PyPI
+    if: github.event_name == 'push'
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
 
@@ -21,6 +21,7 @@ Visit our [Documentation](https://docs.ipdata.co/) for more examples and tutoria
   - [Getting only one field](#getting-only-one-field)
   - [Getting a number of specific fields](#getting-a-number-of-specific-fields)
   - [Bulk Lookups](#bulk-lookups)
+  - [Connection reuse and HTTP/2](#connection-reuse-and-http2)
 - [Using the ipdata CLI](#using-the-ipdata-cli)
   - [Windows Installation Notes](#windows-installation-notes)
   - [Available commands](#available-commands)
@@ -367,6 +368,24 @@ NOTE: Alternatively it is much simpler to process bulk lookups using the `ipdata
 ```
 </details>
 
+### Connection reuse and HTTP/2
+
+An `IPData` client keeps a persistent HTTPS connection pool for as long as it lives. Create one client per process (or one per API key or endpoint), keep it, and reuse it for every lookup: each new client pays a fresh TLS handshake. Requests to api.ipdata.co are multiplexed over HTTP/2 when the platform negotiates it, and fall back to HTTP/1.1 keep-alive otherwise.
+
+The client is built on [httpx](https://www.python-httpx.org/) and is thread-safe: one instance can serve every thread of a process at once (the CLI's `batch` command shares a single client across its thread pool). Idle connections are kept open for 60 seconds and up to 20 connections are pooled. Call `close()` at shutdown, or use the client as a context manager, to release the pool. Pass `http2=False` to stay on HTTP/1.1 keep-alive, or `transport=` to inject your own `httpx.BaseTransport` (for example an `httpx.MockTransport` in tests).
+
+```python
+from ipdata import IPData
+
+with IPData("<YOUR API KEY>") as client:  # one client, many lookups
+    for ip in ["8.8.8.8", "1.1.1.1"]:
+        print(client.lookup(ip).country_name)
+```
+
+The module-level helpers `ipdata.lookup()` and `ipdata.bulk()` share one process-wide client, `ipdata.default_client`, which is created on first use and lives until the process exits. Connections must not be shared across `os.fork()` or `multiprocessing` boundaries: create your `IPData` instance (or make the first module-level call) in the child process, after forking.
+
+Failed requests are retried up to `retry_limit` times (default 7). GET and POST requests that fail with a transport error (connection reset, timeout) or with HTTP 500, 502, 503 or 504 are retried with exponential backoff: 0.5, 1, 2, 4, 8, 16 and 32 seconds for the default `retry_backoff_factor=1`. A 429 response is retried only when it carries a `Retry-After` header (waiting at most 60 seconds); without one it is returned immediately, so an exhausted quota fails fast. The `HTTPS_PROXY` and `NO_PROXY` environment variables are honoured; a custom CA bundle is read from `SSL_CERT_FILE` (httpx does not read `REQUESTS_CA_BUNDLE`).
+
 ## Using the ipdata CLI
 
 
@@ -754,3 +773,9 @@ To run all tests
 ```shell
 pytest
 ```
+
+The tests marked `api` call the live API and need an `IPDATA_API_KEY` environment variable (or a `src/ipdata/.env` file). To run only the offline tests, as CI does for pull requests:
+
+```shell
+pytest -m "not api"
+```
@@ -1,4 +1,4 @@
-requests
+httpx[http2]>=0.28,<1
 rich
 click
 click_default_group
 
@@ -1,6 +1,6 @@
 [metadata]
 name = ipdata
-version = 4.0.9
+version = 4.1.0
 author = Jonathan Kosgei
 author_email = jonathan@ipdata.co
 description = This is the official IPData client library for Python
@@ -24,7 +24,7 @@ package_dir =
 packages = find:
 python_requires = >=3.9
 install_requires =
-    requests
+    httpx[http2]>=0.28,<1
     rich
     click
     click_default_group
 
@@ -8,7 +8,7 @@
 import random
 from pathlib import Path
 
-import requests
+import httpx
 
 from .codes import COUNTRIES, REGION_CODES
 
@@ -49,7 +49,7 @@ def _download(self):
         cache_path = f"{self.dir}/{random_name}.csv"
 
         try:
-            response = requests.get(self.source, timeout=60)
+            response = httpx.get(self.source, timeout=60, follow_redirects=True)
             text = response.text
             with open(cache_path, "w") as f:
                 f.write(
 
@@ -18,18 +18,32 @@
 :class:`~.IPData` is the primary class for making API requests.
 """
 
-import os
+import email.utils
+import importlib.metadata
 import ipaddress
-import requests
 import logging
-import urllib3
-import functools
+import os
+import time
+from datetime import datetime, timezone
 
-from requests.adapters import HTTPAdapter, Retry
+import httpx
 
 logger = logging.getLogger(__name__)
 logger.addHandler(logging.NullHandler())
 
+try:
+    __version__ = importlib.metadata.version("ipdata")
+except importlib.metadata.PackageNotFoundError:  # running from a source checkout
+    __version__ = "unknown"
+
+# HTTP statuses that are retried, for GET and POST requests alike
+RETRY_STATUSES = frozenset({500, 502, 503, 504})
+# Longest pause honoured from a 429 Retry-After header, in seconds
+MAX_RETRY_AFTER = 60.0
+
+# Seam for the tests, which replace it to check the retry schedule without sleeping
+_sleep = time.sleep
+
 
 class IPDataException(Exception):
     pass
@@ -57,12 +71,26 @@ class IPData(object):
     """
     Instances of IPData are used to make API requests. To make requests to the EU endpoint, set "endpoint" to "https://eu-api.ipdata.co".
 
+    Every instance owns one HTTPS connection pool that is kept alive and reused for all of its requests
+    (multiplexed over HTTP/2 when the server negotiates it, HTTP/1.1 keep-alive otherwise), so create one
+    client per process (or per API key or endpoint), reuse it for every lookup and call :meth:`close` (or use
+    the instance as a context manager) when you are done with it. Instances are thread-safe. A client must
+    be created after forking: never share one across os.fork() or multiprocessing boundaries.
+
+    Failed requests are retried up to 'retry_limit' times. GET and POST requests that fail with a transport
+    error (connection reset, timeout, ...) or with HTTP 500, 502, 503 or 504 are retried after sleeping
+    retry_backoff_factor * 2 ** (attempt - 2) seconds, i.e. 0.5, 1, 2, 4, 8, 16 and 32 seconds with the
+    defaults. HTTP 429 is retried only when the response carries a Retry-After header (sleeping at most 60
+    seconds); without one the response is returned immediately so that an exhausted quota fails fast.
+
     :param api_key: A valid IPData API key
     :param endpoint: The API endpoint to send requests to
-    :param timeout: The default requests timeout
+    :param timeout: The default requests timeout in seconds, applied to every request including bulk lookups
     :param retry_limit: The maximum number of retries in case of failure
     :param retry_backoff_factor: The number of seconds to sleep in between retries. With a 1 second backoff calls with be retried up to 7 times at the following intervals: 0.5, 1, 2, 4, 8, 16, 32
     :param debug: A boolean used to set the log level. Set to True when debugging.
+    :param http2: Negotiate HTTP/2 with automatic fallback to HTTP/1.1. Set to False to use HTTP/1.1 keep-alive only.
+    :param transport: An optional httpx.BaseTransport used instead of the default HTTPS transport, for example an httpx.MockTransport in tests
     """
 
     log = logging.getLogger(__name__)
@@ -103,6 +131,8 @@ def __init__(
         retry_limit=7,
         retry_backoff_factor=1,
         debug=False,
+        http2=True,
+        transport=None,
     ):
         if api_key is None:
             api_key = os.environ.get("IPDATA_API_KEY")
@@ -112,7 +142,12 @@ def __init__(
         self.api_key = api_key
         self.endpoint = endpoint.rstrip("/")  # remove trailing /
         self._timeout = timeout
-        self._headers = {"user-agent": "ipdata-python"}  # set default UserAgent
+        self._retry_limit = retry_limit
+        self._retry_backoff_factor = retry_backoff_factor
+        self._headers = {
+            "user-agent": f"ipdata-python/{__version__}",  # set default UserAgent
+            "accept": "application/json",
+        }
         self._query_params = {"api-key": self.api_key}
 
         # Enable debugging
@@ -126,24 +161,37 @@ def __init__(
                 handler.setFormatter(logging.Formatter("%(message)s", datefmt="[%X]"))
                 self.log.addHandler(handler)
 
-        # Work around renamed argument in urllib3.
-        if hasattr(urllib3.util.Retry.DEFAULT, "allowed_methods"):
-            methods_arg = "allowed_methods"
-        else:
-            methods_arg = "method_whitelist"
-
-        # Retry settings
-        retry_args = {
-            "total": retry_limit,
-            "backoff_factor": retry_backoff_factor,
-            "status_forcelist": [429, 500, 502, 503, 504],
-            methods_arg: {"POST"},
-        }
+        # One connection pool per client instance. Connections are kept alive for 60 seconds and reused
+        # across requests (multiplexed over HTTP/2 when the server negotiates it, HTTP/1.1 keep-alive
+        # otherwise) instead of paying a TCP + TLS handshake per call. When no transport is injected
+        # httpx builds its default one, which honours HTTPS_PROXY / NO_PROXY and the SSL_CERT_* variables
+        # like requests did; with an injected transport httpx uses it as-is and ignores http2 and limits.
+        self._client = httpx.Client(
+            base_url=self.endpoint,
+            http2=http2,
+            timeout=httpx.Timeout(timeout),
+            headers=self._headers,
+            params=self._query_params,
+            limits=httpx.Limits(
+                max_connections=20, max_keepalive_connections=20, keepalive_expiry=60.0
+            ),
+            transport=transport,
+        )
+
+    def close(self):
+        """
+        Closes the connection pool. The instance can not be used afterwards. Call this at shutdown, or use the instance as a context manager:
+
+            >>> with IPData("YOUR API KEY") as ipdata:
+            ...     ipdata.lookup("8.8.8.8")
+        """
+        self._client.close()
 
-        adapter = HTTPAdapter(max_retries=urllib3.Retry(**retry_args))
+    def __enter__(self):
+        return self
 
-        self._session = requests.Session()
-        self._session.mount("http", adapter)
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
 
     def _validate_fields(self, fields):
         """
@@ -173,6 +221,74 @@ def _validate_ip_address(self, ip):
         if request_ip.is_private or request_ip.is_reserved or request_ip.is_multicast:
             raise ValueError(f"{ip} is a reserved IP Address")
 
+    def _backoff(self, attempt):
+        """
+        Seconds to sleep before retry number 'attempt' (1-based): 0.5, 1, 2, 4, 8, 16, 32 with the default backoff factor.
+        """
+        return self._retry_backoff_factor * 2 ** (attempt - 2)
+
+    @staticmethod
+    def _retry_after(value):
+        """
+        Parses a Retry-After header, given either as delay-seconds or as an HTTP-date.
+
+        :returns: The number of seconds to wait, or None if the value can not be parsed
+        """
+        value = value.strip()
+        if value.isdigit():
+            return float(value)
+        try:
+            when = email.utils.parsedate_to_datetime(value)
+        except (TypeError, ValueError):
+            return None
+        if when.tzinfo is None:
+            when = when.replace(tzinfo=timezone.utc)
+        return max((when - datetime.now(timezone.utc)).total_seconds(), 0.0)
+
+    def _request(self, method, path, **kwargs):
+        """
+        Sends a request over the shared connection pool, retrying it as described in the class docstring.
+
+        :returns: The last httpx.Response received
+        :raises httpx.TransportError: if the request still fails to get a response once the retries are exhausted
+        """
+        attempt = 0
+        while True:
+            attempt += 1
+            try:
+                response = self._client.request(method, path, **kwargs)
+            except httpx.UnsupportedProtocol:
+                raise  # a configuration error that no retry can fix
+            except httpx.TransportError as e:
+                if attempt > self._retry_limit:
+                    raise
+                delay = self._backoff(attempt)
+                reason = f"{type(e).__name__}: {e}"
+            else:
+                status_code = response.status_code
+                if attempt > self._retry_limit:
+                    return response
+                if status_code in RETRY_STATUSES:
+                    delay = self._backoff(attempt)
+                elif status_code == 429 and "retry-after" in response.headers:
+                    delay = self._retry_after(response.headers["retry-after"])
+                    if delay is None:
+                        delay = self._backoff(attempt)
+                    delay = min(delay, MAX_RETRY_AFTER)
+                else:
+                    return response
+                reason = f"HTTP {status_code}"
+            self.log.debug(
+                "Retrying %s %s in %.1fs (retry %d of %d) after %s",
+                method,
+                path,
+                delay,
+                attempt,
+                self._retry_limit,
+                reason,
+            )
+            _sleep(delay)
+
     def lookup(self, resource="", fields=[], select_field=None):
         """
         Makes a GET request to the IPData API for the specified 'resource' and the given 'fields'.
@@ -204,16 +320,11 @@ def lookup(self, resource="", fields=[], select_field=None):
             fields = [select_field]
 
         self._validate_fields(fields)
-        query_params = self._query_params | {"fields": ",".join(fields)}
+        query_params = {"fields": ",".join(fields)}
 
         # Make the request
         try:
-            response = self._session.get(
-                f"{self.endpoint}/{resource}",
-                headers=self._headers,
-                params=query_params,
-                timeout=self._timeout,
-            )
+            response = self._request("GET", f"/{resource}", params=query_params)
         except Exception as e:
             raise IPDataException(e)
 
@@ -253,16 +364,11 @@ def bulk(self, resources, fields=[]):
             raise ValueError("Bulk lookups must contain at least 1 resource.")
 
         self._validate_fields(fields)
-        query_params = self._query_params | {"fields": ",".join(fields)}
+        query_params = {"fields": ",".join(fields)}
 
         # Make the requests
         try:
-            response = self._session.post(
-                f"{self.endpoint}/bulk",
-                headers=self._headers,
-                params=query_params,
-                json=resources,
-            )
+            response = self._request("POST", "/bulk", params=query_params, json=resources)
         except Exception as e:
             raise IPDataException(f"Error when looking up {resources} - {e}")
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-requests`
	`1`	`+httpx[http2]>=0.28,<1`
`2`	`2`	`rich`
`3`	`3`	`click`
`4`	`4`	`click_default_group`