p15693087
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Refs #27656 -- Updated django.views docstring verbs according to PEP 257.

This commit is contained in:
Anton Samarchyan 2017-01-24 15:36:07 -05:00 committed by Tim Graham
parent b23d264046
commit 711123e1cd
11 changed files with 164 additions and 343 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
django/views/debug.py
View File

@ -24,10 +24,11 @@ CLEANSED_SUBSTITUTE = '********************'
class CallableSettingWrapper:
""" Object to wrap callable appearing in settings
"""
Object to wrap callable appearing in settings.
* Not to call in the debug page (#21345).
* Not to break the debug page if the callable forbidding to set attributes (#23070).
* Not to break the debug page if the callable forbidding to set attributes
(#23070).
"""
def __init__(self, callable_setting):
self._wrapped = callable_setting
@ -37,10 +38,9 @@ class CallableSettingWrapper:
def cleanse_setting(key, value):
"""Cleanse an individual setting key/value of sensitive content.
If the value is a dictionary, recursively cleanse the keys in
that dictionary.
"""
Cleanse an individual setting key/value of sensitive content. If the value
is a dictionary, recursively cleanse the keys in that dictionary.
"""
try:
if HIDDEN_SETTINGS.search(key):
@ -62,7 +62,10 @@ def cleanse_setting(key, value):
def get_safe_settings():
"Returns a dictionary of the settings module, with sensitive settings blurred out."
"""
Return a dictionary of the settings module with values of sensitive
settings replaced with stars (*********).
"""
settings_dict = {}
for k in dir(settings):
if k.isupper():
@ -128,7 +131,7 @@ class SafeExceptionReporterFilter(ExceptionReporterFilter):
def get_cleansed_multivaluedict(self, request, multivaluedict):
"""
Replaces the keys in a MultiValueDict marked as sensitive with stars.
Replace the keys in a MultiValueDict marked as sensitive with stars.
This mitigates leaking sensitive POST parameters if something like
request.POST['nonexistent_key'] throws an exception (#21098).
"""
@ -142,7 +145,7 @@ class SafeExceptionReporterFilter(ExceptionReporterFilter):
def get_post_parameters(self, request):
"""
Replaces the values of POST parameters marked as sensitive with
Replace the values of POST parameters marked as sensitive with
stars (*********).
"""
if request is None:
@ -181,7 +184,7 @@ class SafeExceptionReporterFilter(ExceptionReporterFilter):
def get_traceback_frame_variables(self, request, tb_frame):
"""
Replaces the values of variables marked as sensitive with
Replace the values of variables marked as sensitive with
stars (*********).
"""
# Loop through the frame's callers to see if the sensitive_variables
@ -231,9 +234,7 @@ class SafeExceptionReporterFilter(ExceptionReporterFilter):
class ExceptionReporter:
"""
A class to organize and coordinate reporting on exceptions.
"""
"""Organize and coordinate reporting on exceptions."""
def __init__(self, request, exc_type, exc_value, tb, is_email=False):
self.request = request
self.filter = get_exception_reporter_filter(self.request)
@ -318,21 +319,21 @@ class ExceptionReporter:
return c
def get_traceback_html(self):
"Return HTML version of debug 500 HTTP error page."
"""Return HTML version of debug 500 HTTP error page."""
t = DEBUG_ENGINE.from_string(TECHNICAL_500_TEMPLATE)
c = Context(self.get_traceback_data(), use_l10n=False)
return t.render(c)
def get_traceback_text(self):
"Return plain text version of debug 500 HTTP error page."
"""Return plain text version of debug 500 HTTP error page."""
t = DEBUG_ENGINE.from_string(TECHNICAL_500_TEXT_TEMPLATE)
c = Context(self.get_traceback_data(), autoescape=False, use_l10n=False)
return t.render(c)
def _get_lines_from_file(self, filename, lineno, context_lines, loader=None, module_name=None):
"""
Returns context_lines before and after lineno from file.
Returns (pre_context_lineno, pre_context, context_line, post_context).
Return context_lines before and after lineno from file.
Return (pre_context_lineno, pre_context, context_line, post_context).
"""
source = None
if loader is not None and hasattr(loader, "get_source"):
@ -439,7 +440,7 @@ class ExceptionReporter:
def technical_404_response(request, exception):
"Create a technical 404 error response. The exception should be the Http404."
"""Create a technical 404 error response. `exception` is the Http404."""
try:
error_url = exception.args[0]['path']
except (IndexError, TypeError, KeyError):
@ -494,7 +495,7 @@ def technical_404_response(request, exception):
def default_urlconf(request):
"Create an empty URLconf 404 error response."
"""Create an empty URLconf 404 error response."""
t = DEBUG_ENGINE.from_string(DEFAULT_URLCONF_TEMPLATE)
c = Context({
"title": _("Welcome to Django"),

3
django/views/decorators/cache.py
View File

@ -37,8 +37,7 @@ def cache_control(**kwargs):
def never_cache(view_func):
"""
Decorator that adds headers to a response so that it will
never be cached.
Decorator that adds headers to a response so that it will never be cached.
"""
@wraps(view_func)
def _wrapped_view_func(request, *args, **kwargs):

18
django/views/decorators/clickjacking.py
View File

@ -3,11 +3,9 @@ from functools import wraps
def xframe_options_deny(view_func):
"""
Modifies a view function so its response has the X-Frame-Options HTTP
Modify a view function so its response has the X-Frame-Options HTTP
header set to 'DENY' as long as the response doesn't already have that
header set.
e.g.
header set. Usage:
@xframe_options_deny
def some_view(request):
@ -23,11 +21,9 @@ def xframe_options_deny(view_func):
def xframe_options_sameorigin(view_func):
"""
Modifies a view function so its response has the X-Frame-Options HTTP
Modify a view function so its response has the X-Frame-Options HTTP
header set to 'SAMEORIGIN' as long as the response doesn't already have
that header set.
e.g.
that header set. Usage:
@xframe_options_sameorigin
def some_view(request):
@ -43,10 +39,8 @@ def xframe_options_sameorigin(view_func):
def xframe_options_exempt(view_func):
"""
Modifies a view function by setting a response variable that instructs
XFrameOptionsMiddleware to NOT set the X-Frame-Options HTTP header.
e.g.
Modify a view function by setting a response variable that instructs
XFrameOptionsMiddleware to NOT set the X-Frame-Options HTTP header. Usage:
@xframe_options_exempt
def some_view(request):

14
django/views/decorators/csrf.py
View File

@ -13,8 +13,7 @@ using the decorator multiple times, is harmless and efficient.
class _EnsureCsrfToken(CsrfViewMiddleware):
# We need this to behave just like the CsrfViewMiddleware, but not reject
# requests or log warnings.
# Behave like CsrfViewMiddleware but don't reject requests or log warnings.
def _reject(self, request, reason):
return None
@ -34,7 +33,7 @@ class _EnsureCsrfCookie(CsrfViewMiddleware):
def process_view(self, request, callback, callback_args, callback_kwargs):
retval = super().process_view(request, callback, callback_args, callback_kwargs)
# Forces process_response to send the cookie
# Force process_response to send the cookie
get_token(request)
return retval
@ -48,12 +47,9 @@ uses the csrf_token template tag, or the CsrfViewMiddleware is used.
def csrf_exempt(view_func):
"""
Marks a view function as being exempt from the CSRF view protection.
"""
# We could just do view_func.csrf_exempt = True, but decorators
# are nicer if they don't have side-effects, so we return a new
# function.
"""Mark a view function as being exempt from the CSRF view protection."""
# view_func.csrf_exempt = True would also work, but decorators are nicer
# if they don't have side effects, so return a new function.
def wrapped_view(*args, **kwargs):
return view_func(*args, **kwargs)
wrapped_view.csrf_exempt = True

16
django/views/decorators/debug.py
View File

@ -5,11 +5,11 @@ from django.http import HttpRequest
def sensitive_variables(*variables):
"""
Indicates which variables used in the decorated function are sensitive, so
Indicate which variables used in the decorated function are sensitive so
that those variables can later be treated in a special way, for example
by hiding them when logging unhandled exceptions.
Two forms are accepted:
Accept two forms:
* with specified variable names:
@ -19,8 +19,8 @@ def sensitive_variables(*variables):
credit_card = user.credit_card_number
...
* without any specified variable names, in which case it is assumed that
all variables are considered sensitive:
* without any specified variable names, in which case consider all
variables are sensitive:
@sensitive_variables()
def my_function()
@ -40,11 +40,11 @@ def sensitive_variables(*variables):
def sensitive_post_parameters(*parameters):
"""
Indicates which POST parameters used in the decorated view are sensitive,
Indicate which POST parameters used in the decorated view are sensitive,
so that those parameters can later be treated in a special way, for example
by hiding them when logging unhandled exceptions.
Two forms are accepted:
Accept two forms:
* with specified parameters:
@ -54,8 +54,8 @@ def sensitive_post_parameters(*parameters):
cc = request.POST['credit_card']
...
* without any specified parameters, in which case it is assumed that
all parameters are considered sensitive:
* without any specified parameters, in which case consider all
variables are sensitive:
@sensitive_post_parameters()
def my_view(request)

38
django/views/generic/base.py
View File

@ -16,7 +16,7 @@ logger = logging.getLogger('django.request')
class ContextMixin:
"""
A default context mixin that passes the keyword arguments received by
get_context_data as the template context.
get_context_data() as the template context.
"""
def get_context_data(self, **kwargs):
@ -45,9 +45,7 @@ class View:
@classonlymethod
def as_view(cls, **initkwargs):
"""
Main entry point for a request-response process.
"""
"""Main entry point for a request-response process."""
for key in initkwargs:
if key in cls.http_method_names:
raise TypeError("You tried to pass in the %s method name as a "
@ -95,9 +93,7 @@ class View:
return HttpResponseNotAllowed(self._allowed_methods())
def options(self, request, *args, **kwargs):
"""
Handles responding to requests for the OPTIONS HTTP verb.
"""
"""Handle responding to requests for the OPTIONS HTTP verb."""
response = HttpResponse()
response['Allow'] = ', '.join(self._allowed_methods())
response['Content-Length'] = '0'
@ -108,9 +104,7 @@ class View:
class TemplateResponseMixin:
"""
A mixin that can be used to render a template.
"""
"""A mixin that can be used to render a template."""
template_name = None
template_engine = None
response_class = TemplateResponse
@ -118,11 +112,10 @@ class TemplateResponseMixin:
def render_to_response(self, context, **response_kwargs):
"""
Returns a response, using the `response_class` for this
view, with a template rendered with the given context.
Return a response, using the `response_class` for this view, with a
template rendered with the given context.
If any keyword arguments are provided, they will be
passed to the constructor of the response class.
Pass response_kwargs to the constructor of the response class.
"""
response_kwargs.setdefault('content_type', self.content_type)
return self.response_class(
@ -135,8 +128,8 @@ class TemplateResponseMixin:
def get_template_names(self):
"""
Returns a list of template names to be used for the request. Must return
a list. May not be called if render_to_response is overridden.
Return a list of template names to be used for the request. Must return
a list. May not be called if render_to_response() is overridden.
"""
if self.template_name is None:
raise ImproperlyConfigured(
@ -148,8 +141,7 @@ class TemplateResponseMixin:
class TemplateView(TemplateResponseMixin, ContextMixin, View):
"""
A view that renders a template. This view will also pass into the context
any keyword arguments passed by the URLconf.
Render a template. Pass keyword arguments from the URLconf to the context.
"""
def get(self, request, *args, **kwargs):
context = self.get_context_data(**kwargs)
@ -157,9 +149,7 @@ class TemplateView(TemplateResponseMixin, ContextMixin, View):
class RedirectView(View):
"""
A view that provides a redirect on any GET request.
"""
"""Provide a redirect on any GET request."""
permanent = False
url = None
pattern_name = None
@ -167,9 +157,9 @@ class RedirectView(View):
def get_redirect_url(self, *args, **kwargs):
"""
Return the URL redirect to. Keyword arguments from the
URL pattern match generating the redirect request
are provided as kwargs to this method.
Return the URL redirect to. Keyword arguments from the URL pattern
match generating the redirect request are provided as kwargs to this
method.
"""
if self.url:
url = self.url % kwargs

193
django/views/generic/dates.py
View File

@ -18,9 +18,7 @@ from django.views.generic.list import (
class YearMixin:
"""
Mixin for views manipulating year-based data.
"""
"""Mixin for views manipulating year-based data."""
year_format = '%Y'
year = None
@ -32,9 +30,7 @@ class YearMixin:
return self.year_format
def get_year(self):
"""
Return the year for which this view should display data.
"""
"""Return the year for which this view should display data."""
year = self.year
if year is None:
try:
@ -47,15 +43,11 @@ class YearMixin:
return year
def get_next_year(self, date):
"""
Get the next valid year.
"""
"""Get the next valid year."""
return _get_next_prev(self, date, is_previous=False, period='year')
def get_previous_year(self, date):
"""
Get the previous valid year.
"""
"""Get the previous valid year."""
return _get_next_prev(self, date, is_previous=True, period='year')
def _get_next_year(self, date):
@ -67,16 +59,12 @@ class YearMixin:
return date.replace(year=date.year + 1, month=1, day=1)
def _get_current_year(self, date):
"""
Return the start date of the current interval.
"""
"""Return the start date of the current interval."""
return date.replace(month=1, day=1)
class MonthMixin:
"""
Mixin for views manipulating month-based data.
"""
"""Mixin for views manipulating month-based data."""
month_format = '%b'
month = None
@ -88,9 +76,7 @@ class MonthMixin:
return self.month_format
def get_month(self):
"""
Return the month for which this view should display data.
"""
"""Return the month for which this view should display data."""
month = self.month
if month is None:
try:
@ -103,15 +89,11 @@ class MonthMixin:
return month
def get_next_month(self, date):
"""
Get the next valid month.
"""
"""Get the next valid month."""
return _get_next_prev(self, date, is_previous=False, period='month')
def get_previous_month(self, date):
"""
Get the previous valid month.
"""
"""Get the previous valid month."""
return _get_next_prev(self, date, is_previous=True, period='month')
def _get_next_month(self, date):
@ -126,16 +108,12 @@ class MonthMixin:
return date.replace(month=date.month + 1, day=1)
def _get_current_month(self, date):
"""
Return the start date of the previous interval.
"""
"""Return the start date of the previous interval."""
return date.replace(day=1)
class DayMixin:
"""
Mixin for views manipulating day-based data.
"""
"""Mixin for views manipulating day-based data."""
day_format = '%d'
day = None
@ -147,9 +125,7 @@ class DayMixin:
return self.day_format
def get_day(self):
"""
Return the day for which this view should display data.
"""
"""Return the day for which this view should display data."""
day = self.day
if day is None:
try:
@ -162,15 +138,11 @@ class DayMixin:
return day
def get_next_day(self, date):
"""
Get the next valid day.
"""
"""Get the next valid day."""
return _get_next_prev(self, date, is_previous=False, period='day')
def get_previous_day(self, date):
"""
Get the previous valid day.
"""
"""Get the previous valid day."""
return _get_next_prev(self, date, is_previous=True, period='day')
def _get_next_day(self, date):
@ -182,16 +154,12 @@ class DayMixin:
return date + datetime.timedelta(days=1)
def _get_current_day(self, date):
"""
Return the start date of the current interval.
"""
"""Return the start date of the current interval."""
return date
class WeekMixin:
"""
Mixin for views manipulating week-based data.
"""
"""Mixin for views manipulating week-based data."""
week_format = '%U'
week = None
@ -203,9 +171,7 @@ class WeekMixin:
return self.week_format
def get_week(self):
"""
Return the week for which this view should display data
"""
"""Return the week for which this view should display data."""
week = self.week
if week is None:
try:
@ -218,15 +184,11 @@ class WeekMixin:
return week
def get_next_week(self, date):
"""
Get the next valid week.
"""
"""Get the next valid week."""
return _get_next_prev(self, date, is_previous=False, period='week')
def get_previous_week(self, date):
"""
Get the previous valid week.
"""
"""Get the previous valid week."""
return _get_next_prev(self, date, is_previous=True, period='week')
def _get_next_week(self, date):
@ -238,9 +200,7 @@ class WeekMixin:
return date + datetime.timedelta(days=7 - self._get_weekday(date))
def _get_current_week(self, date):
"""
Return the start date of the current interval.
"""
"""Return the start date of the current interval."""
return date - datetime.timedelta(self._get_weekday(date))
def _get_weekday(self, date):
@ -259,23 +219,19 @@ class WeekMixin:
class DateMixin:
"""
Mixin class for views manipulating date-based data.
"""
"""Mixin class for views manipulating date-based data."""
date_field = None
allow_future = False
def get_date_field(self):
"""
Get the name of the date field to be used to filter by.
"""
"""Get the name of the date field to be used to filter by."""
if self.date_field is None:
raise ImproperlyConfigured("%s.date_field is required." % self.__class__.__name__)
return self.date_field
def get_allow_future(self):
"""
Returns `True` if the view should be allowed to display objects from
Return `True` if the view should be allowed to display objects from
the future.
"""
return self.allow_future
@ -327,9 +283,7 @@ class DateMixin:
class BaseDateListView(MultipleObjectMixin, DateMixin, View):
"""
Abstract base class for date-based views displaying a list of objects.
"""
"""Abstract base class for date-based views displaying a list of objects."""
allow_empty = False
date_list_period = 'year'
@ -341,14 +295,12 @@ class BaseDateListView(MultipleObjectMixin, DateMixin, View):
return self.render_to_response(context)
def get_dated_items(self):
"""
Obtain the list of dates and items.
"""
"""Obtain the list of dates and items."""
raise NotImplementedError('A DateView must provide an implementation of get_dated_items()')
def get_ordering(self):
"""
Returns the field or fields to use for ordering the queryset; uses the
Return the field or fields to use for ordering the queryset; use the
date field by default.
"""
return '-%s' % self.get_date_field() if self.ordering is None else self.ordering
@ -381,7 +333,8 @@ class BaseDateListView(MultipleObjectMixin, DateMixin, View):
def get_date_list_period(self):
"""
Get the aggregation period for the list of dates: 'year', 'month', or 'day'.
Get the aggregation period for the list of dates: 'year', 'month', or
'day'.
"""
return self.date_list_period
@ -409,16 +362,12 @@ class BaseDateListView(MultipleObjectMixin, DateMixin, View):
class BaseArchiveIndexView(BaseDateListView):
"""
Base class for archives of date-based items.
Requires a response mixin.
Base class for archives of date-based items. Requires a response mixin.
"""
context_object_name = 'latest'
def get_dated_items(self):
"""
Return (date_list, items, extra_context) for this request.
"""
"""Return (date_list, items, extra_context) for this request."""
qs = self.get_dated_queryset()
date_list = self.get_date_list(qs, ordering='DESC')
@ -429,23 +378,17 @@ class BaseArchiveIndexView(BaseDateListView):
class ArchiveIndexView(MultipleObjectTemplateResponseMixin, BaseArchiveIndexView):
"""
Top-level archive of date-based items.
"""
"""Top-level archive of date-based items."""
template_name_suffix = '_archive'
class BaseYearArchiveView(YearMixin, BaseDateListView):
"""
List of objects published in a given year.
"""
"""List of objects published in a given year."""
date_list_period = 'month'
make_object_list = False
def get_dated_items(self):
"""
Return (date_list, items, extra_context) for this request.
"""
"""Return (date_list, items, extra_context) for this request."""
year = self.get_year()
date_field = self.get_date_field()
@ -481,22 +424,16 @@ class BaseYearArchiveView(YearMixin, BaseDateListView):
class YearArchiveView(MultipleObjectTemplateResponseMixin, BaseYearArchiveView):
"""
List of objects published in a given year.
"""
"""List of objects published in a given year."""
template_name_suffix = '_archive_year'
class BaseMonthArchiveView(YearMixin, MonthMixin, BaseDateListView):
"""
List of objects published in a given month.
"""
"""List of objects published in a given month."""
date_list_period = 'day'
def get_dated_items(self):
"""
Return (date_list, items, extra_context) for this request.
"""
"""Return (date_list, items, extra_context) for this request."""
year = self.get_year()
month = self.get_month()
@ -522,21 +459,15 @@ class BaseMonthArchiveView(YearMixin, MonthMixin, BaseDateListView):
class MonthArchiveView(MultipleObjectTemplateResponseMixin, BaseMonthArchiveView):
"""
List of objects published in a given month.
"""
"""List of objects published in a given month."""
template_name_suffix = '_archive_month'
class BaseWeekArchiveView(YearMixin, WeekMixin, BaseDateListView):
"""
List of objects published in a given week.
"""
"""List of objects published in a given week."""
def get_dated_items(self):
"""
Return (date_list, items, extra_context) for this request.
"""
"""Return (date_list, items, extra_context) for this request."""
year = self.get_year()
week = self.get_week()
@ -567,20 +498,14 @@ class BaseWeekArchiveView(YearMixin, WeekMixin, BaseDateListView):
class WeekArchiveView(MultipleObjectTemplateResponseMixin, BaseWeekArchiveView):
"""
List of objects published in a given week.
"""
"""List of objects published in a given week."""
template_name_suffix = '_archive_week'
class BaseDayArchiveView(YearMixin, MonthMixin, DayMixin, BaseDateListView):
"""
List of objects published on a given day.
"""
"""List of objects published on a given day."""
def get_dated_items(self):
"""
Return (date_list, items, extra_context) for this request.
"""
"""Return (date_list, items, extra_context) for this request."""
year = self.get_year()
month = self.get_month()
day = self.get_day()
@ -609,28 +534,20 @@ class BaseDayArchiveView(YearMixin, MonthMixin, DayMixin, BaseDateListView):
class DayArchiveView(MultipleObjectTemplateResponseMixin, BaseDayArchiveView):
"""
List of objects published on a given day.
"""
"""List of objects published on a given day."""
template_name_suffix = "_archive_day"
class BaseTodayArchiveView(BaseDayArchiveView):
"""
List of objects published today.
"""
"""List of objects published today."""
def get_dated_items(self):
"""
Return (date_list, items, extra_context) for this request.
"""
"""Return (date_list, items, extra_context) for this request."""
return self._get_dated_items(datetime.date.today())
class TodayArchiveView(MultipleObjectTemplateResponseMixin, BaseTodayArchiveView):
"""
List of objects published today.
"""
"""List of objects published today."""
template_name_suffix = "_archive_day"
@ -640,9 +557,7 @@ class BaseDateDetailView(YearMixin, MonthMixin, DayMixin, DateMixin, BaseDetailV
standard DetailView by accepting a year/month/day in the URL.
"""
def get_object(self, queryset=None):
"""
Get the object this request displays.
"""
"""Get the object this request displays."""
year = self.get_year()
month = self.get_month()
day = self.get_day()
@ -681,8 +596,8 @@ class DateDetailView(SingleObjectTemplateResponseMixin, BaseDateDetailView):
def _date_from_string(year, year_format, month='', month_format='', day='', day_format='', delim='__'):
"""
Helper: get a datetime.date object given a format string and a year,
month, and day (only year is mandatory). Raise a 404 for an invalid date.
Get a datetime.date object given a format string and a year, month, and day
(only year is mandatory). Raise a 404 for an invalid date.
"""
format = delim.join((year_format, month_format, day_format))
datestr = delim.join((year, month, day))
@ -697,9 +612,9 @@ def _date_from_string(year, year_format, month='', month_format='', day='', day_
def _get_next_prev(generic_view, date, is_previous, period):
"""
Helper: Get the next or the previous valid date. The idea is to allow
links on month/day views to never be 404s by never providing a date
that'll be invalid for the given view.
Get the next or the previous valid date. The idea is to allow links on
month/day views to never be 404s by never providing a date that'll be
invalid for the given view.
This is a bit complicated since it handles different intervals of time,
hence the coupling to generic_view.
@ -786,9 +701,7 @@ def _get_next_prev(generic_view, date, is_previous, period):
def timezone_today():
"""
Return the current date in the current time zone.
"""
"""Return the current date in the current time zone."""
if settings.USE_TZ:
return timezone.localdate()
else:

30
django/views/generic/detail.py
View File

@ -7,7 +7,7 @@ from django.views.generic.base import ContextMixin, TemplateResponseMixin, View
class SingleObjectMixin(ContextMixin):
"""
Provides the ability to retrieve a single object for further manipulation.
Provide the ability to retrieve a single object for further manipulation.
"""
model = None
queryset = None
@ -19,10 +19,10 @@ class SingleObjectMixin(ContextMixin):
def get_object(self, queryset=None):
"""
Returns the object the view is displaying.
Return the object the view is displaying.
By default this requires `self.queryset` and a `pk` or `slug` argument
in the URLconf, but subclasses can override this to return any object.
Require `self.queryset` and a `pk` or `slug` argument in the URLconf.
Subclasses can override this to return any object.
"""
# Use a custom queryset if provided; this is required for subclasses
# like DateDetailView
@ -58,8 +58,8 @@ class SingleObjectMixin(ContextMixin):
"""
Return the `QuerySet` that will be used to look up the object.
Note that this method is called by the default implementation of
`get_object` and may not be called if `get_object` is overridden.
This method is called by the default implementation of get_object() and
may not be called if get_object() is overridden.
"""
if self.queryset is None:
if self.model:
@ -75,15 +75,11 @@ class SingleObjectMixin(ContextMixin):
return self.queryset.all()
def get_slug_field(self):
"""
Get the name of a slug field to be used to look up by slug.
"""
"""Get the name of a slug field to be used to look up by slug."""
return self.slug_field
def get_context_object_name(self, obj):
"""
Get the name to use for the object.
"""
"""Get the name to use for the object."""
if self.context_object_name:
return self.context_object_name
elif isinstance(obj, models.Model):
@ -92,9 +88,7 @@ class SingleObjectMixin(ContextMixin):
return None
def get_context_data(self, **kwargs):
"""
Insert the single object into the context dict.
"""
"""Insert the single object into the context dict."""
context = {}
if self.object:
context['object'] = self.object
@ -106,9 +100,7 @@ class SingleObjectMixin(ContextMixin):
class BaseDetailView(SingleObjectMixin, View):
"""
A base view for displaying a single object
"""
"""A base view for displaying a single object."""
def get(self, request, *args, **kwargs):
self.object = self.get_object()
context = self.get_context_data(object=self.object)
@ -122,7 +114,7 @@ class SingleObjectTemplateResponseMixin(TemplateResponseMixin):
def get_template_names(self):
"""
Return a list of template names to be used for the request. May not be
called if render_to_response is overridden. Returns the following list:
called if render_to_response() is overridden. Return the following list:
* the value of ``template_name`` on the view (if provided)
* the contents of the ``template_name_field`` field on the

102
django/views/generic/edit.py
View File

@ -9,45 +9,32 @@ from django.views.generic.detail import (
class FormMixin(ContextMixin):
"""
A mixin that provides a way to show and handle a form in a request.
"""
"""Provide a way to show and handle a form in a request."""
initial = {}
form_class = None
success_url = None
prefix = None
def get_initial(self):
"""
Returns the initial data to use for forms on this view.
"""
"""Return the initial data to use for forms on this view."""
return self.initial.copy()
def get_prefix(self):
"""
Returns the prefix to use for forms on this view
"""
"""Return the prefix to use for forms."""
return self.prefix
def get_form_class(self):
"""
Returns the form class to use in this view
"""
"""Return the form class to use."""
return self.form_class
def get_form(self, form_class=None):
"""
Returns an instance of the form to be used in this view.
"""
"""Return an instance of the form to be used in this view."""
if form_class is None:
form_class = self.get_form_class()
return form_class(**self.get_form_kwargs())
def get_form_kwargs(self):
"""
Returns the keyword arguments for instantiating the form.
"""
"""Return the keyword arguments for instantiating the form."""
kwargs = {
'initial': self.get_initial(),
'prefix': self.get_prefix(),
@ -61,9 +48,7 @@ class FormMixin(ContextMixin):
return kwargs
def get_success_url(self):
"""
Returns the supplied success URL.
"""
"""Return the URL to redirect to after processing a valid form."""
if self.success_url:
# Forcing possible reverse_lazy evaluation
url = force_text(self.success_url)
@ -73,37 +58,26 @@ class FormMixin(ContextMixin):
return url
def form_valid(self, form):
"""
If the form is valid, redirect to the supplied URL.
"""
"""If the form is valid, redirect to the supplied URL."""
return HttpResponseRedirect(self.get_success_url())
def form_invalid(self, form):
"""
If the form is invalid, re-render the context data with the
data-filled form and errors.
"""
"""If the form is invalid, render the invalid form."""
return self.render_to_response(self.get_context_data(form=form))
def get_context_data(self, **kwargs):
"""
Insert the form into the context dict.
"""
"""Insert the form into the context dict."""
if 'form' not in kwargs:
kwargs['form'] = self.get_form()
return super().get_context_data(**kwargs)
class ModelFormMixin(FormMixin, SingleObjectMixin):
"""
A mixin that provides a way to show and handle a modelform in a request.
"""
"""Provide a way to show and handle a ModelForm in a request."""
fields = None
def get_form_class(self):
"""
Returns the form class to use in this view.
"""
"""Return the form class to use in this view."""
if self.fields is not None and self.form_class:
raise ImproperlyConfigured(
"Specifying both 'fields' and 'form_class' is not permitted."
@ -132,18 +106,14 @@ class ModelFormMixin(FormMixin, SingleObjectMixin):
return model_forms.modelform_factory(model, fields=self.fields)
def get_form_kwargs(self):
"""
Returns the keyword arguments for instantiating the form.
"""
"""Return the keyword arguments for instantiating the form."""
kwargs = super().get_form_kwargs()
if hasattr(self, 'object'):
kwargs.update({'instance': self.object})
return kwargs
def get_success_url(self):
"""
Returns the supplied URL.
"""
"""Return the URL to redirect to after processing a valid form."""
if self.success_url:
url = self.success_url.format(**self.object.__dict__)
else:
@ -156,27 +126,21 @@ class ModelFormMixin(FormMixin, SingleObjectMixin):
return url
def form_valid(self, form):
"""
If the form is valid, save the associated model.
"""
"""If the form is valid, save the associated model."""
self.object = form.save()
return super().form_valid(form)
class ProcessFormView(View):
"""
A mixin that renders a form on GET and processes it on POST.
"""
"""Render a form on GET and processes it on POST."""
def get(self, request, *args, **kwargs):
"""
Handles GET requests and instantiates a blank version of the form.
"""
"""Handle GET requests: instantiate a blank version of the form."""
return self.render_to_response(self.get_context_data())
def post(self, request, *args, **kwargs):
"""
Handles POST requests, instantiating a form instance with the passed
POST variables and then checked for validity.
Handle POST requests: instantiate a form instance with the passed
POST variables and then check if it's valid.
"""
form = self.get_form()
if form.is_valid():
@ -191,15 +155,11 @@ class ProcessFormView(View):
class BaseFormView(FormMixin, ProcessFormView):
"""
A base view for displaying a form.
"""
"""A base view for displaying a form."""
class FormView(TemplateResponseMixin, BaseFormView):
"""
A view for displaying a form, and rendering a template response.
"""
"""A view for displaying a form and rendering a template response."""
class BaseCreateView(ModelFormMixin, ProcessFormView):
@ -219,8 +179,7 @@ class BaseCreateView(ModelFormMixin, ProcessFormView):
class CreateView(SingleObjectTemplateResponseMixin, BaseCreateView):
"""
View for creating a new object instance,
with a response rendered by template.
View for creating a new object, with a response rendered by a template.
"""
template_name_suffix = '_form'
@ -241,23 +200,18 @@ class BaseUpdateView(ModelFormMixin, ProcessFormView):
class UpdateView(SingleObjectTemplateResponseMixin, BaseUpdateView):
"""
View for updating an object,
with a response rendered by template.
"""
"""View for updating an object, with a response rendered by a template."""
template_name_suffix = '_form'
class DeletionMixin:
"""
A mixin providing the ability to delete objects
"""
"""Provide the ability to delete objects."""
success_url = None
def delete(self, request, *args, **kwargs):
"""
Calls the delete() method on the fetched object and then
redirects to the success URL.
Call the delete() method on the fetched object and then redirect to the
success URL.
"""
self.object = self.get_object()
success_url = self.get_success_url()
@ -286,7 +240,7 @@ class BaseDeleteView(DeletionMixin, BaseDetailView):
class DeleteView(SingleObjectTemplateResponseMixin, BaseDeleteView):
"""
View for deleting an object retrieved with `self.get_object()`,
with a response rendered by template.
View for deleting an object retrieved with self.get_object(), with a
response rendered by a template.
"""
template_name_suffix = '_confirm_delete'

36
django/views/generic/list.py
View File

@ -7,9 +7,7 @@ from django.views.generic.base import ContextMixin, TemplateResponseMixin, View
class MultipleObjectMixin(ContextMixin):
"""
A mixin for views manipulating multiple objects.
"""
"""A mixin for views manipulating multiple objects."""
allow_empty = True
queryset = None
model = None
@ -50,15 +48,11 @@ class MultipleObjectMixin(ContextMixin):
return queryset
def get_ordering(self):
"""
Return the field or fields to use for ordering the queryset.
"""
"""Return the field or fields to use for ordering the queryset."""
return self.ordering
def paginate_queryset(self, queryset, page_size):
"""
Paginate the queryset, if needed.
"""
"""Paginate the queryset, if needed."""
paginator = self.get_paginator(
queryset, page_size, orphans=self.get_paginate_orphans(),
allow_empty_first_page=self.get_allow_empty())
@ -88,31 +82,27 @@ class MultipleObjectMixin(ContextMixin):
def get_paginator(self, queryset, per_page, orphans=0,
allow_empty_first_page=True, **kwargs):
"""
Return an instance of the paginator for this view.
"""
"""Return an instance of the paginator for this view."""
return self.paginator_class(
queryset, per_page, orphans=orphans,
allow_empty_first_page=allow_empty_first_page, **kwargs)
def get_paginate_orphans(self):
"""
Returns the maximum number of orphans extend the last page by when
Return the maximum number of orphans extend the last page by when
paginating.
"""
return self.paginate_orphans
def get_allow_empty(self):
"""
Returns ``True`` if the view should display empty lists, and ``False``
Return ``True`` if the view should display empty lists and ``False``
if a 404 should be raised instead.
"""
return self.allow_empty
def get_context_object_name(self, object_list):
"""
Get the name of the item to be used in the context.
"""
"""Get the name of the item to be used in the context."""
if self.context_object_name:
return self.context_object_name
elif hasattr(object_list, 'model'):
@ -121,9 +111,7 @@ class MultipleObjectMixin(ContextMixin):
return None
def get_context_data(self, *, object_list=None, **kwargs):
"""
Get the context for this view.
"""
"""Get the context for this view."""
queryset = object_list if object_list is not None else self.object_list
page_size = self.get_paginate_by(queryset)
context_object_name = self.get_context_object_name(queryset)
@ -149,9 +137,7 @@ class MultipleObjectMixin(ContextMixin):
class BaseListView(MultipleObjectMixin, View):
"""
A base view for displaying a list of objects.
"""
"""A base view for displaying a list of objects."""
def get(self, request, *args, **kwargs):
self.object_list = self.get_queryset()
allow_empty = self.get_allow_empty()
@ -173,9 +159,7 @@ class BaseListView(MultipleObjectMixin, View):
class MultipleObjectTemplateResponseMixin(TemplateResponseMixin):
"""
Mixin for responding with a template and list of objects.
"""
"""Mixin for responding with a template and list of objects."""
template_name_suffix = '_list'
def get_template_names(self):

16
django/views/i18n.py
View File

@ -22,9 +22,9 @@ LANGUAGE_QUERY_PARAMETER = 'language'
def set_language(request):
"""
Redirect to a given url while setting the chosen language in the
session or cookie. The url and the language code need to be
specified in the request parameters.
Redirect to a given URL while setting the chosen language in the session or
cookie. The URL and the language code need to be specified in the request
parameters.
Since this view changes how the user will see the rest of the site, it must
only be accessed as a POST request. If called as a GET request, it will
@ -60,9 +60,7 @@ def set_language(request):
def get_formats():
"""
Returns all formats strings required for i18n to work
"""
"""Return all formats strings required for i18n to work."""
FORMAT_SETTINGS = (
'DATE_FORMAT', 'DATETIME_FORMAT', 'TIME_FORMAT',
'YEAR_MONTH_FORMAT', 'MONTH_DAY_FORMAT', 'SHORT_DATE_FORMAT',
@ -207,7 +205,7 @@ def render_javascript_catalog(catalog=None, plural=None):
def null_javascript_catalog(request, domain=None, packages=None):
"""
Returns "identity" versions of the JavaScript i18n functions -- i.e.,
Return "identity" versions of the JavaScript i18n functions -- i.e.,
versions that don't actually do anything.
"""
return render_javascript_catalog()
@ -217,7 +215,7 @@ class JavaScriptCatalog(View):
"""
Return the selected language catalog as a JavaScript library.
Receives the list of packages to check for translations in the `packages`
Receive the list of packages to check for translations in the `packages`
kwarg either from the extra dictionary passed to the url() function or as a
plus-sign delimited string from the request. Default is 'django.conf'.
@ -305,7 +303,7 @@ class JSONCatalog(JavaScriptCatalog):
"""
Return the selected language catalog as a JSON object.
Receives the same parameters as JavaScriptCatalog and returns a response
Receive the same parameters as JavaScriptCatalog and return a response
with a JSON object of the following format:
{