Update maxminddb.extension type stubs

HISTORY.rst

@@ -7,6 +7,7 @@ History
 ++++++++++++++++++
 
 * Added type annotations for instance variables on ``Metadata``
+* Updated type stubs for ``maxminddb.extension``.
 
 2.5.2 (2024-01-09)
 ++++++++++++++++++

maxminddb/extension.pyi

@@ -1,44 +1,116 @@
+"""
+maxminddb.extension
+~~~~~~~~~~~~~~~~
+
+This module contains the C extension database reader and related classes.
+
+"""
+
 from ipaddress import IPv4Address, IPv6Address
 from os import PathLike
-from typing import Any, AnyStr, IO, Mapping, Optional, Sequence, Text, Tuple, Union
-
+from typing import Any, AnyStr, Dict, IO, List, Optional, Tuple, Union
 from maxminddb import MODE_AUTO
-from maxminddb.errors import InvalidDatabaseError as InvalidDatabaseError
 from maxminddb.types import Record
 
 class Reader:
+    """
+    A C extension implementation of a reader for the MaxMind DB format. IP
+    addresses can be looked up using the ``get`` method.
+    """
+
     closed: bool = ...
+
     def __init__(
         self, database: Union[AnyStr, int, PathLike, IO], mode: int = MODE_AUTO
-    ) -> None: ...
-    def close(self) -> None: ...
-    def get(
-        self, ip_address: Union[str, IPv6Address, IPv4Address]
-    ) -> Optional[Record]: ...
+    ) -> None:
+        """Reader for the MaxMind DB file format
+
+        Arguments:
+        database -- A path to a valid MaxMind DB file such as a GeoIP2 database
+                    file, or a file descriptor in the case of MODE_FD.
+        mode -- mode to open the database with. The only supported modes are
+                MODE_AUTO and MODE_MMAP_EXT.
+        """
+
+    def close(self) -> None:
+        """Closes the MaxMind DB file and returns the resources to the system"""
+
+    def get(self, ip_address: Union[str, IPv6Address, IPv4Address]) -> Optional[Record]:
+        """Return the record for the ip_address in the MaxMind DB
+
+
+        Arguments:
+        ip_address -- an IP address in the standard string notation
+        """
+
     def get_with_prefix_len(
         self, ip_address: Union[str, IPv6Address, IPv4Address]
-    ) -> Tuple[Optional[Record], int]: ...
-    def metadata(self) -> "Metadata": ...
+    ) -> Tuple[Optional[Record], int]:
+        """Return a tuple with the record and the associated prefix length
+
+
+        Arguments:
+        ip_address -- an IP address in the standard string notation
+        """
+
+    def metadata(self) -> "Metadata":
+        """Return the metadata associated with the MaxMind DB file"""
+
     def __enter__(self) -> "Reader": ...
     def __exit__(self, *args) -> None: ...
 
+# pylint: disable=too-few-public-methods
 class Metadata:
-    @property
-    def node_count(self) -> int: ...
-    @property
-    def record_size(self) -> int: ...
-    @property
-    def ip_version(self) -> int: ...
-    @property
-    def database_type(self) -> Text: ...
-    @property
-    def languages(self) -> Sequence[Text]: ...
-    @property
-    def binary_format_major_version(self) -> int: ...
-    @property
-    def binary_format_minor_version(self) -> int: ...
-    @property
-    def build_epoch(self) -> int: ...
-    @property
-    def description(self) -> Mapping[Text, Text]: ...
-    def __init__(self, **kwargs: Any) -> None: ...
+    """Metadata for the MaxMind DB reader"""
+
+    binary_format_major_version: int
+    """
+    The major version number of the binary format used when creating the
+    database.
+    """
+
+    binary_format_minor_version: int
+    """
+    The minor version number of the binary format used when creating the
+    database.
+    """
+
+    build_epoch: int
+    """
+    The Unix epoch for the build time of the database.
+    """
+
+    database_type: str
+    """
+    A string identifying the database type, e.g., "GeoIP2-City".
+    """
+
+    description: Dict[str, str]
+    """
+    A map from locales to text descriptions of the database.
+    """
+
+    ip_version: int
+    """
+    The IP version of the data in a database. A value of "4" means the
+    database only supports IPv4. A database with a value of "6" may support
+    both IPv4 and IPv6 lookups.
+    """
+
+    languages: List[str]
+    """
+    A list of locale codes supported by the databse.
+    """
+
+    node_count: int
+    """
+    The number of nodes in the database.
+    """
+
+    record_size: int
+    """
+    The bit size of a record in the search tree.
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Creates new Metadata object. kwargs are key/value pairs from spec"""

maxminddb/reader.py

@@ -29,7 +29,7 @@
 
 class Reader:
     """
-    Instances of this class provide a reader for the MaxMind DB format. IP
+    A pure Python implementation of a reader for the MaxMind DB format. IP
     addresses can be looked up using the ``get`` method.
     """
 
@@ -269,6 +269,7 @@ def __enter__(self) -> "Reader":
         return self
 
 
+# pylint: disable=too-many-instance-attributes,R0801
 class Metadata:
     """Metadata for the MaxMind DB reader"""
 
@@ -321,7 +322,6 @@ class Metadata:
     The bit size of a record in the search tree.
     """
 
-    # pylint: disable=too-many-instance-attributes
     def __init__(self, **kwargs) -> None:
         """Creates new Metadata object. kwargs are key/value pairs from spec"""
         # Although I could just update __dict__, that is less obvious and it