Skip to content

F
flask-admin
Commit fb818885 authored by Serge S. Koval's avatar Serge S. Koval
Browse files
Options

Merge pull request #158 from ctoth/master 

Minor English cleanup in docstrings
parents 0f0a6810 208adeab
Hide whitespace changes
Inline Side-by-side
Showing with 67 additions and 68 deletions
flask_admin/base.py
View file @ fb818885
......@@ -107,7 +107,7 @@ class BaseView(object):
arguments you want to pass to the template and call parent view.
These arguments are local for this request and will be discarded
in next request.
in the next request.
Any value passed through ``_template_args`` will override whatever
parent view function passed to the template.
......@@ -133,17 +133,17 @@ class BaseView(object):
Constructor.
:param name:
Name of this view. If not provided, will be defaulted to the class name.
Name of this view. If not provided, will default to the class name.
:param category:
View category. If not provided, will be shown as a top-level menu item. Otherwise, will
View category. If not provided, this view will be shown as a top-level menu item. Otherwise, it will
be in a submenu.
:param endpoint:
Base endpoint name for the view. For example, if there's view method called "index" and
endpoint was set to "myadmin", you can use `url_for('myadmin.index')` to get URL to the
view method. By default, equals to the class name in lower case.
Base endpoint name for the view. For example, if there's a view method called "index" and
endpoint is set to "myadmin", you can use `url_for('myadmin.index')` to get the URL to the
view method. Defaults to the class name in lower case.
:param url:
Base URL. If provided, affects how URLs are generated. For example, if url parameter
equals to "test", resulting URL will look like "/admin/test/". If not provided, will
Base URL. If provided, affects how URLs are generated. For example, if the url parameter
is "test", the resulting URL will look like "/admin/test/". If not provided, will
use endpoint as a base url. However, if URL starts with '/', absolute path is assumed
and '/admin/' prefix won't be applied.
"""
......@@ -230,7 +230,7 @@ class BaseView(object):
def _prettify_name(self, name):
"""
Prettify class name by splitting name by capital characters. So, 'MySuperClass' will look like 'My Super Class'
Prettify a class name by splitting the name on capitalized characters. So, 'MySuperClass' becomes 'My Super Class'
:param name:
String to prettify
......@@ -241,10 +241,10 @@ class BaseView(object):
"""
Override this method to add permission checks.
Flask-Admin does not make any assumptions about authentication system used in your application, so it is
up for you to implement it.
Flask-Admin does not make any assumptions about the authentication system used in your application, so it is
up to you to implement it.
By default, it will allow access for the everyone.
By default, it will allow access for everyone.
"""
return True
......@@ -252,7 +252,7 @@ class BaseView(object):
"""
This method will be executed before calling any view method.
By default, it will check if admin class is accessible and if it is not - will
By default, it will check if the admin class is accessible and if it is not it will
throw HTTP 404 error.
:param name:
......@@ -278,10 +278,10 @@ class AdminIndexView(BaseView):
admin = Admin(index_view=MyHomeView())
Default values for the index page are following:
Default values for the index page are:
* If name is not provided, 'Home' will be used.
* If endpoint is not provided, will use ``admin``
* If a name is not provided, 'Home' will be used.
* If an endpoint is not provided, will default to ``admin``
* Default URL route is ``/admin``.
* Automatically associates with static folder.
* Default template is ``admin/index.html``
......@@ -351,7 +351,7 @@ class MenuItem(object):
class Admin(object):
"""
Collection of the views. Also manages menu structure.
Collection of the admin views. Also manages menu structure.
"""
def __init__(self, app=None, name=None,
url=None, subdomain=None,
......@@ -364,19 +364,19 @@ class Admin(object):
:param app:
Flask application object
:param name:
Application name. Will be displayed in main menu and as a page title. If not provided, defaulted to "Admin"
Application name. Will be displayed in the main menu and as a page title. Defaults to "Admin"
:param url:
Base URL
:param subdomain:
Subdomain to use
:param index_view:
Home page view to use. If not provided, will use `AdminIndexView`.
Home page view to use. Defaults to `AdminIndexView`.
:param translations_path:
Location of the translation message catalogs. By default will use translations
shipped with the Flask-Admin.
Location of the translation message catalogs. By default will use the translations
shipped with Flask-Admin.
:param endpoint:
Base endpoint name for index view. If you use multiple instances of `Admin` class with
one Flask application, you have to set unique endpoint name for each instance.
Base endpoint name for index view. If you use multiple instances of the `Admin` class with
a single Flask application, you have to set a unique endpoint name for each instance.
"""
self.app = app
......@@ -407,7 +407,7 @@ class Admin(object):
def add_view(self, view):
"""
Add view to the collection.
Add a view to the collection.
:param view:
View to add.
......@@ -422,7 +422,7 @@ class Admin(object):
def locale_selector(self, f):
"""
Installs locale selector for current ``Admin`` instance.
Installs a locale selector for the current ``Admin`` instance.
Example::
......@@ -453,7 +453,7 @@ class Admin(object):
def _add_view_to_menu(self, view):
"""
Add view to the menu tree
Add a view to the menu tree
:param view:
View to add
......@@ -472,7 +472,7 @@ class Admin(object):
def init_app(self, app):
"""
Register all views with Flask application.
Register all views with the Flask application.
:param app:
Flask application instance
......@@ -506,6 +506,6 @@ class Admin(object):
def menu(self):
"""
Return menu hierarchy.
Return the menu hierarchy.
"""
return self._menu
flask_admin/model/base.py
View file @ fb818885
......@@ -14,17 +14,17 @@ class BaseModelView(BaseView, ActionsMixin):
"""
Base model view.
View does not make any assumptions on how models are stored or managed, but expects following:
This view does not make any assumptions on how models are stored or managed, but expects the following:
1. Model is an object
2. Model contains properties
3. Each model contains attribute which uniquely identifies it (i.e. primary key for database model)
4. You can get list of sorted models with pagination applied from a data source
1. The provided model is an object
2. The model contains properties
3. Each model contains an attribute which uniquely identifies it (i.e. a primary key for a database model)
4. It is possible to retrieve a list of sorted models with pagination applied from a data source
5. You can get one model by its identifier from the data source
Essentially, if you want to support new data store, all you have to do:
Essentially, if you want to support a new data store, all you have to do is:
1. Derive from `BaseModelView` class
1. Derive from the `BaseModelView` class
2. Implement various data-related methods (`get_list`, `get_one`, `create_model`, etc)
3. Implement automatic form generation from the model representation (`scaffold_form`)
"""
......@@ -81,7 +81,7 @@ class BaseModelView(BaseView, ActionsMixin):
class MyModelView(BaseModelView):
column_formatters = dict(price=lambda c, m, p: m.price*2)
Callback function has following prototype::
The Callback function has the prototype::
def formatter(context, model, name):
# context is instance of jinja2.runtime.Context
......@@ -92,19 +92,19 @@ class BaseModelView(BaseView, ActionsMixin):
column_type_formatters = ObsoleteAttr('column_type_formatters', 'list_type_formatters', None)
"""
Dictionary of value type formatters to be used in list view.
Dictionary of value type formatters to be used in the list view.
By default, two types are formatted:
1. ``None`` will be displayed as empty string
2. ``bool`` will be displayed as check if it is ``True``
1. ``None`` will be displayed as an empty string
2. ``bool`` will be displayed as a checkmark if it is ``True``
If you don't like default behavior and don't want any type formatters
applied, just override this property with empty dictionary::
If you don't like the default behavior and don't want any type formatters
applied, just override this property with an empty dictionary::
class MyModelView(BaseModelView):
column_type_formatters = dict()
If you want to display `NULL` instead of empty string, you can do
If you want to display `NULL` instead of an empty string, you can do
something like this::
from flask.ext.admin import typefmt
......@@ -155,13 +155,13 @@ class BaseModelView(BaseView, ActionsMixin):
column_sortable_list = ('name', 'last_name')
If you want to explicitly specify field/column to be used while
sorting, you can use tuple::
sorting, you can use a tuple::
class MyModelView(BaseModelView):
column_sortable_list = ('name', ('user', 'user.username'))
When using SQLAlchemy models, model attributes can be used instead
of the string::
of strings::
class MyModelView(BaseModelView):
column_sortable_list = ('name', ('user', User.username))
......@@ -171,9 +171,9 @@ class BaseModelView(BaseView, ActionsMixin):
'searchable_columns',
None)
"""
Collection of the searchable columns. It is assumed that only
text-only fields are searchable, but it is up for a model
implementation to make decision.
A collection of the searchable columns. It is assumed that only
text-only fields are searchable, but it is up to the model
implementation to decide.
Example::
......@@ -197,7 +197,7 @@ class BaseModelView(BaseView, ActionsMixin):
'list_display_pk',
False)
"""
Controls if primary key should be displayed in list view.
Controls if the primary key should be displayed in the list view.
"""
form = None
......@@ -274,7 +274,7 @@ class BaseModelView(BaseView, ActionsMixin):
# Various settings
page_size = 20
"""
Default page size.
Default page size for pagination.
"""
def __init__(self, model,
......@@ -285,11 +285,11 @@ class BaseModelView(BaseView, ActionsMixin):
:param model:
Model class
:param name:
View name. If not provided, will use model class name
View name. If not provided, will use the model class name
:param category:
View category
:param endpoint:
Base endpoint. If not provided, will use model name + 'view'.
Base endpoint. If not provided, will use the model name + 'view'.
For example if model name was 'User', endpoint will be
'userview'
:param url:
......@@ -383,7 +383,7 @@ class BaseModelView(BaseView, ActionsMixin):
def get_column_name(self, field):
"""
Return human-readable column name.
Return a human-readable column name.
:param field:
Model field name.
......@@ -395,9 +395,9 @@ class BaseModelView(BaseView, ActionsMixin):
def get_list_columns(self):
"""
Returns list of the model field names. If `column_list` was
Returns a list of the model field names. If `column_list` was
set, returns it. Otherwise calls `scaffold_list_columns`
to generate list from the model.
to generate the list from the model.
"""
columns = self.column_list
......@@ -415,14 +415,14 @@ class BaseModelView(BaseView, ActionsMixin):
Returns dictionary of sortable columns. Must be implemented in
the child class.
Expected return format is dictionary, where key is field name and
value is property name.
Expected return format is a dictionary, where keys are field names and
values are property names.
"""
raise NotImplemented('Please implement scaffold_sortable_columns method')
def get_sortable_columns(self):
"""
Returns dictionary of the sortable columns. Key is a model
Returns a dictionary of the sortable columns. Key is a model
field name and value is sort column (for example - attribute).
If `column_sortable_list` is set, will use it. Otherwise, will call
......@@ -459,10 +459,10 @@ class BaseModelView(BaseView, ActionsMixin):
def is_valid_filter(self, filter):
"""
Verify that provided filter object is valid.
Verify that the provided filter object is valid.
Override in model backend implementation to verify if
provided filter type is allowed.
the provided filter type is allowed.
:param filter:
Filter object to verify.
......@@ -471,7 +471,7 @@ class BaseModelView(BaseView, ActionsMixin):
def get_filters(self):
"""
Return list of filter objects.
Return a list of filter objects.
If your model backend implementation does not support filters,
override this method and return `None`.
......@@ -568,10 +568,9 @@ class BaseModelView(BaseView, ActionsMixin):
# Database-related API
def get_list(self, page, sort_field, sort_desc, search, filters):
"""
Return list of models from the data source with applied pagination
and sorting.
Must be implemented in child class.
Return a paginated and sorted list of models from the data source.
Must be implemented in the child class.
:param page:
Page number, 0 based. Can be set to None if it is first page.
......@@ -601,7 +600,7 @@ class BaseModelView(BaseView, ActionsMixin):
# Model handlers
def on_model_change(self, form, model):
"""
Allow to do some actions after a model was created or updated.
Perform some actions after a model is created or updated.
Called from create_model and update_model in the same transaction
(if it has any meaning for a store backend).
......@@ -612,7 +611,7 @@ class BaseModelView(BaseView, ActionsMixin):
def on_model_delete(self, model):
"""
Allow to do some actions before a model will be deleted.
Perform some actions before a model is deleted.
Called from delete_model in the same transaction
(if it has any meaning for a store backend).
......@@ -753,7 +752,7 @@ class BaseModelView(BaseView, ActionsMixin):
Override this method to allow or disallow actions based
on some condition.
Default implementation only checks if particular action
The default implementation only checks if the particular action
is not in `action_disallowed_list`.
"""
return name not in self.action_disallowed_list
......@@ -761,7 +760,7 @@ class BaseModelView(BaseView, ActionsMixin):
@contextfunction
def get_list_value(self, context, model, name):
"""
Returns value to be displayed in list view
Returns the value to be displayed in the list view
:param context:
:py:class:`jinja2.runtime.Context`
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment