This adds a minimal decimal capsule API.  As can be seen from the patch,
adding anything to decimal while doing it properly is quite labor and
testing intensive, so the intent is to *keep* the API minimal!

That said, some functions are really necessary:

  1) PyDec_TypeCheck()         -- for obvious reasons.

  2) PyDec_Alloc()             -- create new decimals.

  3) PyDec_Get()               -- get the mpd_t, enables the use of all libmpdec functions.

  4) PyDec_AsUint128Triple()   -- export the decimal as (sign, hi, lo, exp).

  5) PyDec_FromUint128Triple() -- create a decimal from (sign, hi, lo, exp).


4) and 5) have been requested by Antoine for a real world use case.  (hi, lo)
is the coefficient as a __uint128_t split in two uint64_t.


Antoine, could you verify that this is sufficient for the database use case?

Also as a note for Mark and Raymond: This API is for exact conversions
and avoids the use of the context except for raising ConversionSyntax.

I'll add documentation once Antoine has tried it out for his use case.

Adding Daniele Varrazzo, in case this is useful for the PostgreSQL
adapter.

I probably won't try it out explicitly (it's basically cumbersome for us to test with non-release Pythons, because of our dependencies to Numpy and Cython), but reviewing the API should be enough anyway.

It looks like the API would be usable, so the PR now has documentation.

I'm happy with the API, except that --with-system-libmpdec is naturally
broken.  So I've to release a new libmpdec, which I'd rather do soon
because I don't want to revisit this later.

Antoine has looked at the API.  If anyone else has requests or objections,
now would be a good time to raise concerns.  These two functions are
the centerpiece of the PR:

   mpd_uint128_triple_t PyDec_AsUint128Triple(const PyObject *dec)
   PyObject *PyDec_FromUint128Triple(const mpd_uint128_triple_t *triple)

New changeset 39042e00ab01d6521548c1b7cc6554c09f4389ff by Stefan Krah in branch 'master':
bpo-41324 Add a minimal decimal capsule API (#21519)
https://github.com/python/cpython/commit/39042e00ab01d6521548c1b7cc6554c09f4389ff

Was expanding the C-API discussed on the mailing list or in any wider forum? It seems vstinner is working hard to reduce the public API exposure while this issue + PR makes it even larger. Please reconsider putting this in for 3.10.

@mattip, see issue43422

For the record, this is going to be reverted at Stefan's request in issue43422.

FYI, will try to use this API in psycopg3, which supports the PostgreSQL decimal binary format. Thank you very much: it seems exactly what needed.

Binary conversion with Python Decimal currently has disappointing performances and is slower than the text format conversion. This is likely caused by the use of Decimal.as_tuple(), which creates tuples for the return value and the digits and requires Python calls to access their values.

I have considered using libmpdec directly: personally I wouldn't be opposed to that, but the additional dependency on libmpdec-dev would earn the project no new fan :\

Ref. https://github.com/psycopg/psycopg3/issues/54

Ah, just noticed that this has been now reverted. Oh well, I'll see what to do then :(