[ckan-dev] The same functions defined in multiple places - do we need to refactor this?

[Sean Hammond]

I've been working on adding reference docs for things that CKAN exports for
plugins and themes to use to the CKAN docs. For example the plugins
toolkit, and the template helper functions. I'm adding docstrings to
these functions, and using autodoc to pull them into the docs.

One problem I've run into is that in many places in CKAN the same
function, class or exception is made available from multiple places.

For example url_for() is defined in ckan.lib.helpers so that templates
can access it with h.url_for(), but it's also imported directly into the
top-level namespace of ckan.plugins.toolkit so that plugins can do
toolkit.url_for().

The problem than comes when we want to give an example of how to use
this function in its docstring, or we want to cross-reference this
function from another docstring or somewhere else in the docs. Which
name do we use? ckan.lib.helpers.url_for? Or
ckan.plugins.toolkit.url_for? Template developers should use
helpers.url_for, while plugin developers should use toolkit.url_for, but
they're both reading the same docstring.

It seems like if there are some functions that need to be available to
both the templates and the plugins, these should be defined in some
module that's available to both, ckan/lib/util.py or something, rather
than importing the same function into two namespaces.

The problem is worse with exceptions. For example a bunch of logic
functions raise ckan.logic.ObjectNotFound. ObjectNotFound is also
imported into the plugins toolkit, as ckan.plugins.toolkit.NotFound (yes
with a different name even). Now if I want to add a docstring to a logic
function and document what exceptions it raises, what should the
docstring say it raises? ckan.logic.ObjectNotFound? Or
ckan.plugins.toolkit.NotFound?

If the docstring is for CKAN core developers, they should probably use
logic.ObjectNotFound. If the docstring is for plugin developers, they
should probably use toolkit.NotFound. But there's only one docstring.

Any suggestions for how to document this or how to refactor it?