Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

#18451 Improved class based view documentation #144

Closed
wants to merge 90 commits into from

12 participants

Daniel Greenfeld Jacob Kaplan-Moss Marc Tamlyn Danilo Bargen Jannis Leidel Idan Gazit Bryan Helmig Luke Plant Keryn Knight Kenneth Love James Aylett Simon Williams
Daniel Greenfeld

For https://code.djangoproject.com/ticket/18451

Ref Improvements:

  • Documentation moved to /ref/class-based-views/ directory.
  • Method Resolution Order (MRO) on most views.
  • Method flowchart added to many views.
  • Mixins moved to their own pages.
  • Mixins demonstrate which other Mixins they extend.
  • Autodoc added to all views and mixins.
    • Because the Django code does always not contain docstrings, or it is not complete, there remains in many cases the old manual documentation.
    • 'Note' statements placed whenever autodoc is in addition to manual documentation.

Topic Improvements:

  • Documentation moved to /topics/class-based-views/ directory.
  • Cleaner explanation including additional examples.
  • More examples.
  • Mixins moved to their own pages.
  • Very clean mixin documentation with advocacy for best practices.

Authors:

  • Daniel Greenfeld
  • James Aylett
  • Marc Tamlyn
  • Simon Williams
and others added some commits June 07, 2012
Marc Tamlyn Don't refer to all cbvs as 'generic views'. d9fbf40
Marc Tamlyn Text wrapping. f13a378
Marc Tamlyn Split up discussion of CBV and Generic CBV. 8967e70
Marc Tamlyn Templates can exist in multiple places. cf5d4ed
Marc Tamlyn Make example code use the subclassing pattern. 9b32d1e
Marc Tamlyn Move deiscussion of GCBVs into separate file. e63051f
Marc Tamlyn Separate reference documentation of cbvs and mixins. b4c4096
Marc Tamlyn Add stubs for other cbv topic areas. 84cb8c2
Daniel Greenfeld Changed references to 'simple generic class based views' to 'Fundamen…
…tal class based views'. Also worked on some new dialogue to help explain things
a29adf2
Daniel Greenfeld Finished removal of generic from description of fundamental class bas…
…ed views
323c9ec
Marc Tamlyn Promote and expand on when to stop. 3407c81
Daniel Greenfeld Added much of what should hopefully be the new format for the View an…
…d TemplateView fundamental classes
0a2b8bf
Daniel Greenfeld converted 'mixins' for fundamental classes to method resolution order 379af2a
Marc Tamlyn Best practices in list and detail views examples.
Try to make the examples more consistent and follow some best practices.
For example: all strings are single quoted, views are always defined via
subclassing, and certain 1.4 now features are given for reference rather
than re-implementing them.
296ee0f
Marc Tamlyn Put in a placeholder to reference other topics. 44796a1
Marc Tamlyn Better use of the timezeone aware now. 6c28263
Daniel Greenfeld Finished documentation of fundamental views and also added working ex…
…ample code to all views
75ce4f5
Daniel Greenfeld Fixed regular expression in urls.py example a646fca
Daniel Greenfeld Added working version of View example fa22bb5
James Aylett Add new CBV & generic CBV topic documents into index. afbaef9
James Aylett Augment docstring to mention response_kwargs. 7cb8d3b
James Aylett Update JSONResponseMixin to match newer TemplateResponseMixin, and pr…
…ovide a ref target for that section.
af7519e
James Aylett Basic reference documentation of ContextMixin. 983b554
James Aylett Stage one of CBV mixin topic docs: what's there and how it's used in …
…the generic views.
9447a8a
James Aylett Fix up reference to generic views documentation. 8c06593
Daniel Greenfeld Merge pull request #1 from jaylett/cbv-docs
Cbv docs changes provided by @jaylett
1e65f4b
Daniel Greenfeld Temporary RST fix on a note b0ead02
Initial content for cbv form handling page b7215b4
Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs c906dc1
Simon Williams Added missing success_url for DeleteView 633fd1b
Daniel Greenfeld Merge pull request #2 from SystemParadox/cbv-docs
Initial form handling CBV docs
f3e0445
Simon Williams Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs ae0aeba
Daniel Greenfeld moved mention of the Base* views out of the generic CBV references an…
…d into a note section at the bottom
08f73a9
James Aylett Add some descriptions missing for core mixins.
Add "Methods & Attributes" headers throughout CBV mixin ref docs.
e4d063b
Simon Williams Added note about form_class and model c2ae752
Simon Williams Added example for created_by user handing in CreateView 0089cf0
Simon Williams Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs 22a6d87
Daniel Greenfeld Implemented the first pass on the new autodoc system 65b2e08
Simon Williams Improved documentation for form_valid 2157dc4
Daniel Greenfeld Added views index 6775bbe
Daniel Greenfeld Merge pull request #3 from SystemParadox/cbv-docs
CBV form docs
c3e4a43
Daniel Greenfeld Changed CBV ref navigation to use a dedicated class-based-views direc…
…tory. This lets us break up the huge files into smaller, more digestible components
b2800a6
James Aylett Name the AuthorDetailView URL, and provide a target for one of the se…
…ctions.
58f6c49
James Aylett Three examples of using mixins with other CBVs.
Both the more-complex-than-View + mixin examples are suspicious, and reinforce the view that this is a bad idea. I'd probably favour dropping the FormMixin + DetailView example as unreadable and unhelpful.

The SingleObjectMixin + ListView requires a little thought, but is still just about manageable and is a helpful thing to be able to do. SingleObjectMixin + View is just fine.
1008dc9
James Aylett Merge remote branch 'refs/remotes/pydanny/cbv-docs' into cbv-docs 5eba978
Daniel Greenfeld Added autoclass to generic-editing views 6e50c43
Daniel Greenfeld corrected formatting to include proper section titles across generic …
…class based view refs
9effb21
Daniel Greenfeld Added the mro.py prettification script at root of docs. Demonstrated …
…the results of the script by updating the MRO statements for fundamental, display, and edit class based views
7b9467e
Marc Tamlyn Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs d13df05
Marc Tamlyn No more `"` and `'` mixing! 2ef458d
Daniel Greenfeld Added in the date class based generic views MRO listings c0e7e43
Move class based view topic docs into their own subtree, matching
the ref docs.
986f280
Merge remote branch 'pydanny/cbv-docs' into cbv-docs f6d1d2c
Daniel Greenfeld initial work on documenting the mixins 660dc51
Take the most vile example of combining generic CBV functionality
and present it as something not to do; explain a couple of other
approaches of doing the same things which have fewer problems.
fc2c08e
Merge remote branch 'pydanny/cbv-docs' into cbv-docs 92cb9f2
Update to new ref doc place for CBV mixins. 93102be
More explicit warnings, and light text fettling from pydanny. 6a0a067
Daniel Greenfeld Merge pull request #6 from jaylett/cbv-docs
Mixins galore.
2076df7
Daniel Greenfeld resolved merge conflict and also did a little cleanup on the mro script d75be87
Daniel Greenfeld Broke up the mixins reference in order to make it more human friendly…
…. The files went into the same directory as the CBV refs in order to keep nesting at a minimum.
20af74b
Link warning suitably. 8647a5a
More cross linking, and some more explanation, in generic editing
CBV topic.
950cbb9
Daniel Greenfeld Added note to Autodoc methods/attributes explaining that it's a work …
…in progress
be84676
Daniel Greenfeld Merge pull request #7 from jaylett/cbv-docs
Cbv docs
6aa1f54
Daniel Greenfeld Clarificaton that ProcessFormView is actually a mixin. 1a136cc
Daniel Greenfeld Corrected spelling issues, removed empty generic-date-based CBV topic…
… file, and other minor cleanups
e697822
Marc Tamlyn Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs b342b7d
Marc Tamlyn Moderate language regarding diy views.
As requested by @pydanny.
175b6ce
Daniel Greenfeld Merge pull request #5 from mjtamlyn/cbv-docs
First run through improving the generic cbv topic.
bc40fc2
Daniel Greenfeld Merge remote-tracking branch 'upstream/master' into cbv-docs 728dc2c
Daniel Greenfeld Changed a TODO to a RST comment 9a37ed1
docs/ref/class-based-views.old
((350 lines not shown))
  350
