PYTHON-5355 Addition of API to move to and from NumPy ndarrays and BSON BinaryVectors

[caseyclements]

Issue Key

Summary

The existing API for bson.binary.BinaryVector requires that the vector of numbers be a list of either floats or integers. This extends that to allow one to use NumPy Arrays, which are the most common form of vectors used in Python.

Changes in this PR

1. We extend the types of the data member of the bson.binary.BinaryVector to include np.ndarray:

class BinaryVector:
    """Vector of numbers along with metadata for binary interoperability.
    .. versionadded:: 4.10
    """

    __slots__ = ("data", "dtype", "padding")

    def __init__(
        self,
        data: Union[Sequence[float | int], np.ndarray],
        dtype: BinaryVectorDtype,
        padding: int = 0,
    ):

2. Binary.from_vector now accepts this input, and uses NumPy's tobytes() instead of struct.pack as is required for lists.

3. A new instance method, as_numpy_vector was added. This was chosen so that we maintain backwards-compatibility. There was also concern about needlessly introducing Numpy as a dependency.

Testing Plan

New tests are found in test/test_bson.py. These are run via just test-numpy locally and with new Evergreen variants that test on different architectures.

Checklist

Checklist for Author

• Did you update the changelog (if necessary)?
• Is the intention of the code captured in relevant tests?
• If there are new TODOs, has a related JIRA ticket been created?

Checklist for Reviewer @ShaneHarvey @blink1073 @Jibola

• Does the title of the PR reference a JIRA Ticket?
• Do you fully understand the implementation? (Would you be comfortable explaining how this code works to someone else?)
• Have you checked for spelling & grammar errors?
• Is all relevant documentation (README or docstring) updated?

Focus Areas for Reviewer (optional)

[ShaneHarvey]

IIRC importing numpy is very very slow. In that case we should not even attempt to import it by default.

[caseyclements]

I've changed to lazy imports, and used importlib.util.find_spec("numpy") as skip condition in test_bson.py.

[ShaneHarvey]

Should this be a new method or a new argument to the existing as_vector method? Like binary.as_vector(numpy=True)

[caseyclements]

I'm open to this as alternative to additional function as_numpy_vector. What do you think, @blink1073 ?

[blink1073]

I like Shane's suggestion, for symmetry with from_vector.

[ShaneHarvey]

Instead of adding a new extra we could use --with numpy.

[caseyclements]

This was a great suggestion. I had to change invocations from uv run mypy . (or pytest) to be done ad modules uv run python -m mypy . but it works. I removed the extra from pyproject and requirements/.

[ShaneHarvey]

Are we following the rules of the spec for validating PACKED_BIT here (eg the validation in as_vector)?

[caseyclements]

I just added the same validations applied in as_vector.

[blink1073]

I think this is confusing, there might be other place's we'd use numpy optionally, perhaps test-numpy?

[caseyclements]

"test-numpy" works for me. @ShaneHarvey ?

[caseyclements]

@blink1073 Happy to make this change now. All tests are passing.

[blink1073]

I say go for it

[Jibola]

Few questions for clarification, but otherwise looks good.

[Jibola]

NIT because we don't have a general policy around this, but there's three separate test themes in here.

Happy path
Invalid input
Value coercion

I'd push we split those three into three separate unit tests for better semantic representation, but I'm not hard-pressed on this.

[caseyclements]

This looks good to go now @Jibola. Failing tests are unrelated. I ran the link check locally and it succeeded. The run was rate-limited. The evergreen time out was spurious I think.