Merge pull request #102 from maxmind/greg/proxy

Allow setting a proxy

Author: horgh

HISTORY.rst

@@ -3,6 +3,12 @@
 History
 -------
 
+4.2.0
+++++++++++++++++++
+
+* You may now set a proxy to use when making web service request by passing
+  the ``proxy`` parameter to the ``AsyncClient`` or ``Client`` constructor.
+
 4.1.0 (2020-09-25)
 ++++++++++++++++++
 

README.rst

@@ -104,45 +104,50 @@ Async Web Service Example
 
 .. code-block:: pycon
 
+    >>> import asyncio
+    >>>
     >>> import geoip2.webservice
     >>>
-    >>> # This creates an AsyncClient object that can be reused across
-    >>> # requests on the running event loop. If you are using multiple event
-    >>> # loops, you must ensure the object is not used on another loop.
-    >>> #
-    >>> # Replace "42" with your account ID and "license_key" with your license
-    >>> # key.
-    >>> async with geoip2.webservice.AsyncClient(42, 'license_key') as client:
+    >>> async def main():
+    >>>     # This creates an AsyncClient object that can be reused across
+    >>>     # requests on the running event loop. If you are using multiple event
+    >>>     # loops, you must ensure the object is not used on another loop.
+    >>>     #
+    >>>     # Replace "42" with your account ID and "license_key" with your license
+    >>>     # key.
+    >>>     async with geoip2.webservice.AsyncClient(42, 'license_key') as client:
     >>>
-    >>>     # Replace "insights" with the method corresponding to the web service
-    >>>     # that you are using, e.g., "country", "city".
-    >>>     response = await client.insights('203.0.113.0')
+    >>>         # Replace "insights" with the method corresponding to the web service
+    >>>         # that you are using, e.g., "country", "city".
+    >>>         response = await client.insights('203.0.113.0')
     >>>
-    >>>     response.country.iso_code
+    >>>         response.country.iso_code
     'US'
-    >>>     response.country.name
+    >>>         response.country.name
     'United States'
-    >>>     response.country.names['zh-CN']
+    >>>         response.country.names['zh-CN']
     u'美国'
     >>>
-    >>>     response.subdivisions.most_specific.name
+    >>>         response.subdivisions.most_specific.name
     'Minnesota'
-    >>>     response.subdivisions.most_specific.iso_code
+    >>>         response.subdivisions.most_specific.iso_code
     'MN'
     >>>
-    >>>     response.city.name
+    >>>         response.city.name
     'Minneapolis'
     >>>
-    >>>     response.postal.code
+    >>>         response.postal.code
     '55455'
     >>>
-    >>>     response.location.latitude
+    >>>         response.location.latitude
     44.9733
-    >>>     response.location.longitude
+    >>>         response.location.longitude
     -93.2323
     >>>
-    >>>     response.traits.network
+    >>>         response.traits.network
     IPv4Network('203.0.113.0/32')
+    >>>
+    >>> asyncio.run(main())
 
 Web Service Client Exceptions
 -----------------------------

geoip2/webservice.py

@@ -27,7 +27,7 @@
 
 import ipaddress
 import json
-from typing import Any, cast, List, Optional, Type, Union
+from typing import Any, Dict, cast, List, Optional, Type, Union
 
 import aiohttp
 import aiohttp.http
@@ -248,10 +248,14 @@ class AsyncClient(BaseClient):
     :param timeout: The timeout in seconts to use when waiting on the request.
       This sets both the connect timeout and the read timeout. The default is
       60.
+    :param proxy: The URL of an HTTP proxy to use. It may optionally include
+      a basic auth username and password, e.g.,
+      ``http://username:password@host:port``.
 
     """
 
     _existing_session: aiohttp.ClientSession
+    _proxy: Optional[str]
 
     def __init__(  # pylint: disable=too-many-arguments
         self,
@@ -260,6 +264,7 @@ def __init__(  # pylint: disable=too-many-arguments
         host: str = "geoip.maxmind.com",
         locales: Optional[List[str]] = None,
         timeout: float = 60,
+        proxy: Optional[str] = None,
     ) -> None:
         super().__init__(
             account_id,
@@ -268,6 +273,7 @@ def __init__(  # pylint: disable=too-many-arguments
             locales,
             timeout,
         )
+        self._proxy = proxy
 
     async def city(self, ip_address: IPAddress = "me") -> City:
         """Call GeoIP2 Precision City endpoint with the specified IP.
@@ -331,7 +337,7 @@ async def _response_for(
     ) -> Union[Country, City, Insights]:
         uri = self._uri(path, ip_address)
         session = await self._session()
-        async with await session.get(uri) as response:
+        async with await session.get(uri, proxy=self._proxy) as response:
             status = response.status
             content_type = response.content_type
             body = await response.text()
@@ -398,10 +404,15 @@ class Client(BaseClient):
     :param timeout: The timeout in seconts to use when waiting on the request.
       This sets both the connect timeout and the read timeout. The default is
       60.
+    :param proxy: The URL of an HTTP proxy to use. It may optionally include
+      a basic auth username and password, e.g.,
+      ``http://username:password@host:port``.
+
 
     """
 
     _session: requests.Session
+    _proxies: Optional[Dict[str, str]]
 
     def __init__(  # pylint: disable=too-many-arguments
         self,
@@ -410,12 +421,17 @@ def __init__(  # pylint: disable=too-many-arguments
         host: str = "geoip.maxmind.com",
         locales: Optional[List[str]] = None,
         timeout: float = 60,
+        proxy: Optional[str] = None,
     ) -> None:
         super().__init__(account_id, license_key, host, locales, timeout)
         self._session = requests.Session()
         self._session.auth = (self._account_id, self._license_key)
         self._session.headers["Accept"] = "application/json"
         self._session.headers["User-Agent"] = _REQUEST_UA
+        if proxy is None:
+            self._proxies = None
+        else:
+            self._proxies = {"https": proxy}
 
     def city(self, ip_address: IPAddress = "me") -> City:
         """Call GeoIP2 Precision City endpoint with the specified IP.
@@ -464,7 +480,7 @@ def _response_for(
         ip_address: IPAddress,
     ) -> Union[Country, City, Insights]:
         uri = self._uri(path, ip_address)
-        response = self._session.get(uri, timeout=self._timeout)
+        response = self._session.get(uri, proxies=self._proxies, timeout=self._timeout)
         status = response.status_code
         content_type = response.headers["Content-Type"]
         body = response.text

setup.cfg

@@ -9,7 +9,7 @@ max-line-length = 88
 universal = 1
 
 [tox:tox]
-envlist = py36, py37, py38, mypy
+envlist = py36, py37, py38, py39, mypy
 
 [gh-actions]
 python =