+    **Ancestors (MRO)**
  351
+    
  352
+    * :class:`django.views.generic.detail.SingleObjectTemplateResponseMixin`
  353
+    * :class:`django.views.generic.base.TemplateResponseMixin`
  354
+    * :class:`django.views.generic.detail.BaseDetailView`
  355
+    * :class:`django.views.generic.detail.SingleObjectMixin`
  356
+    * :class:`django.views.generic.base.View`
  357
+
  358
+    **Method Flowchart**
  359
+
  360
+    1. dispatch()
  361
+    2. http_method_not_allowed()
  362
+    3. get_template_names()
  363
+    4. get_slug_field()
  364
+    5. get_queryset()
  365
+    6. get_object
1
Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

Missing a () here (and some other similar places)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views.old
((304 lines not shown))
  304
+
  305
+        Constructs the target URL for redirection.
  306
+
  307
+        The default implementation uses :attr:`~RedirectView.url` as a starting
  308
+        string, performs expansion of ``%`` parameters in that string, as well
  309
+        as the appending of query string if requested by
  310
+        :attr:`~RedirectView.query_string`. Subclasses may implement any
  311
+        behavior they wish, as long as the method returns a redirect-ready URL
  312
+        string.        
  313
+
  314
+    **Autoclass methods**
  315
+
  316
+Generic views
  317
+=============
  318
+
  319
+Django’s generic views were developed to ease that pain. They take certain
2
Luke Plant Owner
spookylukey added a note June 08, 2012

"that pain" - what pain?

Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

Sorry I'd split up some paragraphs and nor properly proof read them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Jacob Kaplan-Moss
Owner

Filling in some discussion from IRC:

I think this should nix the use of autodoc. autodoc isn't used in Django's docs deliberately: it prevents translation (which we want to do, despite have not done it...) and it can cause the docs to be hard to build (since it means they have to be able to import django, risking the dreaded DJANGO_SETTINGS_MODULE error). Instead, I'd like to see this use the include directive to avoid repetition.

added some commits June 08, 2012
Kenneth Love Updates to the edit views' docstrings.
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
632b801
Kenneth Love Updates to the date views
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
efe4601
Kenneth Love Updates to the base views
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
1282938
Kenneth Love Updates to the detail views
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
ba0e4c5
Kenneth Love Updates to the list views
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
70b9b3a
docs/ref/class-based-views.old
... ...
@@ -0,0 +1,736 @@
  1
+=================
  2
+Class-based views
  3
+=================
  4
+
  5
+.. versionadded:: 1.3
  6
+
  7
+.. note::
  8
+    Prior to Django 1.3, class based views were implemented as functions. The
2
Keryn Knight
kezabelle added a note June 08, 2012

This line is incorrect; generic views were functions. Class based views weren't implemented.

Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

Agreed. This sentence makes no sense.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views.old
((26 lines not shown))
  26
+Fundamental class based views
  27
+=============================
  28
+
  29
+The following three classes provide much of the functionality needed to create
  30
+Django views. You may think of them as *base* views, which can be used by
  31
+themselves or inherited from.  They may not provide all the capabilities required
  32
+for projects, in which case there are Mixins and Generic class based views.
  33
+
  34
+Specification
  35
+-------------
  36
+
  37
+Each request served by a class based view has an independent state; therefore,
  38
+it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is
  39
+a thread-safe operation).
  40
+
  41
+A class-based view is deployed into a URL pattern using the
5
Keryn Knight
kezabelle added a note June 08, 2012

Interchanges class-based and class based
(side note: Does this warrant a distinct note in the Django specific terminology for documentation?)

Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

Hmm, which do you think is better. I guess class based.

Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

On second thoughts and after searching the existing docs it should be class-based. The release notes certainly always use this form. I'll update all references not just those in this section.

Kenneth Love
kennethlove added a note June 08, 2012

class-based would be proper grammer, just like we'd use Earth-based or faith-based.

Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

Fixed in 87b5513.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
((30 lines not shown))
  30
+        2. http_method_not_allowed()
  31
+
  32
+
  33
+    **Example views.py**::
  34
+
  35
+        from django.http import HttpResponse
  36
+        from django.views.generic import View
  37
+
  38
+        class MyView(View):
  39
+
  40
+            def get(self, request, *args, **kwargs):
  41
+                return HttpResponse('Hello, World!')
  42
+
  43
+    **Example urls.py**::
  44
+    
  45
+        from django.conf.urls.defaults import patterns, url
3
Keryn Knight
kezabelle added a note June 08, 2012

This occurs in a few examples through-out the diff, but the references in the existing docs, as of 1.4 should be using from django.conf.urls import ..., though I can't find the ticket that updated them.

Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

Yup, I'd forgotten we had that updated import path.

Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

Fixed in b93208e

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Marc Tamlyn
Owner

More updates from me can be found here: https://github.com/pydanny/django/pull/8. When @pydanny has accepted them they'll appear here.

Marc Tamlyn mjtamlyn commented on the diff June 08, 2012
docs/topics/class-based-views/mixins.txt
((582 lines not shown))
  582
+
  583
+Finally we bring this together in a new :class:`AuthorDetail` view. We
  584
+already know that calling :meth:`as_view()` on a class based view
  585
+gives us something that behaves exactly like a function based view, so
  586
+we can do that at the point we choose between the two subviews.
  587
+
  588
+You can of course pass through keyword arguments to :meth:`as_view()`
  589
+in the same way you would in your URLconf, such as if you wanted the
  590
+:class:`AuthorInterest` behaviour to also appear at another URL but
  591
+using a different template.
  592
+
  593
+.. code-block:: python
  594
+
  595
+    from django.views.generic import View
  596
+    
  597
+    class AuthorDetail(View):
1
Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

My first reaction reading this was 'why not just write a functional view for this one, it's only 4 lines'. May be worth pointing out that (for example) this code with 405 to a PUT request.

