Explaining application instances

[Daniele Procida]

There are a couple of places in the documentation that refer to "application instances":

<https://docs.djangoproject.com/en/dev/topics/http/urls/#introduction>
<https://docs.djangoproject.com/en/dev/ref/contrib/admin/#multiple-admin-sites-in-the-same-urlconf>

However, it's not really clear what an application instance is or why I might need to deploy multiple instances of one.

I think that's worth explaining in the documentation, especially since I have found a number of questions and discussions on the subject elsewhere.

I'd suggest that the explanation be incorporated in the URLs documentation.

Is the following largely correct:

* an application runs as an instance
* normally one doesn't need to worry about this
* sometimes though one might want to run an additional instance of an application
* one names the multiple instances through the "namespace" argument in a URL pattern
* URL reversing is the only reason we'd have for naming the multiple instances

I still don't quite see why one might want to run an additional instance of an application. If it's just to provide a different set of URLs for it, why not write some additional URLs to the views that the provide the different functionality?

Daniele

[Russell Keith-Magee]

Hi Danielle,

You're right - this is a bit of an ambiguous area, and it would certainly benefit from some clarification.

The only use cases for "application instance" behaviours is where you've got an app that is configurable in it's capabilities, and you want to deploy two different capability configurations in the same URL space. It's an unusual edge case of usage, but it is one that Django supports.

The best example I can give of an application instance would be using admin itself. Imagine a situation where you not only want to have access control on certain models of the admin, but you want to have different admin registrations. You have a Shopping Cart model with items in the cart; admin users can see all the details of the customer and what they've purchased, but sales representatives can only see a subset of fields on the cart. You could do this with two completely separate admin.site objects, with different ModelAdmin registrations, deployed at different URLs in your system.

However, this doesn't involve a duplication of tables -- there's still only 1 admin history table, which is used by both admin "instances".

Does that explanation help at all? 

Yours,

Russ Magee %-)

[Daniele Procida]

On Thu, Jul 11, 2013, Russell Keith-Magee <rus...@keith-magee.com> wrote:

>On Thu, Jul 11, 2013 at 3:57 PM, Daniele Procida <dan...@vurt.org> wrote:

>> I still don't quite see why one might want to run an additional instance
>> of an application. If it's just to provide a different set of URLs for it,
>> why not write some additional URLs to the views that the provide the
>> different functionality?

>The only use cases for "application instance" behaviours is where you've
>got an app that is configurable in it's capabilities, and you want to
>deploy two different capability configurations in the same URL space. It's
>an unusual edge case of usage, but it is one that Django supports.
>
>The best example I can give of an application instance would be using admin
>itself. Imagine a situation where you not only want to have access control
>on certain models of the admin, but you want to have different admin
>registrations. You have a Shopping Cart model with items in the cart; admin
>users can see all the details of the customer and what they've purchased,
>but sales representatives can only see a subset of fields on the cart. You
>could do this with two completely separate admin.site objects, with
>different ModelAdmin registrations, deployed at different URLs in your
>system.
>
>However, this doesn't involve a duplication of tables -- there's still only
>1 admin history table, which is used by both admin "instances".
>
>Does that explanation help at all?

Thanks, it does a bit! What about a non-admin example though? Would there be any case for that? Generally in an application if one needed to use the same tables and models but provide a different view upon them, one would simply create a view to do that, and the URL pattern to point to it.


Reading through the documentation some more, another matter arises.

Multiple application instances require namespacing. This could also be required when one wants to use - for example - {% url "archive" %} in templates, because you might have two different applications that both name patterns "archive".

Perhaps you wouldn't choose to do this yourself, but if you're using other developers' reusable applications, you might find yourself in such a situation. So these applications ought to have their URLs namespaced.

<https://docs.djangoproject.com/en/dev/topics/http/urls/#url-namespaces> doesn't actually give this as a reason for namespacing URLs (it only gives multiple application instances as a case), though <https://docs.djangoproject.com/en/dev/intro/tutorial03/#namespacing-url-names> does.

So perhaps the resuable application case should be mentioned in <https://docs.djangoproject.com/en/dev/topics/http/urls/#url-namespaces> too.


There's still a difficulty though. We can namespace URL patterns by using include() (I think this is the only way).

This means that the namespacing becomes the responsibility of the including URLconf, likely the root project URLconf, whereas I might have created an application that I want to distribute, that has a pattern named "archive" and some templates or template snippets that make use of {% url "archive" %}.

This will constrain anyone who uses my application and needs to namespace it to override all these templates, which could be tedious.

This isn't really a documentation issue, but perhaps the documentation could help address it by suggesting that authors use URL pattern name forms that aren't likely to be found in other applications.

I have created a ticket for this.

<https://code.djangoproject.com/ticket/20734>

Daniele