Skip to content
This repository
Browse code

Updating documentation

  • Loading branch information...
commit 3348d19b6698632e13e12bd18bf5a1820a7e0c9c 1 parent 0bfaa59
Charles Leifer authored October 18, 2012
4  docs/admin.rst
Source Rendered
@@ -120,7 +120,7 @@ the :py:meth:`~ModelAdmin.get_query` method:
120 120
 .. code-block:: python
121 121
 
122 122
     def get_query(self):
123  
-        return self.model.filter(user=g.user)
  123
+        return self.model.select().where(self.model.user == g.user)
124 124
 
125 125
 Now a user will only be able to see and edit their own messages.
126 126
 
@@ -255,7 +255,7 @@ Here's what the panel class looks like:
255 255
 
256 256
         def get_context(self):
257 257
             return {
258  
-                'note_list': Note.select().order_by(('created_date', 'desc')).paginate(1, 3)
  258
+                'note_list': Note.select().order_by(Note.created_date.desc()).limit(3)
259 259
             }
260 260
 
261 261
 When the admin dashboard is rendered (``/admin/``), all panels are rendered using
194  docs/api.rst
Source Rendered
@@ -189,9 +189,38 @@ Exposing Models with the ModelAdmin
189 189
             class EntryAdmin(ModelAdmin):
190 190
                 columns = ['title', 'pub_date', 'blog']
191 191
 
192  
-    .. py:attribute:: paginate_by
  192
+    .. py:attribute:: filter_exclude
193 193
 
194  
-        How many records to paginate by when viewing lists of models, defaults to 20.
  194
+        Exclude certain fields from being exposed as filters.  Related fields can
  195
+        be excluded using "__" notation, e.g. ``user__password``
  196
+
  197
+    .. py:attribute:: filter_fields
  198
+
  199
+        Only allow filtering on the given fields
  200
+
  201
+    .. py:attribute:: exclude
  202
+
  203
+        A list of field names to exclude from the "add" and "edit" forms
  204
+
  205
+    .. py:attribute:: fields
  206
+
  207
+        Only display the given fields on the "add" and "edit" form
  208
+
  209
+    .. py:attribute:: paginate_by = 20
  210
+
  211
+        Number of records to display on index pages
  212
+
  213
+    .. py:attribute:: filter_paginate_by = 15
  214
+
  215
+        Default pagination when filtering in a modal dialog
  216
+
  217
+    .. py:attribute:: delete_collect_objects = True
  218
+
  219
+        Collect and display a list of "dependencies" when deleting
  220
+
  221
+    .. py:attribute:: delete_recursive = True
  222
+
  223
+        Delete "dependencies" recursively
195 224
 
196 225
     .. py:method:: get_query()
197 226
 
@@ -216,7 +245,7 @@ Exposing Models with the ModelAdmin
216 245
                     # if they are not a superuser, only show them their own
217 246
                     # account in the admin
218 247
                     if not current_user.is_superuser:
219  
-                        return User.filter(id=current_user.id)
  248
+                        return User.select().where(User.id==current_user.id)
220 249
 
221 250
                     # otherwise, show them all users
222 251
                     return User.select()
@@ -255,12 +284,12 @@ Exposing Models with the ModelAdmin
255 284
 
256 285
     .. py:method:: get_filter_form()
257 286
 
258  
-        Provide a form for use when filtering the list of objects in the model admin's
259  
-        index view.  This form is slightly different in that it is tailored for use
  287
+        Provide a special form for use when filtering the list of objects in the model admin's
  288
+        index/export views.  This form is slightly different in that it is tailored for use
260 289
         when filtering the list of models.
261 290
 
262  
-        :rtype: A `wtf-peewee <http://github.com/coleifer/wtf-peewee>`_ Form subclass that
263  
-                will be used when filtering the list of objects in the index view.
  291
+        :rtype: A special Form instance (:py:class:`FilterForm`) that will be used 
  292
+                when filtering the list of objects in the index view.
264 293
 
265 294
     .. py:method:: save_model(instance, form, adding=False)
266 295
 
@@ -323,6 +352,20 @@ Exposing Models with the ModelAdmin
323 352
         Since urls are namespaced, this function provides an easy way to get