Really nice example though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Marc Tamlyn mjtamlyn commented on the diff June 08, 2012
docs/topics/class-based-views/mixins.txt
((550 lines not shown))
  550
+            }
  551
+            context.update(kwargs)
  552
+            return super(AuthorDisplay, self).get_context_data(**context)
  553
+    
  554
+Then the :class:`AuthorInterest` is a simple :class:`FormView`, but we
  555
+have to bring in :class:`SingleObjectMixin` so we can find the author
  556
+we're talking about, and we have to remember to set
  557
+:attr:`template_name` to ensure that form errors will render the same
  558
+template as :class:`AuthorDisplay` is using on ``GET``.
  559
+
  560
+.. code-block:: python
  561
+
  562
+    from django.views.generic import FormView
  563
+    from django.views.generic.detail import SingleObjectMixin
  564
+    
  565
+    class AuthorInterest(FormView, SingleObjectMixin):
1
Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

There's possibly some missing subtlety here. If an invalid POST is made to this view, object will not be in the context. We need to actually implement this little test app somewhere in order to ensure all of our example code behaves as predicted.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Marc Tamlyn mjtamlyn commented on the diff June 08, 2012
docs/topics/class-based-views/generic-editing.txt
... ...
@@ -0,0 +1,205 @@
1
Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

Need to think about how this interacts with the working with forms doc. There should be a reference back to this document from the other one. Unsurprisingly, there is a substantial difference in tone/verbosity between this doc and the mixins doc. It would be good to get a more cohesive feeling here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/generic-editing.txt
((88 lines not shown))
  88
+First we need to add :meth:`get_absolute_url()` to our :class:`Author`
  89
+class:
  90
+
  91
+.. code-block:: python
  92
+
  93
+    # models.py
  94
+    from django import models
  95
+    from django.core.urlresolvers import reverse
  96
+
  97
+    class Author(models.Model):
  98
+        name = models.CharField(max_length=200)
  99
+
  100
+        def get_absolute_url(self):
  101
