Merge pull request #200 from maxmind/greg/eng-1812

Add GeoIP Anonymous Plus and clean up docs

Author: marselester

HISTORY.rst

@@ -4,6 +4,13 @@
 History
 -------
 
+5.1.0
+++++++++++++++++++
+
+* Support for the GeoIP Anonymous Plus database has been added. To do a lookup
+  in this database, use the ``anonymous_plus`` method on ``Reader``.
+
+
 5.0.1 (2025-01-28)
 ++++++++++++++++++
 

README.rst

@@ -268,6 +268,42 @@ Anonymous IP Database
     >>>     response.network
     IPv4Network('203.0.113.0/24')
 
+Anonymous Plus Database
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: pycon
+
+    >>> import geoip2.database
+    >>>
+    >>> # This creates a Reader object. You should use the same object
+    >>> # across multiple requests as creation of it is expensive.
+    >>> with geoip2.database.Reader('/path/to/GeoIP-Anonymous-Plus.mmdb') as reader:
+    >>>
+    >>>     response = reader.anonymous_plus('203.0.113.0')
+    >>>
+    >>>     response.anonymizer_confidence
+    30
+    >>>     response.is_anonymous
+    True
+    >>>     response.is_anonymous_vpn
+    True
+    >>>     response.is_hosting_provider
+    False
+    >>>     response.is_public_proxy
+    False
+    >>>     response.is_residential_proxy
+    False
+    >>>     response.is_tor_exit_node
+    False
+    >>>     response.ip_address
+    '203.0.113.0'
+    >>>     response.network
+    IPv4Network('203.0.113.0/24')
+    >>>     response.network_last_seen
+    datetime.date(2025, 4, 18)
+    >>>     response.provider_name
+    FooBar VPNs
+
 ASN Database
 ^^^^^^^^^^^^
 

docs/index.rst

@@ -8,27 +8,55 @@
 
 .. include:: ../README.rst
 
-=======
-Modules
-=======
-
 .. automodule:: geoip2
     :members:
+    :inherited-members:
+    :show-inheritance:
+
+===============
+Database Reader
+===============
 
 .. automodule:: geoip2.database
     :members:
+    :inherited-members:
+    :show-inheritance:
+
+==================
+WebServices Client
+==================
 
 .. automodule:: geoip2.webservice
     :members:
+    :inherited-members:
+    :show-inheritance:
+
+======
+Models
+======
 
 .. automodule:: geoip2.models
     :members:
+    :inherited-members:
+    :show-inheritance:
+
+=======
+Records
+=======
 
 .. automodule:: geoip2.records
     :members:
+    :inherited-members:
+    :show-inheritance:
+
+======
+Errors
+======
 
 .. automodule:: geoip2.errors
     :members:
+    :inherited-members:
+    :show-inheritance:
 
 ==================
 Indices and tables

geoip2/_internal.py

@@ -1,4 +1,4 @@
-"""This package contains internal utilities."""
+"""Internal utilities."""
 
 # pylint: disable=too-few-public-methods
 from abc import ABCMeta
@@ -15,7 +15,7 @@ def __ne__(self, other) -> bool:
 
     # pylint: disable=too-many-branches
     def to_dict(self) -> dict:
-        """Returns a dict of the object suitable for serialization."""
+        """Return a dict of the object suitable for serialization."""
         result = {}
         for key, value in self.__dict__.items():
             if key.startswith("_"):

geoip2/database.py

@@ -1,9 +1,4 @@
-"""
-======================
-GeoIP2 Database Reader
-======================
-
-"""
+"""The database reader for MaxMind MMDB files."""
 
 import inspect
 import os
@@ -27,6 +22,7 @@
     ASN,
     ISP,
     AnonymousIP,
+    AnonymousPlus,
     City,
     ConnectionType,
     Country,
@@ -167,6 +163,23 @@ def anonymous_ip(self, ip_address: IPAddress) -> AnonymousIP:
             ),
         )
 
+    def anonymous_plus(self, ip_address: IPAddress) -> AnonymousPlus:
+        """Get the AnonymousPlus object for the IP address.
+
+        :param ip_address: IPv4 or IPv6 address as a string.
+
+        :returns: :py:class:`geoip2.models.AnonymousPlus` object
+
+        """
+        return cast(
+            AnonymousPlus,
+            self._flat_model_for(
+                geoip2.models.AnonymousPlus,
+                "GeoIP-Anonymous-Plus",
+                ip_address,
+            ),
+        )
+
     def asn(self, ip_address: IPAddress) -> ASN:
         """Get the ASN object for the IP address.
 

geoip2/errors.py

@@ -1,11 +1,6 @@
-"""
-Errors
-======
-
-"""
+"""Typed errors thrown by this library."""
 
 import ipaddress
-
 from typing import Optional, Union
 
 
@@ -19,26 +14,12 @@ class GeoIP2Error(RuntimeError):
 
 
 class AddressNotFoundError(GeoIP2Error):
-    """The address you were looking up was not found.
-
-    .. attribute:: ip_address
-
-      The IP address used in the lookup. This is only available for database
-      lookups.
-
-      :type: str
-
-    .. attribute:: network
-
-      The network associated with the error. In particular, this is the
-      largest network where no address would be found. This is only
-      available for database lookups.
-
-      :type: ipaddress.IPv4Network or ipaddress.IPv6Network
-
-    """
+    """The address you were looking up was not found."""
 
     ip_address: Optional[str]
+    """The IP address used in the lookup. This is only available for database
+    lookups.
+    """
     _prefix_len: Optional[int]
 
     def __init__(
@@ -53,10 +34,16 @@ def __init__(
 
     @property
     def network(self) -> Optional[Union[ipaddress.IPv4Network, ipaddress.IPv6Network]]:
-        """The network for the error."""
+        """The network associated with the error.
+
+        In particular, this is the largest network where no address would be
+        found. This is only available for database lookups.
+        """
         if self.ip_address is None or self._prefix_len is None:
             return None
-        return ipaddress.ip_network(f"{self.ip_address}/{self._prefix_len}", False)
+        return ipaddress.ip_network(
+            f"{self.ip_address}/{self._prefix_len}", strict=False
+        )
 
 
 class AuthenticationError(GeoIP2Error):
@@ -69,12 +56,15 @@ class HTTPError(GeoIP2Error):
     This class represents an HTTP transport error. It extends
     :py:exc:`GeoIP2Error` and adds attributes of its own.
 
-    :ivar http_status: The HTTP status code returned
-    :ivar uri: The URI queried
-    :ivar decoded_content: The decoded response content
-
     """
 
+    http_status: Optional[int]
+    """The HTTP status code returned"""
+    uri: Optional[str]
+    """The URI queried"""
+    decoded_content: Optional[str]
+    """The decoded response content"""
+
     def __init__(
         self,
         message: str,