324 353
         full urls to views provided by this ModelAdmin
325 354
 
  355
+    .. py:method:: process_filters(query)
  356
+
  357
+        Applies any filters specified by the user to the given query, returning
  358
+        metadata about the filters.
  359
+
  360
+        Returns a 4-tuple containing:
  361
+
  362
+        * special ``Form`` instance containing fields for filtering
  363
+        * filtered query
  364
+        * a list containing the currently selected filters
  365
+        * a tree-structure containing the fields available for filtering (:py:class:`FieldTreeNode`)
  366
+
  367
+        :rtype: A tuple as described above
  368
+
326 369
 
327 370
 Extending admin functionality using AdminPanel
328 371
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -616,7 +659,7 @@ Database
616 659
 REST API
617 660
 --------
618 661
 
619  
-.. py:class:: RestAPI(app[, prefix='/api'[, default_auth=None]])
  662
+.. py:class:: RestAPI(app[, prefix='/api'[, default_auth=None[, name='api']]])
620 663
 
621 664
     The :py:class:`RestAPI` acts as a container for the various :py:class:`RestResource`
622 665
     objects.  By default it binds all resources to ``/api/<model-name>/``.  Much like
@@ -645,6 +688,7 @@ REST API
645 688
     :param app: flask application to bind API to
646 689
     :param prefix: url to serve REST API from
647 690
     :param default_auth: default :py:class:`Authentication` type to use with registered resources
  691
+    :param name: the name for the API blueprint
648 692
 
649 693
     .. py:method:: register(model[, provider=RestResource[, auth=None[, allowed_methods=None]]])
650 694
 
@@ -665,12 +709,15 @@ REST API
665 709
 RESTful Resources and their subclasses
666 710
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
667 711
 
668  
-.. py:class:: RestResource
  712
+.. py:class:: RestResource(rest_api, model, authentication[, allowed_methods=None])
669 713
 
670 714
     Class that determines how a peewee ``Model`` is exposed by the Rest API.  Provides
671 715
     a way of encapsulating model-specific configuration and behaviors.  Provided
672 716
     when registering a model with the :py:class:`RestAPI` instance (see :py:meth:`RestAPI.register`).
673 717
 
  718
+    Should not be instantiated directly in most cases. Instead should be "registered" with
  719
+    a ``RestAPI`` instance.
  720
+
674 721
     Example usage:
675 722
 
676 723
     .. code-block:: python
@@ -700,10 +747,58 @@ RESTful Resources and their subclasses
700 747
 
701 748
         A list or tuple of fields to **not** expose when serializing
702 749
 
703  
-    .. py:attribute:: ignore_filters = ('ordering', 'page', 'limit', 'key', 'secret',)
  750
+    .. py:attribute:: filter_exclude
  751
+
  752
+        A list of fields that **cannot** be used to filter API results
  753
+
  754
+    .. py:attribute:: filter_fields
  755
+
  756
+        A list of fields that can be used to filter the API results
  757
+
  758
+    .. py:attribute:: filter_recursive = True
  759
+
  760
+        Allow filtering on related resources
  761
+
  762
+    .. py:attribute:: include_resources
704 763
 
705  
-        A list or tuple of GET arguments to ignore when applying filters.  Generally
706  
-        these are special url arguments that have special meaning.
  764
+        A mapping of field name to resource class for handling of foreign-keys.
  765
+        When provided, foreign keys will be "nested".
  766
+
  767
+        .. code-block:: python
  768
+
  769
+            class UserResource(RestResource):
  770
+                exclude = ('password', 'email')
  771
+
  772
+            class MessageResource(RestResource):
  773
+                include_resources = {'user': UserResource} # 'user' is a foreign key field
  774
+
  775
+        .. code-block:: javascript
  776
+
  777
+            /* messages without "include_resources" */
  778
+            {
  779
+              "content": "flask and peewee, together at last!",
  780
+              "pub_date": "2011-09-16 18:36:15",
  781
+              "id": 1,
  782
+              "user": 2
  783
+            },
  784
+
  785
+            /* messages with "include_resources = {'user': UserResource} */
  786
