docs(python): Document SDK connection config (#14043)

Author: dustinbyrne

contents/docs/libraries/python/index.mdx

@@ -227,6 +227,50 @@ if settings.TEST:
     posthog.disabled = True
 ```
 
+## Connection configuration
+
+The SDK uses HTTP connection pooling internally for better performance. These settings typically need not be changed, but in some environments, such as when running behind NAT gateways, pooled connections may be terminated non-gracefully, causing request failures.
+
+You can configure connection behavior in several ways. The following settings should be called during initialization, before any API requests are made.
+
+### Enable TCP keepalive
+
+TCP keepalive probes help prevent idle connections from being dropped by network infrastructure. This is the recommended approach for most cases where idle connections are terminated.
+
+```python
+import posthog
+
+posthog.enable_keep_alive()
+```
+
+This enables TCP keepalive with sensible defaults (60 second idle time, 60 second probe interval, 3 probes before timeout).
+
+### Disable connection pooling
+
+If you need each request to use a fresh connection, you can disable connection reuse entirely. This will incur additional overhead per request but may be desirable in some circumstances.
+
+```python
+import posthog
+
+posthog.disable_connection_reuse()
+```
+
+### Custom HTTP socket options
+
+For advanced use cases, you can configure arbitrary socket options on the underlying HTTP connection.
+
+```python
+import socket
+import posthog
+
+posthog.set_socket_options([
+    (socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1),
+    # Add additional socket options as needed
+])
+```
+
+Pass `None` to `set_socket_options()` to reset to default behavior.
+
 ## Historical migrations
 
 You can use the Python or Node SDK to run [historical migrations](/docs/migrate) of data into PostHog. To do so, set the `historical_migration` option to `true` when initializing the client.