Skip to content

Commit 8380cdc

Browse files
horghhorgh
authored
Merge pull request #151 from maxmind/greg/pylint-updates
Improve extension type stubs
2 parents a4bdc84 + 6100e5d commit 8380cdc

File tree

3 files changed

+150
-84
lines changed

3 files changed

+150
-84
lines changed

‎HISTORY.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,12 @@
33
History
44
-------
55

6+
2.6.0
7+
++++++++++++++++++
8+
9+
* Added type annotations for instance variables on ``Metadata``
10+
* Updated type stubs for ``maxminddb.extension``.
11+
612
2.5.2 (2024-01-09)
713
++++++++++++++++++
814

‎maxminddb/extension.pyi‎

Lines changed: 101 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,116 @@
1+
"""
2+
maxminddb.extension
3+
~~~~~~~~~~~~~~~~
4+
5+
This module contains the C extension database reader and related classes.
6+
7+
"""
8+
19
from ipaddress import IPv4Address, IPv6Address
210
from os import PathLike
3-
from typing import Any, AnyStr, IO, Mapping, Optional, Sequence, Text, Tuple, Union
4-
11+
from typing import Any, AnyStr, Dict, IO, List, Optional, Tuple, Union
512
from maxminddb import MODE_AUTO
6-
from maxminddb.errors import InvalidDatabaseError as InvalidDatabaseError
713
from maxminddb.types import Record
814

915
class Reader:
16+
"""
17+
A C extension implementation of a reader for the MaxMind DB format. IP
18+
addresses can be looked up using the ``get`` method.
19+
"""
20+
1021
closed: bool = ...
22+
1123
def __init__(
1224
self, database: Union[AnyStr, int, PathLike, IO], mode: int = MODE_AUTO
13-
) -> None: ...
14-
def close(self) -> None: ...
15-
def get(
16-
self, ip_address: Union[str, IPv6Address, IPv4Address]
17-
) -> Optional[Record]: ...
25+
) -> None:
26+
"""Reader for the MaxMind DB file format
27+
28+
Arguments:
29+
database -- A path to a valid MaxMind DB file such as a GeoIP2 database
30+
file, or a file descriptor in the case of MODE_FD.
31+
mode -- mode to open the database with. The only supported modes are
32+
MODE_AUTO and MODE_MMAP_EXT.
33+
"""
34+
35+
def close(self) -> None:
36+
"""Closes the MaxMind DB file and returns the resources to the system"""
37+
38+
def get(self, ip_address: Union[str, IPv6Address, IPv4Address]) -> Optional[Record]:
39+
"""Return the record for the ip_address in the MaxMind DB
40+
41+
42+
Arguments:
43+
ip_address -- an IP address in the standard string notation
44+
"""
45+
1846
def get_with_prefix_len(
1947
self, ip_address: Union[str, IPv6Address, IPv4Address]
20-
) -> Tuple[Optional[Record], int]: ...
21-
def metadata(self) -> "Metadata": ...
48+
) -> Tuple[Optional[Record], int]:
49+
"""Return a tuple with the record and the associated prefix length
50+
51+
52+
Arguments:
53+
ip_address -- an IP address in the standard string notation
54+
"""
55+
56+
def metadata(self) -> "Metadata":
57+
"""Return the metadata associated with the MaxMind DB file"""
58+
2259
def __enter__(self) -> "Reader": ...
2360
def __exit__(self, *args) -> None: ...
2461

62+
# pylint: disable=too-few-public-methods
2563
class Metadata:
26-
@property
27-
def node_count(self) -> int: ...
28-
@property
29-
def record_size(self) -> int: ...
30-
@property
31-
def ip_version(self) -> int: ...
32-
@property
33-
def database_type(self) -> Text: ...
34-
@property
35-
def languages(self) -> Sequence[Text]: ...
36-
@property
37-
def binary_format_major_version(self) -> int: ...
38-
@property
39-
def binary_format_minor_version(self) -> int: ...
40-
@property
41-
def build_epoch(self) -> int: ...
42-
@property
43-
def description(self) -> Mapping[Text, Text]: ...
44-
def __init__(self, **kwargs: Any) -> None: ...
64+
"""Metadata for the MaxMind DB reader"""
65+
66+
binary_format_major_version: int
67+
"""
68+
The major version number of the binary format used when creating the
69+
database.
70+
"""
71+
72+
binary_format_minor_version: int
73+
"""
74+
The minor version number of the binary format used when creating the
75+
database.
76+
"""
77+
78+
build_epoch: int
79+
"""
80+
The Unix epoch for the build time of the database.
81+
"""
82+
83+
database_type: str
84+
"""
85+
A string identifying the database type, e.g., "GeoIP2-City".
86+
"""
87+
88+
description: Dict[str, str]
89+
"""
90+
A map from locales to text descriptions of the database.
91+
"""
92+
93+
ip_version: int
94+
"""
95+
The IP version of the data in a database. A value of "4" means the
96+
database only supports IPv4. A database with a value of "6" may support
97+
both IPv4 and IPv6 lookups.
98+
"""
99+
100+
languages: List[str]
101+
"""
102+
A list of locale codes supported by the databse.
103+
"""
104+
105+
node_count: int
106+
"""
107+
The number of nodes in the database.
108+
"""
109+
110+
record_size: int
111+
"""
112+
The bit size of a record in the search tree.
113+
"""
114+
115+
def __init__(self, **kwargs: Any) -> None:
116+
"""Creates new Metadata object. kwargs are key/value pairs from spec"""

