Improve docs

Author: oschwald

examples/benchmark.py

@@ -1,4 +1,5 @@
 #!/usr/bin/python
+"""Basic benchmark for maxminddb."""
 
 import argparse
 import random
@@ -20,6 +21,7 @@
 
 
 def lookup_ip_address() -> None:
+    """Look up the IP."""
     ip = socket.inet_ntoa(struct.pack("!L", random.getrandbits(32)))
     reader.get(str(ip))
 
@@ -29,4 +31,3 @@ def lookup_ip_address() -> None:
     setup="from __main__ import lookup_ip_address",
     number=args.count,
 )
-

maxminddb/__init__.py

@@ -42,16 +42,16 @@ def open_database(
     """Open a MaxMind DB database.
 
     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. Valid mode are:
-            * MODE_MMAP_EXT - use the C extension with memory map.
-            * MODE_MMAP - read from memory map. Pure Python.
-            * MODE_FILE - read database as standard file. Pure Python.
-            * MODE_MEMORY - load database into memory. Pure Python.
-            * MODE_FD - the param passed via database is a file descriptor, not
-                        a path. This mode implies MODE_MEMORY.
-            * MODE_AUTO - tries MODE_MMAP_EXT, MODE_MMAP, MODE_FILE in that
+        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. Valid mode are:
+              * MODE_MMAP_EXT - use the C extension with memory map.
+              * MODE_MMAP - read from memory map. Pure Python.
+              * MODE_FILE - read database as standard file. Pure Python.
+              * MODE_MEMORY - load database into memory. Pure Python.
+              * MODE_FD - the param passed via database is a file descriptor, not
+                          a path. This mode implies MODE_MEMORY.
+              * MODE_AUTO - tries MODE_MMAP_EXT, MODE_MMAP, MODE_FILE in that
                           order. Default mode.
 
     """

maxminddb/decoder.py

@@ -25,12 +25,12 @@ def __init__(
         pointer_base: int = 0,
         pointer_test: bool = False,
     ) -> None:
-        """Created a Decoder for a MaxMind DB.
+        """Create a Decoder for a MaxMind DB.
 
         Arguments:
-        database_buffer -- an mmap'd MaxMind DB file.
-        pointer_base -- the base number to use when decoding a pointer
-        pointer_test -- used for internal unit testing of pointer code
+            database_buffer: an mmap'd MaxMind DB file.
+            pointer_base: the base number to use when decoding a pointer
+            pointer_test: used for internal unit testing of pointer code
 
         """
         self._pointer_test = pointer_test
@@ -136,7 +136,7 @@ def decode(self, offset: int) -> tuple[Record, int]:
         """Decode a section of the data section starting at offset.
 
         Arguments:
-        offset -- the location of the data structure to decode
+            offset: the location of the data structure to decode
 
         """
         new_offset = offset + 1

maxminddb/extension.pyi

@@ -79,7 +79,7 @@ class Metadata:
 
     languages: list[str]
     """
-    A list of locale codes supported by the databse.
+    A list of locale codes supported by the database.
     """
 
     node_count: int

maxminddb/file.py

@@ -16,6 +16,7 @@ class FileBuffer:
     """A slice-able file reader."""
 
     def __init__(self, database: str) -> None:
+        """Create FileBuffer."""
         # pylint: disable=consider-using-with
         self._handle = open(database, "rb")
         self._size = os.fstat(self._handle.fileno()).st_size

maxminddb/reader.py

@@ -23,8 +23,9 @@
 
 
 class Reader:
-    """A pure Python implementation of a reader for the MaxMind DB format. IP
-    addresses can be looked up using the ``get`` method.
+    """A pure Python implementation of a reader for the MaxMind DB format.
+
+    IP addresses can be looked up using the ``get`` method.
     """
 
     _DATA_SECTION_SEPARATOR_SIZE = 16
@@ -45,15 +46,15 @@ def __init__(
         """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. Valid mode are:
-            * MODE_MMAP - read from memory map.
-            * MODE_FILE - read database as standard file.
-            * MODE_MEMORY - load database into memory.
-            * MODE_AUTO - tries MODE_MMAP and then MODE_FILE. Default.
-            * MODE_FD - the param passed via database is a file descriptor, not
-                        a path. This mode implies MODE_MEMORY.
+            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. Valid mode are:
+                  * MODE_MMAP - read from memory map.
+                  * MODE_FILE - read database as standard file.
+                  * MODE_MEMORY - load database into memory.
+                  * MODE_AUTO - tries MODE_MMAP and then MODE_FILE. Default.
+                  * MODE_FD - the param passed via database is a file descriptor, not
+                              a path. This mode implies MODE_MEMORY.
 
         """
         filename: Any
@@ -140,7 +141,7 @@ def get(self, ip_address: Union[str, IPv6Address, IPv4Address]) -> Optional[Reco
         """Return the record for the ip_address in the MaxMind DB.
 
         Arguments:
-        ip_address -- an IP address in the standard string notation
+            ip_address: an IP address in the standard string notation
 
         """
         (record, _) = self.get_with_prefix_len(ip_address)
@@ -153,7 +154,7 @@ def get_with_prefix_len(
         """Return a tuple with the record and the associated prefix length.
 
         Arguments:
-        ip_address -- an IP address in the standard string notation
+            ip_address: an IP address in the standard string notation
 
         """
         if isinstance(ip_address, str):
@@ -326,7 +327,7 @@ class Metadata:
 
     languages: list[str]
     """
-    A list of locale codes supported by the databse.
+    A list of locale codes supported by the database.
     """
 
     node_count: int
@@ -340,7 +341,7 @@ class Metadata:
     """
 
     def __init__(self, **kwargs) -> None:
-        """Creates new Metadata object. kwargs are key/value pairs from spec."""
+        """Create new Metadata object. kwargs are key/value pairs from spec."""
         # Although I could just update __dict__, that is less obvious and it
         # doesn't work well with static analysis tools and some IDEs
         self.node_count = kwargs["node_count"]