Skip to content

Commit efd955f

Browse files
committed
Add back docs to type stub file
1 parent ccce395 commit efd955f

File tree

2 files changed

+49
-6
lines changed

2 files changed

+49
-6
lines changed

maxminddb/extension.pyi

Lines changed: 45 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
"""C extension database reader and related classes."""
2+
13
from ipaddress import IPv4Address, IPv6Address
24
from os import PathLike
35
from typing import IO, Any, AnyStr
@@ -7,24 +9,60 @@ from typing_extensions import Self
79
from maxminddb.types import Record
810

911
class Reader:
12+
"""A C extension implementation of a reader for the MaxMind DB format.
13+
14+
IP addresses can be looked up using the ``get`` method.
15+
"""
16+
1017
closed: bool = ...
1118

1219
def __init__(
1320
self,
1421
database: AnyStr | int | PathLike | IO,
1522
mode: int = ...,
16-
) -> None: ...
17-
def close(self) -> None: ...
18-
def get(self, ip_address: str | IPv6Address | IPv4Address) -> Record | None: ...
23+
) -> None:
24+
"""Reader for the MaxMind DB file format.
25+
26+
Arguments:
27+
database: A path to a valid MaxMind DB file such as a GeoIP2 database
28+
file, or a file descriptor in the case of MODE_FD.
29+
mode: mode to open the database with. The only supported modes are
30+
MODE_AUTO and MODE_MMAP_EXT.
31+
32+
"""
33+
34+
def close(self) -> None:
35+
"""Close the MaxMind DB file and returns the resources to the system."""
36+
37+
def get(self, ip_address: str | IPv6Address | IPv4Address) -> Record | None:
38+
"""Return the record for the ip_address in the MaxMind DB.
39+
40+
Arguments:
41+
ip_address: an IP address in the standard string notation
42+
43+
"""
44+
1945
def get_with_prefix_len(
2046
self,
2147
ip_address: str | IPv6Address | IPv4Address,
22-
) -> tuple[Record | None, int]: ...
23-
def metadata(self) -> Metadata: ...
48+
) -> tuple[Record | None, int]:
49+
"""Return a tuple with the record and the associated prefix length.
50+
51+
Arguments:
52+
ip_address: an IP address in the standard string notation
53+
54+
"""
55+
56+
def metadata(self) -> Metadata:
57+
"""Return the metadata associated with the MaxMind DB file."""
58+
2459
def __enter__(self) -> Self: ...
2560
def __exit__(self, *args) -> None: ... # noqa: ANN002
2661

62+
# pylint: disable=too-few-public-methods
2763
class Metadata:
64+
"""Metadata for the MaxMind DB reader."""
65+
2866
binary_format_major_version: int
2967
"""
3068
The major version number of the binary format used when creating the
@@ -74,4 +112,5 @@ class Metadata:
74112
The bit size of a record in the search tree.
75113
"""
76114

77-
def __init__(self, **kwargs: Any) -> None: ... # noqa: ANN401
115+
def __init__(self, **kwargs: Any) -> None: # noqa: ANN401
116+
"""Create new Metadata object. kwargs are key/value pairs from spec."""

pyproject.toml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,10 @@ ignore = [
8484

8585
[tool.ruff.lint.per-file-ignores]
8686
"docs/*" = ["ALL"]
87+
"maxminddb/extension.pyi" = [
88+
# This is a stub for extension and having the docs here is useful.
89+
"PYI021",
90+
]
8791
"setup.py" = ["ALL"]
8892
"tests/*" = ["ANN201", "D"]
8993

0 commit comments

Comments
 (0)