PYTHON-5395 - Add convert_decimal to CodecOptions

[NoahStapp]

Context

We currently reject Python decimal.Decimal instances and require the user to manually convert to Decimal128.

This PR adds a new convert_decimal kwarg to CodecOptions that enables automatic conversion of decimal.Decimal to Decimal128 during BSON encoding.

Summary and example of changes

Current behavior and new behavior when convert_decimal=False (default)

>>> bson.encode({"d": decimal.Decimal('1.0')})
Traceback (most recent call last):
  File "<python-input-7>", line 1, in <module>
    encode({"d": decimal.Decimal('1.0')})
    ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/shane/git/mongo-python-driver/bson/__init__.py", line 1053, in encode
    return _dict_to_bson(document, check_keys, codec_options)
bson.errors.InvalidDocument: Invalid document {'d': Decimal('1.0')} | cannot encode object: Decimal('1.0'), of type: <class 'decimal.Decimal'>

New behavior when convert_decimal=True

>>> bson.encode({"d": decimal.Decimal('1.0')}, codec_options=CodecOptions(convert_decimal=True))
b'\x18\x00\x00\x00\x13d\x00\n\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00>0\x00'

Testing

test/test_bson.py has a new test TestCodecOptions.test_convert_decimal to verify correctness.

A changelog entry will be added in this PR if we determine that this is the correct approach to move ahead with.

[NoahStapp]

Will update the test/test_custom_types.py tests to reflect the change later today.

[sleepyStick]

Just a couple of minor comments

[aclark4life]

I stared at this for a while but then found: https://docs.python.org/3/c-api/arg.html. So, just confirming that's a format string for the args below.

[sleepyStick]

lol i was sitting on this one too, googled it, found that same site, was still confused / overwhelemed by words so then i asked mongo-gpt HAHA

[NoahStapp]

Yup this is a format string.

[aclark4life]

So after case 100 or so and if case 19 wasn't the case, auto-convert ?

[NoahStapp]

For consistency with how the rest of _write_element_to_buffer works, we check the converison edge cases such as this after the native BSON case statement.

[aclark4life]

LGTM!

[ShaneHarvey]

This PR doesn't add new functionality since users can already configure a CodecOptions that automatically encodes Decimal, for example:

class DecimalEncoder(TypeEncoder):
    @property
    def python_type(self):
        return Decimal

    def transform_python(self, value):
        return Decimal128(value)


DECIMAL_CODECOPTS = CodecOptions(type_registry=TypeRegistry([DecimalEncoder()]))

TypeRegistry can also be configured to auto-decode Decimal128 to decimal by implementing TypeDecoder.

Given this, is it necessary to add this convert_decimal flag?

[ShaneHarvey]

Suggest mentioning the convert_decimal option in this error message.

[NoahStapp]

This PR doesn't add new functionality since users can already configure a CodecOptions that automatically encodes Decimal, for example:

class DecimalEncoder(TypeEncoder):
    @property
    def python_type(self):
        return Decimal

    def transform_python(self, value):
        return Decimal128(value)


DECIMAL_CODECOPTS = CodecOptions(type_registry=TypeRegistry([DecimalEncoder()]))

TypeRegistry can also be configured to auto-decode Decimal128 to decimal by implementing TypeDecoder.

Given this, is it necessary to add this convert_decimal flag?

The convert_decimal flag is significantly less friction for users than configuring their own CodecOptions with an Encoder. Especially since practically every custom TypeEncoder to do so will be identical. If that's the case, we should do the conversion automatically ourselves.

I'm fine to make this auto-conversion the default instead of adding a flag, but then we would explicitly disallow users from making their own custom Encoders for decimal.Decimal.

[NoahStapp]

The Decimal128 specification explicitly does not allow this kind of auto-conversion. Closed.