[Pulp-dev] Django app naming discussion summary

[Sean Myers]

This morning we had an ad hoc discussion regarding the naming/namespacing
of our django apps in the Pulp platform and its plugins in Pulp 3. While
we were there we also talked a little bit about the pulp plugin API namespace,
and how we plan to "register" our plugin apps with Django.

I'll outline my recollection of the main points here, and elaborate below.
This is all from memory (I forgot to take notes...), so please correct anything
I've gotten wrong.

- All Django apps should be named <package>.app
  - Rename pulp.platform to pulp.app (pulp.platform is currently the platform
    django app)
  - Plugins should also follow this naming scheme
- Plugin API should be exposed under pulp.plugin(s). Anything importable
  from this namespace should be considered part of the versioned plugin API
- Use Django's Applications framework (linked below) to initialize plugins
  - Use python entry points to discover plugin Django apps and add them to
    INSTALLED_APPS
  - Don't use entry points for anything else
  - Do use Django's AppConfig to trigger any needed plugin initialization
    functionality

The details!


= All Django apps should be named <package>.app

Currently, no plugins have created Django apps for Pulp 3. The platform
Django app is 'pulp.platform' itself. For simplicity's sake, the consensus
was to call the Django apps "app". It's brief, and at least in the Django
context it makes it clear that this is what gets added to Django's
INSTALLED_APPS list to make the plugin known to Django.

Since pulp.platform currently is the platform Django app, the proposal is
to rename pulp.platform to pulp.app.

This work is tracked in https://pulp.plan.io/issues/2226, including details
about the open PRs we'd like to see closed before renaming pulp.platform.
Please update that issue as appropriate if I missed any 3.0-related pull
requests that might be affected by the pulp.platform rename.

The plugins have not yet been converted, but when Django apps are created
in the plugins, they should be similarly named. So, for example, rpm's
Django app will be pulp_rpm.app, docker will will be pulp_docker.app, etc.


= Plugin API should be exposed under pulp.plugin(s)

We touched on a few other topics, including namespacing the entire plugin
API under pulp.plugin, so that plugin writers would ideally only ever
"from pulp.plugin import what_they_need". pulp.plugin was used interchangeably
with pulp.plugins (I prefer the former but don't care). Explicitly
exposing this namespace as "the plugin API" (hopefully) makes it easier to
manage semantic versioning here. This would mean, for example, importing
base models that we want to expose to plugins into a module named like
"pulp.plugins.models". In this example, the plugins would therefore *not*
import any models from pulp.app.models.

This might be infeasible; Brian is taking it into account while working on
https://pulp.plan.io/issues/2181

= Use Django's Applications framework to initialize plugins

Finally, I mentioned my thoughts about how we would use Django's apps framework
as the basis for all plugin capability discovery. The gist is that "we'll use it
exactly how Django says to use it", as described in their docs:

https://docs.djangoproject.com/en/1.8/ref/applications/

Specifically applied to pulp, we're most likely going to use entry points to
make the installed plugins discoverable as Django apps and get them added to
Django's INSTALLED_APPS. From there, my current thinking is that we'll have
a specialized AppConfig subclass that plugins will use to uniformly register
their required and optional functionality with the Pulp platform. We get some
of this "for free", like models discovery, by virtue of using Django, so I'm
thinking that this specifically relates to things like making sure the API is
made aware of new views that it'll need to expose, tasks get loaded, or any
other initialization-time functionality we might want.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 851 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20160901/e65be0a7/attachment.sig>