Improve types and fix C extension crashes

HISTORY.rst

@@ -3,6 +3,73 @@
 History
 -------
 
+3.3.0
+++++++++++++++++++
+
+* Fixed iteration over an IPv6 database with a network shorter than /96
+  whose first bits are zero, such as ``::/1``. The readers raised
+  ``ValueError`` or skipped networks.
+* The pure Python reader now raises ``InvalidDatabaseError`` for a search tree
+  record that points before the data section. Previously, it returned an
+  empty map.
+* Iterating over a database with a corrupt search tree, such as one with a
+  cycle, now raises ``InvalidDatabaseError``. Previously, the C extension
+  could corrupt memory, and the pure Python reader raised ``RecursionError``
+  or returned part of the networks.
+
+* C extension:
+
+  * Fixed segmentation faults from invalid use of ``Metadata``, ``Reader`` and
+    the internal iterator type.
+  * Fixed a segmentation fault on a database with a map key that is not a
+    string. Such a database now raises ``InvalidDatabaseError``.
+  * Fixed large ``uint32`` values, which came back negative on Windows.
+  * Fixed memory leaks and a use-after-free. Reinitializing a ``Reader`` or a
+    ``Metadata`` now raises ``ValueError``.
+  * Fixed a deadlock on free-threaded Python when a ``Reader`` was closed
+    during iteration, from another thread or from a signal handler.
+  * Fixed a crash on free-threaded Python when two threads advanced the same
+    iterator.
+  * An exhausted iterator now raises ``StopIteration`` after its ``Reader``
+    closes, not ``ValueError``.
+  * The iterator now stops after it raises an error, as the pure Python
+    iterator does.
+  * Added the ``node_byte_size`` and ``search_tree_size`` properties to
+    ``Metadata``, as the pure Python ``Metadata`` has.
+
+* Metadata:
+
+  * The pure Python reader ignores unknown keys, which a new minor version of
+    the format can add. It raises ``InvalidDatabaseError`` for a missing key, a
+    value of the wrong type, an invalid ``ip_version`` or format version, or a
+    ``build_epoch`` of 0.
+  * The C extension ignores unknown keys. Previously, ``Reader.metadata()``
+    crashed on them.
+
+* Added ``maxminddb.Mode``, which the README already described.
+* ``maxminddb.types.Record`` and ``Primitive`` are no longer generic type
+  aliases. Remove any subscript, such as ``Record[str]``. Pull request by Adam
+  Hitchcock. GitHub #464.
+
+* Type hints:
+
+  * ``Primitive`` includes ``bytearray``, which the C extension returns for
+    the ``bytes`` type.
+  * ``Reader.__iter__`` declares its item type.
+  * Added the ``StrOrBytesPath`` and ``DatabaseSource`` aliases to
+    ``maxminddb.types``.
+  * The ``maxminddb.extension.Reader`` stub accepts only a path, as the
+    extension does.
+  * ``MODE_FD`` accepts any object whose ``read()`` method returns ``bytes``,
+    such as a ``gzip.GzipFile``. ``maxminddb.types.SupportsRead`` describes
+    this type.
+
+* ``MODE_AUTO`` now accepts a binary file object. Previously, this could
+  raise ``TypeError``. It reads the file object into memory with the pure
+  Python reader, as ``MODE_FD`` does, so lookups are slower than with a path.
+* The pure Python reader raises ``TypeError`` when the database argument does
+  not suit the mode.
+
 3.2.0 (2026-09-10)
 ++++++++++++++++++
 

README.rst

@@ -39,21 +39,22 @@ provide `free GeoLite databases
 files must be decompressed with ``gunzip``.
 
 After you have obtained a database and imported the module, call
-``open_database`` with a path, or file descriptor (in the case of ``Mode.FD``),
+``open_database`` with a path, or binary file object (with ``Mode.FD`` or ``Mode.AUTO``),
 to the database as the first argument. Optionally, you may pass a mode as the
 second argument. The modes are available from ``maxminddb.Mode``. Valid modes 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`` - load database into memory from a file descriptor. Pure Python.
+* ``Mode.FD`` - load database into memory from a binary file object. Pure Python.
 * ``Mode.AUTO`` - try ``Mode.MMAP_EXT``, ``Mode.MMAP``, ``Mode.FILE`` in that
-  order. Default.
+  order. A file object is read into memory with the pure Python reader, as
+  with ``Mode.FD``. Pass a path to use the faster C extension. Default.
 
-**NOTE**: When using ``Mode.FD``, it is the *caller's* responsibility to be
-sure that the file descriptor gets closed properly. The caller may close the
-file descriptor immediately after the ``Reader`` object is created.
+**NOTE**: When using a file object, it is the *caller's* responsibility to be
+sure that the file object gets closed properly. The caller may close the
+file object immediately after the ``Reader`` object is created.
 
 The ``open_database`` function returns a ``Reader`` object. To look up an IP
 address, use the ``get`` method on this object. The method will return the

docs/index.rst

@@ -35,6 +35,14 @@ Database Reader
     :undoc-members:
     :show-inheritance:
 
+=====
+Types
+=====
+
+.. automodule:: maxminddb.types
+    :members:
+    :undoc-members:
+
 ==================
 Indices and tables
 ==================