‎maxminddb/reader.py‎

Lines changed: 43 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
import struct
1717
from ipaddress import IPv4Address, IPv6Address
1818
from os import PathLike
19-
from typing import Any, AnyStr, IO, Optional, Tuple, Union
19+
from typing import Any, AnyStr, Dict, IO, List, Optional, Tuple, Union
2020

2121
from maxminddb.const import MODE_AUTO, MODE_MMAP, MODE_FILE, MODE_MEMORY, MODE_FD
2222
from maxminddb.decoder import Decoder
@@ -29,7 +29,7 @@
2929

3030
class Reader:
3131
"""
32-
Instances of this class provide a reader for the MaxMind DB format. IP
32+
A pure Python implementation of a reader for the MaxMind DB format. IP
3333
addresses can be looked up using the ``get`` method.
3434
"""
3535

@@ -269,71 +269,59 @@ def __enter__(self) -> "Reader":
269269
return self
270270

271271

272+
# pylint: disable=too-many-instance-attributes,R0801
272273
class Metadata:
273-
"""Metadata for the MaxMind DB reader
274+
"""Metadata for the MaxMind DB reader"""
274275

276+
binary_format_major_version: int
277+
"""
278+
The major version number of the binary format used when creating the
279+
database.
280+
"""
275281

276-
.. attribute:: binary_format_major_version
277-
278-
The major version number of the binary format used when creating the
279-
database.
280-
281-
:type: int
282-
283-
.. attribute:: binary_format_minor_version
284-
285-
The minor version number of the binary format used when creating the
286-
database.
287-
288-
:type: int
289-
290-
.. attribute:: build_epoch
291-
292-
The Unix epoch for the build time of the database.
293-
294-
:type: int
295-
296-
.. attribute:: database_type
297-
298-
A string identifying the database type, e.g., "GeoIP2-City".
299-
300-
:type: str
301-
302-
.. attribute:: description
303-
304-
A map from locales to text descriptions of the database.
305-
306-
:type: dict(str, str)
307-
308-
.. attribute:: ip_version
309-
310-
The IP version of the data in a database. A value of "4" means the
311-
database only supports IPv4. A database with a value of "6" may support
312-
both IPv4 and IPv6 lookups.
313-
314-
:type: int
315-
316-
.. attribute:: languages
317-
318-
A list of locale codes supported by the databse.
319-
320-
:type: list(str)
282+
binary_format_minor_version: int
283+
"""
284+
The minor version number of the binary format used when creating the
285+
database.
286+
"""
321287

322-
.. attribute:: node_count
288+
build_epoch: int
289+
"""
290+
The Unix epoch for the build time of the database.
291+
"""
323292

324-
The number of nodes in the database.
293+
database_type: str
294+
"""
295+
A string identifying the database type, e.g., "GeoIP2-City".
296+
"""
325297

326-
:type: int
298+
description: Dict[str, str]
299+
"""
300+
A map from locales to text descriptions of the database.
301+
"""
327302

328-
.. attribute:: record_size
303+
ip_version: int
304+
"""
305+
The IP version of the data in a database. A value of "4" means the
306+
database only supports IPv4. A database with a value of "6" may support
307+
both IPv4 and IPv6 lookups.
308+
"""
329309

330-
The bit size of a record in the search tree.
310+
languages: List[str]
311+
"""
312+
A list of locale codes supported by the databse.
313+
"""
331314

332-
:type: int
315+
node_count: int
316+
"""
317+
The number of nodes in the database.
318+
"""
333319

320+
record_size: int
321+
"""
322+
The bit size of a record in the search tree.
334323
"""
335324

336-
# pylint: disable=too-many-instance-attributes
337325
def __init__(self, **kwargs) -> None:
338326
"""Creates new Metadata object. kwargs are key/value pairs from spec"""
339327
# Although I could just update __dict__, that is less obvious and it

0 commit comments

Comments
 (0)