overlapping/nested context managers on one instance are not supported

Author: mtmail

Changes.txt

@@ -1,3 +1,6 @@
+unreleased
+  Add warning and safeguard that overlapping/nested context managers on one instance aren't supported
+
 v3.4.0 Mon Jun 09 2026
   CLI tool extracted to separate `opencage-cli` package and repository (https://github.com/OpenCageData/opencage-cli)
 

opencage/geocoder.py

@@ -203,6 +203,17 @@ def __init__(
         self.user_agent_comment = user_agent_comment
 
     def __enter__(self):
+        """Open a pooled requests session for sync geocoding.
+
+        Overlapping or nested ``with`` blocks on the same instance are
+        not supported and will raise ``RuntimeError`` to prevent silently
+        leaking the previous session's connection pool.
+        """
+        if self.session is not None:
+            raise RuntimeError(
+                "OpenCageGeocode context already entered; "
+                "overlapping `with` blocks on the same instance are not supported."
+            )
         self.session = requests.Session()
         return self
 
@@ -212,9 +223,20 @@ def __exit__(self, *args):
         return False
 
     async def __aenter__(self):
+        """Open a pooled aiohttp session for async geocoding.
+
+        Overlapping or nested ``async with`` blocks on the same instance
+        are not supported and will raise ``RuntimeError`` to prevent
+        silently leaking the previous session's connection pool.
+        """
         if not AIOHTTP_AVAILABLE:
             raise AioHttpError("You must install `aiohttp` to use async methods")
 
+        if self.session is not None:
+            raise RuntimeError(
+                "OpenCageGeocode context already entered; "
+                "overlapping `async with` blocks on the same instance are not supported."
+            )
         self.session = aiohttp.ClientSession()
         return self