+            return reverse(
  102
+                'author-detail',
  103
+                kwargs = { 'pk': self.pk', },
1
Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

Syntax error! Extra ' after self.pk. Also we should be showing valid pep8 code - no spaces inside a dict literal.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/generic-editing.txt
((107 lines not shown))
  107
+work. Notice how we're just configuring the generic class based views
  108
+here; we don't have to write any logic ourselves::
  109
+   
  110
+    # views.py
  111
+    from myapp.models import Author
  112
+    from django.views.generic.edit import CreateView, UpdateView, DeleteView
  113
+
  114
+    class AuthorCreate(CreateView):
  115
+        model = Author
  116
+
  117
+    class AuthorUpdate(UpdateView):
  118
+        model = Author
  119
+
  120
+    class AuthorDelete(DeleteView):
  121
+        model = Author
  122
+        success_url = '/authors/'
1
Marc Tamlyn Owner
mjtamlyn added a note June 08, 2012

If we're doing best practices here, this should be a lazy_reverse('authors_list') or something along those lines.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Danilo Bargen
dbrgn commented June 08, 2012

Wow, sorry for the interruption, but thanks for your great documentation efforts! :)

docs/ref/class-based-views.old
... ...
@@ -0,0 +1,736 @@
  1
+=================
  2
+Class-based views
  3
+=================
  4
+
  5
+.. versionadded:: 1.3
  6
+
  7
+.. note::
  8
+    Prior to Django 1.3, class based views were implemented as functions. The
  9
+    function-based implementation has been removed in favor of the
  10
+    class-based approach described here.
  11
+
  12
+
  13
+Writing Web applications can be monotonous, because we repeat certain patterns
2
Danilo Bargen
dbrgn added a note June 08, 2012

Should "Web" really be capitalized? Same thing two lines below.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
((61 lines not shown))
  61
+
  62
+        The ``view`` part of the view -- the method that accepts a ``request``
  63
+        argument plus arguments, and returns a HTTP response.
  64
+
  65
+        The default implementation will inspect the HTTP method and attempt to
  66
+        delegate to a method that matches the HTTP method; a ``GET`` will be
  67
+        delegated to :meth:`~View.get()`, a ``POST`` to :meth:`~View.post()`,
  68
+        and so on.
  69
+
  70
+        The default implementation also sets ``request``, ``args`` and
  71
+        ``kwargs`` as instance variables, so any method on the view can know
  72
+        the full details of the request that was made to invoke the view.
  73
+
  74
+    .. method:: http_method_not_allowed(request, *args, **kwargs)
  75
+
  76
+        If the view was called with HTTP method it doesn't support, this method
1
Danilo Bargen
dbrgn added a note June 08, 2012

s/with HTTP method/with a HTTP method/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
((99 lines not shown))
  99
+    which is a dictionary of the parameters captured in the URL.
  100
+    
  101
+    **Classpath**
  102
+    
  103
+    ``django.views.generic.base.TemplateView``    
  104
+
  105
+    **Ancestors (MRO)**
  106
+
  107
+    * :class:`django.views.generic.base.TemplateView`
  108
+    * :class:`django.views.generic.base.TemplateResponseMixin`
  109
+    * :class:`django.views.generic.base.View`
  110
+    
  111
+    **Method Flowchart**
  112
+
  113
+        1. dispatch()
  114
+        2. http_method_not_allowed()
1
Danilo Bargen
dbrgn added a note June 08, 2012

Why http_method_not_allowed()? Shouldn't that rather be handler() or get() / post() / put() / ...?

Same thing applies for other Method Flowchart listings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/generic-display.txt
((28 lines not shown))
  28
+    * :class:`django.views.generic.detail.BaseDetailView`
  29
+    * :class:`django.views.generic.detail.SingleObjectMixin`
  30
+    * :class:`django.views.generic.base.View`
  31
+
  32
+    **Method Flowchart**
  33
+
  34
+    1. dispatch()
  35
+    2. http_method_not_allowed()
  36
+    3. get_template_names()
  37
+    4. get_slug_field()
  38
+    5. get_queryset()
  39
+    6. get_object
  40
+    7. get_context_object_name()
  41
+    8. get_context_data()
  42
+    9. get()
  43
+    10. render_to_response()
6
Danilo Bargen
dbrgn added a note June 08, 2012

Something's wrong with this flowchart. get() is called right after the dispatch() method. http_method_not_allowed() should never be called, as mentioned in another comment above. get_object should be a function and should be executed after get().

Danilo Bargen
dbrgn added a note June 10, 2012

Bump.

Daniel Greenfeld
pydanny added a note June 10, 2012

I like fundamental and agree with mjtamlyn.

As for flowcharts,

The flowcharts are purposefully in this simplified format for now and I request they stay in this format on this pull request. In other words, I would like it to be addressed in a future pull request. In fact, @jacobian says he has an idea for rendering them, and @idangazit should certainly be given his say. On a side note, I prefer Graphviz, but only out of familiarity.

As for their completeness, while I would like to get them to 100% right now, that is not a small amount of work. I think a better option is to accept this monolithic pull request sooner rather then later, then let the flow charts be handled in a smaller pull request or a series of them. That way they can be more easily audited and will allow more eyes on them, making a deep problem very shallow. :wink:

Idan Gazit Owner
idan added a note June 11, 2012

Wow, wrapping my head around this gigantic thread. I love having Django on github.

I assume these must be renderable programmatically because there will be a lot of them. Must they be renderable at docs-creation time? Alternatively, if we can stipulate that they are renderable in-browser, that lets us do some nice things there (but makes PDF generation more complicated, for example.

Off the top of my head, there are three good options for rendering the charts:

  • Graphviz: simple, descriptive language for defining graph. Not much control over rendering output.
  • Nodebox: A graphics library for python, analogous to Processing. Nodebox-opengl seems pip-installable, need to see that this works on all platforms. Pros: majorly nice control over rendering output. Cons: commensurate headache.
  • D3 or other web charting/graphics libraries: a nice way to do it in-browser. Cons: only in-browser.

Right now the commit isn't clear on much of a flow, it's just a list of steps in order. Perhaps an IRC discussion to help me get my bearings would be helpful,

Idan Gazit Owner
idan added a note June 11, 2012

Following up: I'm +1 on the docs containing a rough outline of operation in bullet-point form now, and improving things to add some graphical representation later. This is already a monster pull request, no need to hold it up for Just One More Addition.

Jannis Leidel Owner
jezdez added a note June 11, 2012

FYI, you are all commenting on a code line not on the pull request.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Danilo Bargen
dbrgn commented June 08, 2012

I could probably help a little with those docs, but I don't want to conflict with currently ongoing work. Is anyone working on major changes?

Something I noticed is that the method flowcharts aren't always correct. I could for example verify and correct those.

Against which version are those docs written? 1.5-dev?

Marc Tamlyn
Owner

Ok, autodoc is nixed. #145 has been merged in. Most of the small comments from here are fixed up, and the dead files (ref/class-based-views.old and mro.py) have been deleted.

So I think we're kinda there. There's still a load to do but it would make sense to get this merged in and then look for smaller patches to improve it further. Will make it much easier for others to get involved.

django/views/generic/edit.py
@@ -106,10 +119,17 @@ def get_success_url(self):
106 119
         return url
107 120
 
108 121
     def form_valid(self, form):
  122
+        """
  123
+        If the form is valid, save is associated model.
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

Typo.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
django/views/generic/edit.py
@@ -125,11 +145,19 @@ class ProcessFormView(View):
125 145
     A mixin that processes a form on POST.
126 146
     """
127 147
     def get(self, request, *args, **kwargs):
  148
+        """
  149
+        Handles the GET HTTP verb and instantiates a blank version of the form.
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

You mean "handles GET requests"?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
django/views/generic/edit.py
((7 lines not shown))
128 151
         form_class = self.get_form_class()
129 152
         form = self.get_form(form_class)
130 153
         return self.render_to_response(self.get_context_data(form=form))
131 154
 
132 155
     def post(self, request, *args, **kwargs):
  156
+        """
  157
+        Handles the POST HTTP verb, instantiating an instance of the class
2
Jannis Leidel Owner
jezdez added a note June 09, 2012

"Handles POST requests" please.

Jannis Leidel Owner
jezdez added a note June 09, 2012

"Instantiating a form instance with the passed POST variables, .." sounds simpler.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/conf.py
@@ -20,6 +20,10 @@
20 20
 # add these directories to sys.path here. If the directory is relative to the
21 21
 # documentation root, use os.path.abspath to make it absolute, like shown here.
22 22
 sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext")))
  23
+sys.path.insert(0, os.path.abspath('../'))
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

If all autodoc is removed now, we can remove this, too. Including the settings.configure() call.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
... ...
@@ -0,0 +1,246 @@
  1
+=============================
  2
+Fundamental class-based views
  3
+=============================
  4
+
  5
+The following three classes provide much of the functionality needed to create
  6
+Django views. You may think of them as *base* views, which can be used by
  7
+themselves or inherited from.  They may not provide all the capabilities required
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

Two spaces behind the punctuation?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
((23 lines not shown))
  23
+
  24
+        from django.http import HttpResponse
  25
+        from django.views.generic import View
  26
+
  27
+        class MyView(View):
  28
+
  29
+            def get(self, request, *args, **kwargs):
  30
+                return HttpResponse('Hello, World!')
  31
+
  32
+    **Example urls.py**::
  33
+
  34
+        from django.conf.urls import patterns, url
  35
+        
  36
+        from myapp.views import MyView
  37
+        
  38
+        urlpatterns = patterns("",
2
Jannis Leidel Owner
jezdez added a note June 09, 2012

Let's use PEP8 code style here.

Marc Tamlyn Owner
mjtamlyn added a note June 09, 2012

God yes. It hurts my eyeses.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
((170 lines not shown))
  170
+
  171
+        from django.shortcuts import get_object_or_404
  172
+        from django.views.generic.base import RedirectView
  173
+        
  174
+        from articles.models import Article
  175
+
  176
+        class ArticleCounterRedirectView(RedirectView):
  177
+
  178
+            permanent = True
  179
+            query_string = True
  180
+
  181
+            def get_redirect_url(self, pk):
  182
+                article = get_object_or_404(Article, pk=pk)
  183
+                article.count += 1
  184
+                article.save()
  185
+                return reverse('product_detail', args=(pk, ))
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

One space too much.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/fundamentals.txt
((168 lines not shown))
  168
+
  169
+    **Example views.py**::
  170
+
  171
+        from django.shortcuts import get_object_or_404
  172
+        from django.views.generic.base import RedirectView
  173
+        
  174
+        from articles.models import Article
  175
+
  176
+        class ArticleCounterRedirectView(RedirectView):
  177
+
  178
+            permanent = True
  179
+            query_string = True
  180
+
  181
+            def get_redirect_url(self, pk):
  182
+                article = get_object_or_404(Article, pk=pk)
  183
+                article.count += 1
3
Jannis Leidel Owner
jezdez added a note June 09, 2012

The example is well-intended but maybe should do something else, or use the F object.

Marc Tamlyn Owner
mjtamlyn added a note June 09, 2012

Opted for calling an imaginary update_counter method on the article. Also set it to be non-permanent redirect otherwise it wouldn't be much use as a view (I believe the browser would skip hitting this url at all in future)

Jannis Leidel Owner
jezdez added a note June 09, 2012

Cool!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/generic-date-based.txt
((62 lines not shown))
  62
+
  63
+        Determine if an object list will be returned as part of the context. If
  64
+        ``False``, the ``None`` queryset will be used as the object list.
  65
+
  66
+    **Context**
  67
+
  68
+    In addition to the context provided by
  69
+    :class:`django.views.generic.list.MultipleObjectMixin` (via
  70
+    :class:`django.views.generic.dates.BaseDateListView`), the template's
  71
+    context will be:
  72
+
  73
+    * ``date_list``: A ``DateQuerySet`` object containing all months that
  74
+      have objects available according to ``queryset``, represented as
  75
+      ``datetime.datetime`` objects, in ascending order.
  76
+
  77
+    * ``year``: A ``datetime.date`` object representing the given year.
3
Jannis Leidel Owner
jezdez added a note June 09, 2012

We could use the intersphinx ability in Sphinx here to link to the Python docs.

Marc Tamlyn Owner
mjtamlyn added a note June 09, 2012

Would be nice. Couldn't seem to get it to work.

It looks like it's been set up to link to the python docs in the conf.py but :ref:datetime.date<python:anything-here> (with the necessary back ticks) was giving me an error:

WARNING: undefined label: python:datetime (if the link has no caption the label must precede a section header)

Jannis Leidel Owner
jezdez added a note June 09, 2012

Try :class:datetime.date

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/generic-date-based.txt
... ...
@@ -0,0 +1,275 @@
  1
+====================================
  2
+Generic date class-based views
  3
+====================================
  4
+
  5
+Date-based generic views (in the module :mod:`django.views.generic.dates`)
  6
+are views for displaying drilldown pages for date-based data.
  7
+
  8
+.. currentmodule:: django.views.generic.dates
  9
+
  10
+ArchiveIndexView
  11
+~~~~~~~~~~~~~~~~
  12
+.. class:: ArchiveIndexView()
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

I don't think brackets are needed here for the class directive.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/generic-date-based.txt
((104 lines not shown))
  104
+    * :class:`django.views.generic.dates.BaseMonthArchiveView`
  105
+    * :class:`django.views.generic.dates.YearMixin`
  106
+    * :class:`django.views.generic.dates.MonthMixin`
  107
+    * :class:`django.views.generic.dates.BaseDateListView`
  108
+    * :class:`django.views.generic.list.MultipleObjectMixin`
  109
+    * :class:`django.views.generic.dates.DateMixin`
  110
+    * :class:`django.views.generic.base.View`
  111
+
  112
+    **Context**
  113
+
  114
+    In addition to the context provided by
  115
+    :class:`~django.views.generic.list.MultipleObjectMixin` (via
  116
+    :class:`~django.views.generic.dates.BaseDateListView`), the template's
  117
+    context will be:
  118
+
  119
+    * ``date_list``: A ``DateQuerySet`` object containing all days that
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

Could we link to DateQuerySet here?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/generic-display.txt
((34 lines not shown))
  34
+
  35
+    **Example views.py**::
  36
+
  37
+        from datetime import datetime
  38
+
  39
+        from django.views.generic.detail import DetailView
  40
+
  41
+        from articles.models import Article
  42
+
  43
+        class ArticleDetailView(DetailView):
  44
+        
  45
+            model = Article
  46
+
  47
+            def get_context_data(self, **kwargs):
  48
+                context = super(ArticleDetailView, self).get_context_data(**kwargs)
  49
+                context['now'] = datetime.now()
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

We should discourage using datetime.now given the new timezone abilities in 1.4. Instead use django.utils.timezone.now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/index.txt
((13 lines not shown))
  13
+   generic-editing
  14
+   generic-date-based
  15
+   mixins
  16
+
  17
+Specification
  18
+-------------
  19
+
  20
+Each request served by a class-based view has an independent state; therefore,
  21
+it is safe to store state variables on the instance (i.e., ``self.foo = 3`` is
  22
+a thread-safe operation).
  23
+
  24
+A class-based view is deployed into a URL pattern using the
  25
+:meth:`~View.as_view()` classmethod::
  26
+
  27
+    urlpatterns = patterns('',
  28
+            (r'^view/$', MyView.as_view(size=42)),
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

Indented wrong.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/index.txt
((26 lines not shown))
  26
+
  27
+    urlpatterns = patterns('',
  28
+            (r'^view/$', MyView.as_view(size=42)),
  29
+        )
  30
+
  31
+.. admonition:: Thread safety with view arguments
  32
+
  33
+    Arguments passed to a view are shared between every instance of a view.
  34
+    This means that you shoudn't use a list, dictionary, or any other
  35
+    variable object as an argument to a view. If you did, the actions of
  36
+    one user visiting your view could have an effect on subsequent users
  37
+    visiting the same view.
  38
+
  39
+Any argument passed into :meth:`~View.as_view()` will be assigned onto the
  40
+instance that is used to service a request. Using the previous example,
  41
+this means that every request on ``MyView`` is able to interrogate
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

"use" instead of "interrogate"?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/index.txt
((33 lines not shown))
  33
+    Arguments passed to a view are shared between every instance of a view.
  34
+    This means that you shoudn't use a list, dictionary, or any other
  35
+    variable object as an argument to a view. If you did, the actions of
  36
+    one user visiting your view could have an effect on subsequent users
  37
+    visiting the same view.
  38
+
  39
+Any argument passed into :meth:`~View.as_view()` will be assigned onto the
  40
+instance that is used to service a request. Using the previous example,
  41
+this means that every request on ``MyView`` is able to interrogate
  42
+``self.size``.
  43
+
  44
+Fundamental vs Generic class-based views
  45
+-----------------------------------------
  46
+
  47
+Fundamental class-based views can be thought of as *base* views, which can be
  48
+used by themselves or inherited from.  They may not provide all the
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

Double space after dot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/index.txt
((35 lines not shown))
  35
+    variable object as an argument to a view. If you did, the actions of
  36
+    one user visiting your view could have an effect on subsequent users
  37
+    visiting the same view.
  38
+
  39
+Any argument passed into :meth:`~View.as_view()` will be assigned onto the
  40
+instance that is used to service a request. Using the previous example,
  41
+this means that every request on ``MyView`` is able to interrogate
  42
+``self.size``.
  43
+
  44
+Fundamental vs Generic class-based views
  45
+-----------------------------------------
  46
+
  47
+Fundamental class-based views can be thought of as *base* views, which can be
  48
+used by themselves or inherited from.  They may not provide all the
  49
+capabilities required for projects, in which case there are Mixins which extend
  50
+what Fundamental views can do.
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

lower case for "Fundamental"?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/mixins-editing.txt
((13 lines not shown))
  13
+        A dictionary containing initial data for the form.
  14
+
  15
+    .. attribute:: form_class
  16
+
  17
+        The form class to instantiate.
  18
+
  19
+    .. attribute:: success_url
  20
+
  21
+        The URL to redirect to when the form is successfully processed.
  22
+
  23
+    .. method:: get_initial()
  24
+
  25
+        Retrieve initial data for the form. By default, returns a copy of
  26
+        :attr:`~django.views.generic.edit.FormMixin.initial`.
  27
+
  28
+    .. admonition:: Changed in 1.4
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

I think this can also be expressed with a .. versionchanged:: 1.4 directive.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/mixins-editing.txt
((132 lines not shown))
  132
+        Saves the form instance, sets the current object for the view, and
  133
+        redirects to
  134
+        :meth:`~django.views.generic.edit.FormMixin.get_success_url`.
  135
+
  136
+    .. method:: form_invalid()
  137
+
  138
+        Renders a response, providing the invalid form as context.
  139
+            
  140
+.. class:: django.views.generic.edit.ProcessFormView
  141
+
  142
+    A mixin that provides basic HTTP GET and POST workflow.
  143
+
  144
+    .. note:: 
  145
+
  146
+        This is named 'ProcessFormView' and inherits directly from :class:`django.views.generic.base.View`,
  147
+        but breaks if used independently. Therefore is actually a mixin.
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

Typo in last sentence.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/class-based-views/mixins-single-object.txt
((94 lines not shown))
  94
+    operating on. ``self.object`` will usually be, but is not required to be,
  95
+    an instance of a Django model. It may be ``None`` if the view is in the
  96
+    process of constructing a new instance.
  97
+
  98
+    **Extends**
  99
+
  100
+    * :class:`~django.views.generic.base.TemplateResponseMixin`
  101
+
  102
+    **Methods and Attributes**
  103
+
  104
+    .. attribute:: template_name_field
  105
+
  106
+        The field on the current object instance that can be used to determine
  107
+        the name of a candidate template. If either ``template_name_field`` or
  108
+        the value of the ``template_name_field`` on the current object instance
  109
+        is ``None``, the object will not be interrogated for a candidate
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

"interrogated"?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/generic-display.txt
((118 lines not shown))
  118
+    from django.conf.urls import patterns, url, include
  119
+    from books.views import PublisherList
  120
+
  121
+    urlpatterns = patterns('',
  122
+        url(r'^publishers/$', PublisherList.as_view()),
  123
+    )
  124
+
  125
+That's all the Python code we need to write. We still need to write a template,
  126
+however. We could explicitly tell the view which template to use by adding a
  127
+``template_name`` attribute to the view, but in the absence of an explicit
  128
+template Django will infer one from the object's name. In this case, the
  129
+inferred template will be ``"books/publisher_list.html"`` -- the "books" part
  130
+comes from the name of the app that defines the model, while the "publisher"
  131
+bit is just the lowercased version of the model's name.
  132
+
  133
+.. note:: Thus, when (for example) the :class:`django.template.loaders.app_directories.Loader` template loader is enabled in :setting:`TEMPLATE_LOADERS`, a template location could be: /path/to/project/books/templates/books/publisher_list.html
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

Please wrap the lines of this note.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/generic-display.txt
((211 lines not shown))
  211
+
  212
+    class PublisherDetail(DetailView):
  213
+
  214
+        model = Publisher
  215
+
  216
+        def get_context_data(self, **kwargs):
  217
+            # Call the base implementation first to get a context
  218
+            context = super(PublisherDetailView, self).get_context_data(**kwargs)
  219
+            # Add in a QuerySet of all the books
  220
+            context['book_list'] = Book.objects.all()
  221
+            return context
  222
+
  223
+.. note::
  224
+
  225
+    Generally, get_context_data will merge the context data of all parent classes
  226
+    with those of the current class.  To preserve this behavior in your own classes
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

Two spaces after the dot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Jannis Leidel jezdez commented on the diff June 09, 2012
docs/topics/class-based-views/generic-display.txt
((378 lines not shown))
  378
+        salutation = models.CharField(max_length=10)
  379
+        name = models.CharField(max_length=200)
  380
+        email = models.EmailField()
  381
+        headshot = models.ImageField(upload_to='/tmp')
  382
+        last_accessed = models.DateTimeField()
  383
+
  384
+The generic ``DetailView`` class, of course, wouldn't know anything about this
  385
+field, but once again we could easily write a custom view to keep that field
  386
+updated.
  387
+
  388
+First, we'd need to add an author detail bit in the URLconf to point to a
  389
+custom view::
  390
+
  391
+    from books.views import AuthorDetailView
  392
+
  393
+    urlpatterns = patterns('',
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

PEP8 please.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/generic-editing.txt
((71 lines not shown))
  71
+saves the model automatically.  You can override this if you have any
  72
+special requirements; see below for examples.
  73
+
  74
+You don't even need to provide a attr:`success_url` for
  75
+:class:`~django.views.generic.edit.CreateView` or
  76
+:class:`~django.views.generic.edit.UpdateView` - they will use
  77
+:meth:`get_absolute_url()` on the model object if available.
  78
+
  79
+If you want to use a custom :class:`ModelForm` (for instance to add
  80
+extra validation) simply set
  81
+:attr:`~django.views.generic.edit.FormMixin.form_class` on your view.
  82
+
  83
+.. note::
  84
+    When specifying a custom form class, you must still specify the model,
  85
+    even though the :attr:`form_class` may be a :class:`ModelForm`.
  86
+    (See https://code.djangoproject.com/ticket/15125)
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

Not sure if linking a ticket is really sensible here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/generic-editing.txt
((108 lines not shown))
  108
+    from django.views.generic.edit import CreateView, UpdateView, DeleteView
  109
+    from django.core.urlresolvers import reverse_lazy
  110
+    from myapp.models import Author
  111
+
  112
+    class AuthorCreate(CreateView):
  113
+        model = Author
  114
+
  115
+    class AuthorUpdate(UpdateView):
  116
+        model = Author
  117
+
  118
+    class AuthorDelete(DeleteView):
  119
+        model = Author
  120
+        success_url = reverse_lazy('author-list')
  121
+
  122
+.. note::
  123
+    We have to use ``reverse_lazy`` here, not just ``reverse`` as the urls are
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

Link to the reverse_lazy docs here?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/index.txt
((71 lines not shown))
  71
+    from django.conf.urls import patterns, url, include
  72
+    from django.views.generic import TemplateView
  73
+
  74
+    urlpatterns = patterns('',
  75
+        (r'^about/', TemplateView.as_view(template_name="about.html")),
  76
+    )
  77
+
  78
+A similar overriding pattern can be used for the ``url`` attribute on
  79
+:class:`~django.views.generic.base.RedirectView`.
  80
+
  81
+.. _jsonresponsemixin-example:
  82
+
  83
+More than just HTML
  84
+-------------------
  85
+
  86
+Where class based view shine is when you want to do the same thing many times.
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

s/view/views/g

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/mixins.txt
((22 lines not shown))
  22
+
  23
+For this reason, Django also provides a number of mixins that provide
  24
+more discrete functionality. Template rendering, for instance, is
  25
+encapsulated in the
  26
+:class:`~django.views.generic.base.TemplateResponseMixin`. The Django
  27
+reference documentation contains :doc:`full documentation of all the
  28
+mixins</ref/class-based-views/mixins>`.
  29
+
  30
+Context and template responses
  31
+==============================
  32
+
  33
+Two central mixins are provided that help in providing a consistent
  34
+interface to working with templates in class-based views.
  35
+
  36
+:class:`~django.views.generic.base.TemplateResponseMixin`
  37
+    Everywhere that needs to make a
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

"Everywhere that needs to make.." sounds odd to me.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/mixins.txt
((25 lines not shown))
  25
+encapsulated in the
  26
+:class:`~django.views.generic.base.TemplateResponseMixin`. The Django
  27
+reference documentation contains :doc:`full documentation of all the
  28
+mixins</ref/class-based-views/mixins>`.
  29
+
  30
+Context and template responses
  31
+==============================
  32
+
  33
+Two central mixins are provided that help in providing a consistent
  34
+interface to working with templates in class-based views.
  35
+
  36
+:class:`~django.views.generic.base.TemplateResponseMixin`
  37
+    Everywhere that needs to make a
  38
+    :class:`~django.template.response.TemplateResponse` will call the
  39
+    :meth:`~django.views.generic.base.TemplateResponseMixin.render_to_response`
  40
+    method that :class:`TemplateResponseMixin` provides.  Most of the time
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

Double space.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/mixins.txt
((49 lines not shown))
  49
+
  50
+    ``render_to_response`` itself calls
  51
+    :meth:`~django.views.generic.base.TemplateResponseMixin.get_template_names`,
  52
+    which by default will just look up
  53
+    :attr:`~django.views.generic.base.TemplateResponseMixin.template_name`
  54
+    on the class-based view; two other mixins
  55
+    (:class:`~django.views.generic.detail.SingleObjectTemplateResponseMixin`
  56
+    and
  57
+    :class:`~django.views.generic.list.MultipleObjectTemplateResponseMixin`)
  58
+    override this to provide more flexible defaults when dealing with
  59
+    actual objects.
  60
+
  61
+.. versionadded:: 1.5
  62
+
  63
+:class:`~django.views.generic.base.ContextMixin`
  64
+    Everywhere that needs context data, such as for rendering a
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

"Everywhere that needs context data" sounds odd.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Jannis Leidel jezdez commented on the diff June 09, 2012
docs/topics/class-based-views/mixins.txt
((235 lines not shown))
  235
+    from django.views.generic.detail import SingleObjectMixin
  236
+    from books.models import Author
  237
+    
  238
+    class RecordInterest(View, SingleObjectMixin):
  239
+        """Records the current user's interest in an author."""
  240
+        model = Author
  241
+    
  242
+        def post(self, request, *args, **kwargs):
  243
+            if not request.user.is_authenticated():
  244
+                return HttpResponseForbidden()
  245
+
  246
+            # Look up the author we're interested in.
  247
+            self.object = self.get_object()
  248
+            # Actually record interest somehow here!
  249
+
  250
+            return HttpResponseRedirect(
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

PEP8

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/class-based-views/mixins.txt
((259 lines not shown))
  259
+out. The only bit of the view that needs to worry about using
  260
+:class:`SingleObjectMixin` is where we want to look up the author
  261
+we're interested in, which it just does with a simple call to
  262
+``self.get_object()``. Everything else is taken care of for us by the
  263
+mixin.
  264
+
  265
+We can hook this into our URLs easily enough:
  266
+
  267
+.. code-block:: python
  268
+
  269
+    # urls.py
  270
+    from books.views import RecordInterest
  271
+
  272
+    urlpatterns = patterns('',
  273
+        #...
  274
+        **url(
1
Jannis Leidel Owner
jezdez added a note June 09, 2012

PEP8

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Jannis Leidel
Owner
jezdez commented June 09, 2012

Except some optional intersphinx links this looks good to me. If there are no other reviews, I'd commit this tomorrow.

Marc Tamlyn
Owner

@jezdez, master of intersphinx. I believe all outstanding blocking issues are resolved.

Jannis Leidel
Owner
jezdez commented June 10, 2012

Those changes fixed the build for me: https://gist.github.com/2907251

Jannis Leidel
Owner
jezdez commented June 10, 2012

Oh, I think I still have two issues:

  • The word "Fundamentals" for describing the base class based views seems a bit off to me. It may be my non-nativeness but it sounds like "Fundamentalists" which has a rather negative connotation. I know "base" is also pretty loaded, so what if we call it "Basic class based views". Alternatively "Essential class based views"?

  • The method flowcharts need some nice graphics, or at least links to the appropriate methods instead of just a list of text.

Given those two important things are still open, I won't merge this just yet. Any help with solving would be much appreciated.

Marc Tamlyn
Owner

Hmmm. I like fundamental. To me there's no connection with fundamentalist, and we're using it in the meaning of "Foundational" (which is a worse word) - kinda meaning that they're the important ones and the ones upon which everything else is built. Basic has connotations of simple, and I'm not sure they are... Essential also implies you have to use them, which you don't.

Flowcharts are a bit more of a question. I probably need to do a good review of them to make sure they're actually accurate. Some graphviz graphics would be nice, but I'm concerned about them not being updated properly. Either we build them first and commit the images to the repo, or we use http://sphinx.pocoo.org/ext/graphviz.html to build them dynamically. This would require everything to have the relevant binaries installed though. Opinions @jacobian?

A lot of the ref docs are incomplete - which includes the method flows. Not every method is documented yet (see previous discussion about includes/autodoc) - I've not written all of the replacement references now the autobuilt stuff is gone. Do we want to get it all accurate and finished before we merge anything?

Re those build changes, I'm not getting errors but that is tidier rst so I'll make those tweaks.

Daniel Greenfeld pydanny closed this June 11, 2012
Daniel Greenfeld

@idangazit I'm going to find you on IRC. Right now.

Daniel Greenfeld pydanny reopened this June 11, 2012
Jannis Leidel
Owner
jezdez commented June 11, 2012

I'm going to close this as I think it's ready for commit (I have all the changes locally). I've decided to not go with fundamental as I think it would introduce more confusion. But that's really a minor thing and I'm happy to say this is going to be a HUGE help for our users. Thank you good sirs.

Jannis Leidel jezdez closed this June 11, 2012
Idan Gazit
Owner
idan commented June 11, 2012

:cake::sparkles:

Bryan Helmig

Just in time to make us look foolish (http://3rdaverad.io/shows/django-podcast/episodes/class-vs-function-based-views/) as we complain about lack of documentation... :-D

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Showing 90 unique commits by 7 authors.

Jun 07, 2012
Marc Tamlyn Don't refer to all cbvs as 'generic views'. d9fbf40
Marc Tamlyn Text wrapping. f13a378
Marc Tamlyn Split up discussion of CBV and Generic CBV. 8967e70
Marc Tamlyn Templates can exist in multiple places. cf5d4ed
Marc Tamlyn Make example code use the subclassing pattern. 9b32d1e
Marc Tamlyn Move deiscussion of GCBVs into separate file. e63051f
Marc Tamlyn Separate reference documentation of cbvs and mixins. b4c4096
Marc Tamlyn Add stubs for other cbv topic areas. 84cb8c2
Daniel Greenfeld Changed references to 'simple generic class based views' to 'Fundamen…
…tal class based views'. Also worked on some new dialogue to help explain things
a29adf2
Daniel Greenfeld Finished removal of generic from description of fundamental class bas…
…ed views
323c9ec
Marc Tamlyn Promote and expand on when to stop. 3407c81
Daniel Greenfeld Added much of what should hopefully be the new format for the View an…
…d TemplateView fundamental classes
0a2b8bf
Daniel Greenfeld converted 'mixins' for fundamental classes to method resolution order 379af2a
Marc Tamlyn Best practices in list and detail views examples.
Try to make the examples more consistent and follow some best practices.
For example: all strings are single quoted, views are always defined via
subclassing, and certain 1.4 now features are given for reference rather
than re-implementing them.
296ee0f
Marc Tamlyn Put in a placeholder to reference other topics. 44796a1
Marc Tamlyn Better use of the timezeone aware now. 6c28263
Daniel Greenfeld Finished documentation of fundamental views and also added working ex…
…ample code to all views
75ce4f5
Daniel Greenfeld Fixed regular expression in urls.py example a646fca
Daniel Greenfeld Added working version of View example fa22bb5
James Aylett Add new CBV & generic CBV topic documents into index. afbaef9
James Aylett Augment docstring to mention response_kwargs. 7cb8d3b
James Aylett Update JSONResponseMixin to match newer TemplateResponseMixin, and pr…
…ovide a ref target for that section.
af7519e
James Aylett Basic reference documentation of ContextMixin. 983b554
James Aylett Stage one of CBV mixin topic docs: what's there and how it's used in …
…the generic views.
9447a8a
James Aylett Fix up reference to generic views documentation. 8c06593
Daniel Greenfeld Merge pull request #1 from jaylett/cbv-docs
Cbv docs changes provided by @jaylett
1e65f4b
Daniel Greenfeld Temporary RST fix on a note b0ead02
Initial content for cbv form handling page b7215b4
Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs c906dc1
Simon Williams Added missing success_url for DeleteView 633fd1b
Daniel Greenfeld Merge pull request #2 from SystemParadox/cbv-docs
Initial form handling CBV docs
f3e0445
Simon Williams Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs ae0aeba
Daniel Greenfeld moved mention of the Base* views out of the generic CBV references an…
…d into a note section at the bottom
08f73a9
James Aylett Add some descriptions missing for core mixins.
Add "Methods & Attributes" headers throughout CBV mixin ref docs.
e4d063b
Simon Williams Added note about form_class and model c2ae752
Simon Williams Added example for created_by user handing in CreateView 0089cf0
Simon Williams Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs 22a6d87
Daniel Greenfeld Implemented the first pass on the new autodoc system 65b2e08
Simon Williams Improved documentation for form_valid 2157dc4
Daniel Greenfeld Added views index 6775bbe
Daniel Greenfeld Merge pull request #3 from SystemParadox/cbv-docs
CBV form docs
c3e4a43
Daniel Greenfeld Changed CBV ref navigation to use a dedicated class-based-views direc…
…tory. This lets us break up the huge files into smaller, more digestible components
b2800a6
James Aylett Name the AuthorDetailView URL, and provide a target for one of the se…
…ctions.
58f6c49
James Aylett Three examples of using mixins with other CBVs.
Both the more-complex-than-View + mixin examples are suspicious, and reinforce the view that this is a bad idea. I'd probably favour dropping the FormMixin + DetailView example as unreadable and unhelpful.

The SingleObjectMixin + ListView requires a little thought, but is still just about manageable and is a helpful thing to be able to do. SingleObjectMixin + View is just fine.
1008dc9
James Aylett Merge remote branch 'refs/remotes/pydanny/cbv-docs' into cbv-docs 5eba978
Jun 08, 2012
Daniel Greenfeld Added autoclass to generic-editing views 6e50c43
Daniel Greenfeld corrected formatting to include proper section titles across generic …
…class based view refs
9effb21
Daniel Greenfeld Added the mro.py prettification script at root of docs. Demonstrated …
…the results of the script by updating the MRO statements for fundamental, display, and edit class based views
7b9467e
Marc Tamlyn Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs d13df05
Marc Tamlyn No more `"` and `'` mixing! 2ef458d
Daniel Greenfeld Added in the date class based generic views MRO listings c0e7e43
Move class based view topic docs into their own subtree, matching
the ref docs.
986f280
Merge remote branch 'pydanny/cbv-docs' into cbv-docs f6d1d2c
Daniel Greenfeld initial work on documenting the mixins 660dc51
Take the most vile example of combining generic CBV functionality
and present it as something not to do; explain a couple of other
approaches of doing the same things which have fewer problems.
fc2c08e
Merge remote branch 'pydanny/cbv-docs' into cbv-docs 92cb9f2
Update to new ref doc place for CBV mixins. 93102be
More explicit warnings, and light text fettling from pydanny. 6a0a067
Daniel Greenfeld Merge pull request #6 from jaylett/cbv-docs
Mixins galore.
2076df7
Daniel Greenfeld resolved merge conflict and also did a little cleanup on the mro script d75be87
Daniel Greenfeld Broke up the mixins reference in order to make it more human friendly…
…. The files went into the same directory as the CBV refs in order to keep nesting at a minimum.
20af74b
Link warning suitably. 8647a5a
More cross linking, and some more explanation, in generic editing
CBV topic.
950cbb9
Daniel Greenfeld Added note to Autodoc methods/attributes explaining that it's a work …
…in progress
be84676
Daniel Greenfeld Merge pull request #7 from jaylett/cbv-docs
Cbv docs
6aa1f54
Daniel Greenfeld Clarificaton that ProcessFormView is actually a mixin. 1a136cc
Daniel Greenfeld Corrected spelling issues, removed empty generic-date-based CBV topic…
… file, and other minor cleanups
e697822
Marc Tamlyn Merge branch 'cbv-docs' of git://github.com/pydanny/django into cbv-docs b342b7d
Marc Tamlyn Moderate language regarding diy views.
As requested by @pydanny.
175b6ce
Daniel Greenfeld Merge pull request #5 from mjtamlyn/cbv-docs
First run through improving the generic cbv topic.
bc40fc2
Daniel Greenfeld Merge remote-tracking branch 'upstream/master' into cbv-docs 728dc2c
Daniel Greenfeld Changed a TODO to a RST comment 9a37ed1
Kenneth Love Updates to the edit views' docstrings.
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
632b801
Kenneth Love Updates to the date views
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
efe4601
Kenneth Love Updates to the base views
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
1282938
Kenneth Love Updates to the detail views
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
ba0e4c5
Kenneth Love Updates to the list views
Signed-off-by: Kenneth Love <kenneth@gigantuan.net>
70b9b3a
Marc Tamlyn Remove refernces to ``urls.defaults``. b93208e
Marc Tamlyn Class-based not class based and other grammar. 87b5513
Marc Tamlyn Fix some weird sentences. d369ab4
Marc Tamlyn ContentMixin doesn't exist until 1.5 0348a41
Jun 09, 2012
Marc Tamlyn Merge pull request #8 from mjtamlyn/cbv-docs
MOAR
ce3314b
Marc Tamlyn Tidy up topic pages.
Remove broken refs, clarify a little text, fix and pep8 some code
examples.
4e970cc
Marc Tamlyn Delete old files. 5e92dff
Marc Tamlyn Fix a grammatical error. 000a178
Marc Tamlyn Remove autodoc. 54ea20f
Marc Tamlyn Merge remote-tracking branch 'kennethlove/fix/cbv-docs' into cbv-docs b0f1658
Marc Tamlyn Lots of small tweaks as suggested by @jezdez. 8aa4237
Jun 10, 2012
Marc Tamlyn Intersphinx to Python datetime docs. 08c5b01
Marc Tamlyn RST tidyup. 6c8db99
Something went wrong with that request. Please try again.