From 67c7ad26432d2cdd18d08426252e026db934c86a Mon Sep 17 00:00:00 2001 From: Casey Clements Date: Thu, 24 Oct 2024 14:13:57 -0400 Subject: [PATCH 1/4] Fixed typing.overload --- bson/binary.py | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/bson/binary.py b/bson/binary.py index f03173a8ef..0496261cc7 100644 --- a/bson/binary.py +++ b/bson/binary.py @@ -16,7 +16,7 @@ import struct from dataclasses import dataclass from enum import Enum -from typing import TYPE_CHECKING, Any, Optional, Sequence, Tuple, Type, Union +from typing import TYPE_CHECKING, Any, Optional, Sequence, Tuple, Type, Union, overload from uuid import UUID """Tools for representing BSON binary data. @@ -397,6 +397,18 @@ def as_uuid(self, uuid_representation: int = UuidRepresentation.STANDARD) -> UUI f"cannot decode subtype {self.subtype} to {UUID_REPRESENTATION_NAMES[uuid_representation]}" ) + @classmethod + @overload + def from_vector(cls: Type[Binary], vector: BinaryVector) -> Binary: + ... + + @classmethod + @overload + def from_vector( + cls: Type[Binary], vector: list[int, float], dtype: BinaryVectorDtype, padding: int = 0 + ) -> Binary: + ... + @classmethod def from_vector( cls: Type[Binary], From ec6fed483a48d640f0c7fda6bb9bab559789e1a1 Mon Sep 17 00:00:00 2001 From: Casey Clements Date: Mon, 4 Nov 2024 16:47:14 -0500 Subject: [PATCH 2/4] test that from_vector(BinaryVector(), dtype=...) raises an error --- test/test_bson.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/test/test_bson.py b/test/test_bson.py index 5dc1377bcd..ba2726fd87 100644 --- a/test/test_bson.py +++ b/test/test_bson.py @@ -802,6 +802,13 @@ def test_vector(self): assert float_binary == Binary.from_vector( BinaryVector(list_vector, BinaryVectorDtype.FLOAT32) ) + # Confirm kwargs cannot be passed when BinaryVector is provided + self.assertRaises( + ValueError, + Binary.from_vector, + BinaryVector(list_vector, BinaryVectorDtype.PACKED_BIT, padding), + {"dtype": BinaryVectorDtype.PACKED_BIT}, + ) def test_unicode_regex(self): """Tests we do not get a segfault for C extension on unicode RegExs. From c971d846979846d44a4fdbbeed69c9153735b1be Mon Sep 17 00:00:00 2001 From: Casey Clements Date: Mon, 4 Nov 2024 16:54:36 -0500 Subject: [PATCH 3/4] Removed BETA advertisements on vector apis in binary.py --- bson/binary.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/bson/binary.py b/bson/binary.py index 0496261cc7..6dc5058c2c 100644 --- a/bson/binary.py +++ b/bson/binary.py @@ -195,7 +195,7 @@ class UuidRepresentation: VECTOR_SUBTYPE = 9 -"""**(BETA)** BSON binary subtype for densely packed vector data. +"""BSON binary subtype for densely packed vector data. .. versionadded:: 4.10 """ @@ -207,7 +207,7 @@ class UuidRepresentation: class BinaryVectorDtype(Enum): - """**(BETA)** Datatypes of vector subtype. + """Datatypes of vector subtype. :param FLOAT32: (0x27) Pack list of :class:`float` as float32 :param INT8: (0x03) Pack list of :class:`int` in [-128, 127] as signed int8 @@ -229,7 +229,7 @@ class BinaryVectorDtype(Enum): @dataclass class BinaryVector: - """**(BETA)** Vector of numbers along with metadata for binary interoperability. + """Vector of numbers along with metadata for binary interoperability. .. versionadded:: 4.10 """ @@ -256,7 +256,7 @@ class Binary(bytes): the difference between what should be considered binary data and what should be considered a string when we encode to BSON. - **(BETA)** Subtype 9 provides a space-efficient representation of 1-dimensional vector data. + Subtype 9 provides a space-efficient representation of 1-dimensional vector data. Its data is prepended with two bytes of metadata. The first (dtype) describes its data type, such as float32 or int8. The second (padding) prescribes the number of bits to ignore in the final byte. @@ -278,7 +278,7 @@ class Binary(bytes): Support any bytes-like type that implements the buffer protocol. .. versionchanged:: 4.10 - **(BETA)** Addition of vector subtype. + Addition of vector subtype. """ _type_marker = 5 @@ -416,7 +416,7 @@ def from_vector( dtype: Optional[BinaryVectorDtype] = None, padding: Optional[int] = None, ) -> Binary: - """**(BETA)** Create a BSON :class:`~bson.binary.Binary` of Vector subtype. + """Create a BSON :class:`~bson.binary.Binary` of Vector subtype. To interpret the representation of the numbers, a data type must be included. See :class:`~bson.binary.BinaryVectorDtype` for available types and descriptions. @@ -459,7 +459,7 @@ def from_vector( return cls(metadata + data, subtype=VECTOR_SUBTYPE) def as_vector(self) -> BinaryVector: - """**(BETA)** From the Binary, create a list of numbers, along with dtype and padding. + """From the Binary, create a list of numbers, along with dtype and padding. :return: BinaryVector From ab265aee4579363adf408a9c51ee0a481055081b Mon Sep 17 00:00:00 2001 From: Casey Clements Date: Mon, 4 Nov 2024 19:14:39 -0500 Subject: [PATCH 4/4] Put test in a with clause to draw attention that mypy would catch the incorrect signature with [call-overload] --- test/test_bson.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/test/test_bson.py b/test/test_bson.py index ba2726fd87..b431f700dc 100644 --- a/test/test_bson.py +++ b/test/test_bson.py @@ -803,12 +803,11 @@ def test_vector(self): BinaryVector(list_vector, BinaryVectorDtype.FLOAT32) ) # Confirm kwargs cannot be passed when BinaryVector is provided - self.assertRaises( - ValueError, - Binary.from_vector, - BinaryVector(list_vector, BinaryVectorDtype.PACKED_BIT, padding), - {"dtype": BinaryVectorDtype.PACKED_BIT}, - ) + with self.assertRaises(ValueError): + Binary.from_vector( + BinaryVector(list_vector, BinaryVectorDtype.PACKED_BIT, padding), + dtype=BinaryVectorDtype.PACKED_BIT, + ) # type: ignore[call-overload] def test_unicode_regex(self): """Tests we do not get a segfault for C extension on unicode RegExs.