How to properly use Client in a class?

[secsilm]

I have code like this:

class Predictor:
    def __init__(self, url) -> None:
        self.url = url
        self.client = httpx.Client()

    def predict(self, text):
        r = self.client.get(self.url)
        # some codes ...

Do I need to close the client explicitly?

[amasen02]

Yes, you should explicitly close the client.

Why Explicit Cleanup Matters

Under the hood, httpx.Client does much more than make one-off HTTP requests: it initializes an underlying connection pool (httpcore.ConnectionPool) that maintains open TCP sockets, active TLS/SSL contexts, and keep-alive connections for reuse.

If you don't explicitly close the client:

1. Socket & File Descriptor Leaks: Relying on Python's garbage collector (__del__) to close sockets is nondeterministic. If instances of Predictor are created frequently or stored in cycles, open sockets remain alive, leading to ResourceWarning: unclosed <socket.socket ...> warnings or OS file descriptor exhaustion (EMFILE: too many open files).
2. Keep-Alive Hangs: Active keep-alive connections may keep worker threads or sockets alive until remote server timeouts expire.

---

Recommended Architectural Patterns

Depending on how Predictor is used in your system, here are the three standard patterns:

Pattern 1: Make Predictor a Context Manager (Idiomatic & Self-Contained)

If Predictor has a well-defined lifecycle within a script or batch process:

import httpx
from typing import Optional

class Predictor:
    def __init__(self, url: str) -> None:
        self.url = url
        self.client: Optional[httpx.Client] = None

    def __enter__(self) -> "Predictor":
        self.client = httpx.Client(timeout=10.0)
        return self

    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
        if self.client is not None:
            self.client.close()

    def predict(self, text: str):
        if self.client is None or self.client.is_closed:
            raise RuntimeError("Predictor must be used within a 'with' context block.")
        return self.client.post(self.url, json={"text": text})


# Usage:
with Predictor("https://api.example.com/predict") as predictor:
    result = predictor.predict("sample text")

---

Pattern 2: Dependency Injection (Production Best Practice for Web APIs / Microservices)

In high-throughput services (like FastAPI, Flask, or background worker fleets), creating a new httpx.Client inside each service class is an anti-pattern because it destroys connection reuse and incurs repeated TLS handshakes.

Instead, inject a shared client managed by the application lifecycle:

import httpx

class Predictor:
    def __init__(self, url: str, client: httpx.Client) -> None:
        self.url = url
        self.client = client

    def predict(self, text: str):
        return self.client.post(self.url, json={"text": text})


# Application / service level:
with httpx.Client(
    limits=httpx.Limits(max_keepalive_connections=20, max_connections=50),
    timeout=httpx.Timeout(10.0, connect=5.0)
) as shared_client:
    predictor = Predictor(url="https://api.example.com/predict", client=shared_client)
    result = predictor.predict("sample text")

---

Pattern 3: Expose an Explicit close() Method

If you need Predictor to be instantiated directly and passed around over a longer lifespan, expose an explicit close() method alongside context manager support:

import httpx

class Predictor:
    def __init__(self, url: str) -> None:
        self.url = url
        self.client = httpx.Client(timeout=10.0)

    def predict(self, text: str):
        return self.client.post(self.url, json={"text": text})

    def close(self) -> None:
        self.client.close()

    def __enter__(self) -> "Predictor":
        return self

    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
        self.close()

---

Note

If you ever migrate this class to httpx.AsyncClient (e.g. for asyncio), explicit cleanup is mandatory via await client.aclose() or async with, because Python's garbage collector cannot reliably await coroutines during finalization.