diff --git a/django/views/debug.py b/django/views/debug.py index 2b829716fd..538abb1037 100644 --- a/django/views/debug.py +++ b/django/views/debug.py @@ -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"), diff --git a/django/views/decorators/cache.py b/django/views/decorators/cache.py index 7c5d157ea5..9658bd6ba2 100644 --- a/django/views/decorators/cache.py +++ b/django/views/decorators/cache.py @@ -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): diff --git a/django/views/decorators/clickjacking.py b/django/views/decorators/clickjacking.py index 828ae3c1fd..f8fc2d2b95 100644 --- a/django/views/decorators/clickjacking.py +++ b/django/views/decorators/clickjacking.py @@ -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): diff --git a/django/views/decorators/csrf.py b/django/views/decorators/csrf.py index 19e8fb30de..19d439a55a 100644 --- a/django/views/decorators/csrf.py +++ b/django/views/decorators/csrf.py @@ -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 diff --git a/django/views/decorators/debug.py b/django/views/decorators/debug.py index 318759f052..42a6d32661 100644 --- a/django/views/decorators/debug.py +++ b/django/views/decorators/debug.py @@ -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) diff --git a/django/views/generic/base.py b/django/views/generic/base.py index f63c89ac52..d9be6e17e8 100644 --- a/django/views/generic/base.py +++ b/django/views/generic/base.py @@ -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 diff --git a/django/views/generic/dates.py b/django/views/generic/dates.py index 48434d2adc..bc276b75db 100644 --- a/django/views/generic/dates.py +++ b/django/views/generic/dates.py @@ -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: diff --git a/django/views/generic/detail.py b/django/views/generic/detail.py index fe96005ca8..82599bdc5a 100644 --- a/django/views/generic/detail.py +++ b/django/views/generic/detail.py @@ -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 diff --git a/django/views/generic/edit.py b/django/views/generic/edit.py index 7d8a86b9fc..3dff9ece33 100644 --- a/django/views/generic/edit.py +++ b/django/views/generic/edit.py @@ -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' diff --git a/django/views/generic/list.py b/django/views/generic/list.py index df03c586f5..906e2a6016 100644 --- a/django/views/generic/list.py +++ b/django/views/generic/list.py @@ -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): diff --git a/django/views/i18n.py b/django/views/i18n.py index 68fefa8e30..ce78742fd8 100644 --- a/django/views/i18n.py +++ b/django/views/i18n.py @@ -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: {