For Django 2.0 you MUST provide `app_name` when using `namespace`.Closesencode#5659Correct namespace referenceUpdated example without changing old text.

carltongibson force-pushed the38/router-include-docs branch fromb5be07f to3ba3f45Compare

February 20, 2018 20:08

lovelydinosaur reviewed

Feb 22, 2018

View reviewed changes

docs/api-guide/routers.md Outdated

		Router URL patterns can also be included using_application_ and_instance_ namespaces.

		To use an_application namespace_ pass a 2-tuple containing the`router.urls` and the app name.
		To use an_instance namespace_ pass the optional`namespace` parameter.

Copy link

Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Can we reference anywhere in the Django docs here? I wouldn't know the difference between the two off the top of my head.

I guess ideally we'd just say "Do X", and have "If you need to do Y then ..." slightly later in the docs, rather than presenting the developer with a choice that they need to make here.

Copy link

CollaboratorAuthor

carltongibsonFeb 22, 2018•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

The[URL namespaces docs] reference below is the canonical source. It's basically the only place it's ever discussed.

The other place we could link to is theinclude referencehttps://docs.djangoproject.com/en/2.0/ref/urls/#include

The way I thought about phrasing this is:

Try toinclude via an app-levelurls module, setting theapp_name variable there. Basically never use thenamespace parameter, you basically don't want it.
If you MUSTinclude the router urls directly (and need namespaces) then provide(router.urls, app_name) — that's what you want. (If you really neednamespace then go-ahead, but you still have to pass the 2-tuple first.)

But by the time I'd drafted than I basically need to rewrite the Django docs (linked) so people should really read those.

Copy link

CollaboratorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

The >80% case is to just pass the 2-tuple and ignore thenamespace parameter. Let me re-phrase around that...

Adjust phrasing.

e88d46a

carltongibson commented

Feb 22, 2018

View reviewed changes

Copy link

CollaboratorAuthor

carltongibson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Hey@tomchristie.

I adjusted the phrasing. Have a look.

(It's tricky because the whole application vs instance thing isn't clearly represented by the API...)

docs/api-guide/routers.md Outdated

		urlpatterns = [
		url(r'^forgot-password/$', ForgotPasswordFormView.as_view()),
		url(r'^api/', include(router.urls,namespace='api')),
		url(r'^api/', include((router.urls,'app_name')),

Copy link

CollaboratorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

This is the >80% usage for namespaces. (We want to namespace our URL names to a single application.)

Copy link

Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Theinclude(( ...) looks wrong to me?

Copy link

Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I'm confused by theapp_name argument, does ithave to match the app name, or is it a general purpose namespace?

Copy link

CollaboratorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

The parenthesis is missing. I'll fix that.

SO... 😃

What ultimately gets passed included is a 3-tuple:

(A_LIST_OF_PATTERNS, AN_APPLICATION_NAMESPACE, AN_INSTANCE_NAMESPACE)

In the example here we pass the first two of those, as a 2-tuple.

When you include a module the list of patterns comes fromurlpatterns, and the application namespace comes fromapp_name.

I've just usedapp_name here as any old string. It's usually,'admin', or'polls' or'rest_framework'.

In this example the instance namespace ends up being the same as the application namespace, because we didn't provide one. (This means that it'll beNone if the application namespace is, which is just the global namespace we all start out with.)

But we could do provide, say,namespace='v1' and such.

Grrr. I'm still not happy here.

docs/api-guide/routers.md Outdated

		If using namespacing with hyperlinked serializers you'll also need to ensure that any`view_name` parameters on the serializers correctly reflect the namespace. In the example above you'd need to include a parameter such as`view_name='api:user-detail'` for serializer fields hyperlinked to the user detail view.
		(`include` also allows an optional`namespace` parameter to also create an_instance namespace_.
		This defaults to`None` and will be set to`app_name` if not provided.
		See Django's[URL namespaces docs][url-namespace-docs] for more details.)

Copy link

CollaboratorAuthor

carltongibsonFeb 22, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Do we even need to say this? Not sure...

Copy link

Contributor

lovelydinosaurFeb 22, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Looks better!

Copy link

CollaboratorAuthor

carltongibsonFeb 22, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

and will be set toapp_name ...

Grrrr."...the same as the application namespace..." or such.

Don't merge this yet. I'll have a go over the weekend.

carltongibson added2 commits

February 22, 2018 16:23

Add missing parenthesis

51884ab

Adjust wording

a0528fd

carltongibson commented

Feb 22, 2018

View reviewed changes

docs/api-guide/routers.md Outdated


		Router URL patterns can also be namespaces.
		To include the router URL patterns with an application namespace pass a
		`(router.urls, 'app_name')` 2-tuple to`include`.

Copy link

CollaboratorAuthor

carltongibsonFeb 22, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I added the'' aroundapp_name here. Hopefully that works.

The option is something like(PATTERN_LIST, APP_NAME)

carltongibson commented

Feb 22, 2018

View reviewed changes

docs/api-guide/routers.md Outdated


		If using namespacing with hyperlinked serializers you'll also need to ensure that any`view_name` parameters on the serializers correctly reflect the namespace. In the example above you'd need to include a parameter such as`view_name='api:user-detail'` for serializer fields hyperlinked to the user detail view.
		(You may additionally pass an optional`namespace` parameter to`include` to also
		create an_instance namespace_. See Django's[URL namespaces docs][url-namespace-docs] for more details.)

Copy link

CollaboratorAuthor

carltongibsonFeb 22, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Maybe if I drop the whole "...ifnamespace=None bit... and just let people read the docs.

Copy link

Contributor

lovelydinosaurFeb 23, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Yup. Althoughdo let's reference Django'sinclude docs here - I think that'd be helpful.

carltongibson added2 commits

March 6, 2018 09:08

Provide both app and instance namespace examples

8f821dc

Emphasise non-namespaced option

e274bcd

Copy link

CollaboratorAuthor

carltongibson commentedMar 6, 2018

Hey@tomchristie. Can I ask you to pass your eyes over this again.

8f821dc Gives both app and instance namespace examples and links to both parts of the Django docs. I think it's about as clear as can be (without it becoming an essay).
e274bcd adds a little emphasis to the idea that you probably don't need namespaces, which is relevant when you're usingHyperlinked.... I keep having the same conversation around that, so I just want to draw it out. (I don't think people would be using namespaces at all unless we showed them).

carltongibson merged commit0da4617 intoencode:master

Mar 13, 2018

carltongibson deleted the 38/router-include-docs branch

March 13, 2018 14:52

carltongibson mentioned this pull request

Mar 13, 2018

HyperlinkedModelSerializer fails when app_name is configured and URLs added to app.#5850

Closed

6 tasks

TheMickeyMike mentioned this pull request

Mar 19, 2018

BOOK-26 | Create Comments Approgemus/BookHub#6

Merged

pchiquet pushed a commit to pchiquet/django-rest-framework that referenced this pull request

Nov 17, 2020

Corrected docs on router include with namespaces. (encode#5843)

aaf55ac

* Provide both app and instance namespace examples* Emphasise non-namespaced option

Labels

Documentation

Movatterモバイル変換

Uh oh!

Corrected docs on router include with namespaces.#5843

Corrected docs on router include with namespaces.#5843

Uh oh!

Conversation

carltongibson commentedFeb 20, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carltongibsonFeb 22, 2018• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carltongibson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carltongibson commentedMar 6, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

carltongibsonFeb 22, 2018•
edited
Loading