Document how database backends should monkey patch functions

[Josh Smeaton]

@dedsm at djangounderthehood brought up that the docs do not currently contain information for how 3rd party backends should be supporting expressions by monkey patching. Let's fix that.

Firebird backend (with connection.vendor == 'firebird') would change Sum like this:

from django.db.models import Sum

def backend_sum(self, compiler, connection)
    # do stuff

Sum.as_firebird = backend_sum

[Tim Graham]

It seems the "Technical Information" section of docs/ref/models/expression.txt is probably the place to add this.

[David De Sousa]

wouldn't it be better if the BaseExpression had a public api for this instead of relying on third parties monkey patching by design?

Something like:

from django.db.models import Sum

def backend_sum(self, compiler, connection):
    #do stuff

Sum.add_backend('firebird', backend_sum)

[Kristof Claes]

I have created a PR to update the docs: ​https://github.com/django/django/pull/5574

[Michael Manfre]

I've been discussing with jarshwah and apollo13 about ways of allowing backends to provide vendor specific overrides. They've convinced me that monkey patching is a good approach until/unless this becomes a more common problem.

kirstofclaes, the documentation looks good to me. Thanks!

[Carl Meyer]

I don't think the code in the doc patch is quite right yet.

Also, I'm inclined to agree with @dedsm above -- what's the harm in providing a public API that is effectively equivalent to doing this same monkey-patching "under the hood"( ;-) ). Seems like there'd be no harm, and it would give us more flexibility in the future if this does "become a more common problem."

[Michael Manfre]

Missed a mistake in the documentation example. Need to pass template to as_sql so that it is used.

[Kristof Claes]

I have changed template to self.template. If I understand the code correctly, this should work as well? Or is passing template to as_sql the preferred solution?

[Carl Meyer]

After discussion with jarshwah and manfre, we've agreed that none of us really care that much between simple monkeypatching vs a public API that does the monkeypatching internally. I don't think there's any practical benefit to the public API, even in terms of future flexibility: either way we're committed to the as_vendor method system, whether the method gets there via monkeypatching or otherwise is irrelevant. The only real benefit is that recommending monkeypatching in our documentation looks bad :-)

I think this doc patch should go ahead as-is. If I (or dedsm or anyone else) is motivated enough to submit a PR that adds the three-line public API (could also be a decorator) and modifies the docs accordingly, it would likely be accepted.

[Kristof Claes]

I have updated my PR again so it uses template again and passes it to as_sql.

I've been force pushing these changes. If I'm not using the correct workflow here, please let me know. This is my first contribution to OSS ever.

[Carl Meyer]

Force-pushing on every change is fine for a smaller patch like this. Patch looks good to me, thanks for the contribution, and congratulations, welcome to the team :-)

[Tim Graham]

Left some comments for improvement. Please uncheck "Patch needs improvement" when you update the pull request.

[Tim Graham]

​Updated PR

[Tim Graham <timograham@…>]

In 88034c99:

Fixed #25687 -- Documented how to add database function support to third-party backends.

Thanks Kristof Claes for the initial patch.

[Tim Graham <timograham@…>]

In 477b82cf:

[1.9.x] Fixed #25687 -- Documented how to add database function support to third-party backends.

Thanks Kristof Claes for the initial patch.

Backport of 88034c9938d92193d2104ecfe77999c69301dcc1 from master

[Tim Graham]

(leaving the documentation of how to patch expressions to #25759)