From 03a04fb3f396b4ed3924655a979fbf1b01816b88 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Mon, 4 Mar 2024 08:46:58 -0800 Subject: [PATCH 1/2] Add type hints for Metadata --- HISTORY.rst | 5 +++ maxminddb/reader.py | 94 ++++++++++++++++++++------------------------- 2 files changed, 46 insertions(+), 53 deletions(-) diff --git a/HISTORY.rst b/HISTORY.rst index 876c60b..91d43c6 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -3,6 +3,11 @@ History ------- +2.6.0 +++++++++++++++++++ + +* Added type annotations for instance variables on ``Metadata`` + 2.5.2 (2024-01-09) ++++++++++++++++++ diff --git a/maxminddb/reader.py b/maxminddb/reader.py index ae197ba..642ef37 100644 --- a/maxminddb/reader.py +++ b/maxminddb/reader.py @@ -16,7 +16,7 @@ import struct from ipaddress import IPv4Address, IPv6Address from os import PathLike -from typing import Any, AnyStr, IO, Optional, Tuple, Union +from typing import Any, AnyStr, Dict, IO, List, Optional, Tuple, Union from maxminddb.const import MODE_AUTO, MODE_MMAP, MODE_FILE, MODE_MEMORY, MODE_FD from maxminddb.decoder import Decoder @@ -270,67 +270,55 @@ def __enter__(self) -> "Reader": class Metadata: - """Metadata for the MaxMind DB reader + """Metadata for the MaxMind DB reader""" + binary_format_major_version: int + """ + The major version number of the binary format used when creating the + database. + """ - .. attribute:: binary_format_major_version - - The major version number of the binary format used when creating the - database. - - :type: int - - .. attribute:: binary_format_minor_version - - The minor version number of the binary format used when creating the - database. - - :type: int - - .. attribute:: build_epoch - - The Unix epoch for the build time of the database. - - :type: int - - .. attribute:: database_type - - A string identifying the database type, e.g., "GeoIP2-City". - - :type: str - - .. attribute:: description - - A map from locales to text descriptions of the database. - - :type: dict(str, str) - - .. attribute:: ip_version - - 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. - - :type: int - - .. attribute:: languages - - A list of locale codes supported by the databse. - - :type: list(str) + binary_format_minor_version: int + """ + The minor version number of the binary format used when creating the + database. + """ - .. attribute:: node_count + build_epoch: int + """ + The Unix epoch for the build time of the database. + """ - The number of nodes in the database. + database_type: str + """ + A string identifying the database type, e.g., "GeoIP2-City". + """ - :type: int + description: Dict[str, str] + """ + A map from locales to text descriptions of the database. + """ - .. attribute:: record_size + 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. + """ - The bit size of a record in the search tree. + languages: List[str] + """ + A list of locale codes supported by the databse. + """ - :type: int + node_count: int + """ + The number of nodes in the database. + """ + record_size: int + """ + The bit size of a record in the search tree. """ # pylint: disable=too-many-instance-attributes From 6100e5d6876568338c4eabf314ad39edb24393e7 Mon Sep 17 00:00:00 2001 From: Gregory Oschwald Date: Mon, 4 Mar 2024 09:01:13 -0800 Subject: [PATCH 2/2] Update maxminddb.extension type stubs --- HISTORY.rst | 1 + maxminddb/extension.pyi | 130 +++++++++++++++++++++++++++++++--------- maxminddb/reader.py | 4 +- 3 files changed, 104 insertions(+), 31 deletions(-) diff --git a/HISTORY.rst b/HISTORY.rst index 91d43c6..5e44201 100644 --- a/HISTORY.rst +++ b/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) ++++++++++++++++++ diff --git a/maxminddb/extension.pyi b/maxminddb/extension.pyi index 1345fa7..56883d2 100644 --- a/maxminddb/extension.pyi +++ b/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""" diff --git a/maxminddb/reader.py b/maxminddb/reader.py index 642ef37..606aa28 100644 --- a/maxminddb/reader.py +++ b/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