+            {
  787
+              "content": "flask and peewee, together at last!",
  788
+              "pub_date": "2011-09-16 18:36:15",
  789
+              "id": 1,
  790
+              "user": {
  791
+                "username": "coleifer",
  792
+                "active": true,
  793
+                "join_date": "2011-09-16 18:35:56",
  794
+                "admin": false,
  795
+                "id": 2
  796
+              }
  797
+            }
  798
+            
  799
+    .. py:attribute:: delete_recursive = True
  800
+
  801
+        Recursively delete dependencies
707 802
 
708 803
     .. py:method:: get_query()
709 804
 
@@ -986,25 +1081,51 @@ Authenticating requests to the API
986 1081
 Utilities
987 1082
 ---------
988 1083
 
989  
-.. py:function:: get_object_or_404(query_or_model, **query)
  1084
+.. py:function:: get_object_or_404(query_or_model, *query)
990 1085
 
991  
-    Given any number of keyword arguments, retrieve a single instance of the
992  
-    ``query_or_model`` parameter or return a 404
  1086
+    Provides a handy way of getting an object or 404ing if not found, useful
  1087
+    for urls that match based on ID.
993 1088
 
994  
-    :param query_or_model: either a ``Model`` class or a ``SelectQuery``
995  
-    :param **query: any number of keyword arguments, e.g. ``id=1``
996  
-    :rtype: either a single model instance or raises a ``NotFound`` (404 response)
  1089
+    :param query_or_model: a query or model to filter using the given expressions
  1090
+    :param query: a list of query expressions
997 1091
 
998  
-.. py:function:: object_list(template_name, qr[, var_name='object_list'[, paginate_by=20[, **kwargs]]])
  1092
+    .. code-block:: python
  1093
+    
  1094
+        @app.route('/blog/<title>/')
  1095
+        def blog_detail(title):
  1096
+            blog = get_object_or_404(Blog.select().where(Blog.active==True), Blog.title==title)
  1097
+            return render_template('blog/detail.html', blog=blog)
999 1098
 
1000  
-    Returns a rendered template, passing in a paginated version of the query.
  1099
+.. py:function:: object_list(template_name, qr[, var_name='object_list'[, **kwargs]])
1001 1100
 
1002  
-    :param template_name: a string representation of a path to a template
1003  
-    :param qr: a ``SelectQuery``
1004  
-    :param var_name: context variable name to use when rendering the template
1005  
-    :param paginate_by: number of results per page, defaults to 20
1006  
-    :param **kwargs: any arbitrary keyword arguments to pass to the template during rendering
1007  
-    :rtype: rendered ``Response``
  1101
+    Wraps the given query and handles pagination automatically. Pagination defaults to ``20``
  1102
+    but can be changed by passing in ``paginate_by=XX``.
  1103
+
  1104
+    :param template_name: template to render
  1105
+    :param qr: a select query
  1106
+    :param var_name: the template variable name to use for the paginated query
  1107
+    :param kwargs: arbitrary context to pass in to the template
  1108
+
  1109
+    .. code-block:: python
  1110
+    
  1111
+        @app.route('/blog/')
  1112
+        def blog_list():
  1113
+            active = Blog.select().where(Blog.active==True)
  1114
+            return object_list('blog/index.html', active)
  1115
+    
  1116
+    .. code-block:: html
  1117
+    
  1118
+        <!-- template -->
  1119
+        {% for blog in object_list %}
  1120
+          {# render the blog here #}
  1121
+        {% endfor %}
  1122
+        
  1123
+        {% if page > 1 %}
  1124
+          <a href="./?page={{ page - 1 }}">Prev</a>
  1125
+        {% endif %}
  1126
+        {% if page < pagination.get_pages() %}
  1127
+          <a href="./?page={{ page + 1 }}">Next</a>
  1128
+        {% endif %}
1008 1129
 
1009 1130
 .. py:function:: get_next()
1010 1131
 
@@ -1017,18 +1138,27 @@ Utilities
1017 1138
     :param s: any string to be slugified
1018 1139
     :rtype: url-friendly version of string ``s``
1019 1140
 
1020  
-.. py:class:: PaginatedQuery
  1141
+.. py:class:: PaginatedQuery(query_or_model, paginate_by)
1021 1142
 
1022  
-    Wraps a ``SelectQuery`` with helpers for paginating.
  1143
+    A wrapper around a query (or model class) that handles pagination.
1023 1144
 
1024 1145
     .. py:attribute:: page_var = 'page'
1025 1146
 
1026  
-        GET argument to use for determining request page
  1147
+        The URL variable used to store the current page
1027 1148
 
1028  
-    .. py:method:: __init__(query_or_model, paginate_by)
  1149
+    Example:
1029 1150
 
1030  
-        :param query_or_model: either a ``Model`` class or a ``SelectQuery``
1031  
-        :param paginate_by: number of results to return per-page
  1151
+    .. code-block:: python
  1152
+    
  1153
+        query = Blog.select().where(Blog.active==True)
  1154
+        pq = PaginatedQuery(query)
  1155
+        
  1156
+        # assume url was /?page=3
  1157
+        obj_list = pq.get_list()  # returns 3rd page of results
  1158
+        
  1159
+        pq.get_page() # returns "3"
  1160
+        
  1161
+        pq.get_pages() # returns total objects / objects-per-page
1032 1162
 
1033 1163
     .. py:method:: get_list()
1034 1164
 
33  docs/utils.rst
Source Rendered
@@ -12,20 +12,26 @@ Getting objects
12 12
 
13 13
 :py:func:`get_object_or_404`
14 14
 
  15
+    Provides a handy way of getting an object or 404ing if not found, useful
  16
+    for urls that match based on ID.
  17
+
15 18
     .. code-block:: python
16 19
     
17 20
         @app.route('/blog/<title>/')
18 21
         def blog_detail(title):
19  
-            blog = get_object_or_404(Blog.select().where(active=True), title=title)
  22
+            blog = get_object_or_404(Blog.select().where(Blog.active==True), Blog.title==title)
20 23
             return render_template('blog/detail.html', blog=blog)
21 24
 
22 25
 :py:func:`object_list`
23 26
 
  27
+    Wraps the given query and handles pagination automatically. Pagination defaults to ``20``
  28
+    but can be changed by passing in ``paginate_by=XX``.
  29
+
24 30
     .. code-block:: python
25 31
     
26 32
         @app.route('/blog/')
27 33
         def blog_list():
28  
-            active = Blog.select().where(active=True)
  34
+            active = Blog.select().where(Blog.active==True)
29 35
             return object_list('blog/index.html', active)
30 36
     
31 37
     .. code-block:: html
@@ -44,9 +50,13 @@ Getting objects
44 50
 
45 51
 :py:class:`PaginatedQuery`
46 52
 
  53
+    A wrapper around a query (or model class) that handles pagination.
  54
+
  55
+    Example:
  56
+
47 57
     .. code-block:: python
48 58
     
49  
-        query = Blog.select().where(active=True)
  59
+        query = Blog.select().where(Blog.active==True)
50 60
         pq = PaginatedQuery(query)
51 61
         
52 62
         # assume url was /?page=3
@@ -61,7 +71,10 @@ Misc
61 71
 ----
62 72
 
63 73
 
64  
-:py:func:`slugify`
  74
+.. py:function:: slugify(string)
  75
+
  76
+    Convert a string into something suitable for use as part of a URL,
  77
+    e.g. "This is a url" becomes "this-is-a-url"
65 78
 
66 79
     .. code-block:: python
67 80
     
@@ -72,6 +85,14 @@ Misc
72 85
             title = CharField()
73 86
             slug = CharField()
74 87
             
75  
-            def save(self):
  88
+            def save(self, *args, **kwargs):
76 89
                 self.slug = slugify(self.title)
77  
-                super(Blog, self).save()
  90
+                super(Blog, self).save(*args, **kwargs)
  91
+
  92
+.. py:function:: make_password(raw_password)
  93
+
  94
+    Create a salted hash for the given plain-text password
  95
+
  96
+.. py:function:: check_password(raw_password, enc_password)
  97
+
  98
+    Compare a plain-text password against a salted/hashed password

0 notes on commit 3348d19

Please sign in to comment.
Something went wrong with that request. Please try again.