Django 1.10 版本发行说明

Full text search for PostgreSQL

django.contrib.postgres now includes a collection of database functions to allow the use of the full text search engine. You can search across multiple fields in your relational database, combine the searches with other lookups, use different language configurations and weightings, and rank the results by relevance.

It also now includes trigram support, using the trigram_similar lookup, and the TrigramSimilarity and TrigramDistance expressions.

New-style middleware

A new style of middleware is introduced to solve the lack of strict request/response layering of the old-style of middleware described in DEP 0005. You'll need to adapt old, custom middleware and switch from the MIDDLEWARE_CLASSES setting to the new MIDDLEWARE setting to take advantage of the improvements.

Official support for Unicode usernames

The User model in django.contrib.auth originally only accepted ASCII letters and numbers in usernames. Although it wasn't a deliberate choice, Unicode characters have always been accepted when using Python 3.

The username validator now explicitly accepts Unicode characters by default on Python 3 only.

Custom user models may use the new ASCIIUsernameValidator or UnicodeUsernameValidator.

次要特性

数据库后端 API

• GIS's AreaField uses an unspecified underlying numeric type that could in practice be any numeric Python type. decimal.Decimal values retrieved from the database are now converted to float to make it easier to combine them with values used by the GIS libraries.
• In order to enable temporal subtraction you must set the supports_temporal_subtraction database feature flag to True and implement the DatabaseOperations.subtract_temporals() method. This method should return the SQL and parameters required to compute the difference in microseconds between the lhs and rhs arguments in the datatype used to store DurationField.

select_related() prohibits non-relational fields for nested relations

Django 1.8 added validation for non-relational fields in select_related():

>>> Book.objects.select_related('title')
Traceback (most recent call last):
...
FieldError: Non-relational field given in select_related: 'title'

But it didn't prohibit nested non-relation fields as it does now:

>>> Book.objects.select_related('author__name')
Traceback (most recent call last):
...
FieldError: Non-relational field given in select_related: 'name'

_meta.get_fields() returns consistent reverse fields for proxy models

Before Django 1.10, the get_fields() method returned different reverse fields when called on a proxy model compared to its proxied concrete class. This inconsistency was fixed by returning the full set of fields pointing to a concrete class or one of its proxies in both cases.

AbstractUser.username max_length increased to 150

A migration for django.contrib.auth.models.User.username is included. If you have a custom user model inheriting from AbstractUser, you'll need to generate and apply a database migration for your user model.

We considered an increase to 254 characters to more easily allow the use of email addresses (which are limited to 254 characters) as usernames but rejected it due to a MySQL limitation. When using the utf8mb4 encoding (recommended for proper Unicode support), MySQL can only create unique indexes with 191 characters by default. Therefore, if you need a longer length, please use a custom user model.

If you want to preserve the 30 character limit for usernames, use a custom form when creating a user or changing usernames:

from django.contrib.auth.forms import UserCreationForm

class MyUserCreationForm(UserCreationForm):
    username = forms.CharField(
        max_length=30,
        help_text='Required. 30 characters or fewer. Letters, digits and @/./+/-/_ only.',
    )

If you wish to keep this restriction in the admin, set UserAdmin.add_form to use this form:

from django.contrib.auth.admin import UserAdmin as BaseUserAdmin
from django.contrib.auth.models import User

class UserAdmin(BaseUserAdmin):
    add_form = MyUserCreationForm

admin.site.unregister(User)
admin.site.register(User, UserAdmin)

Dropped support for PostgreSQL 9.1

Upstream support for PostgreSQL 9.1 ends in September 2016. As a consequence, Django 1.10 sets PostgreSQL 9.2 as the minimum version it officially supports.

runserver output goes through logging

Request and response handling of the runserver command is sent to the django.server logger instead of to sys.stderr. If you disable Django's logging configuration or override it with your own, you'll need to add the appropriate logging configuration if you want to see that output:

'formatters': {
    'django.server': {
        '()': 'django.utils.log.ServerFormatter',
        'format': '[%(server_time)s] %(message)s',
    }
},
'handlers': {
    'django.server': {
        'level': 'INFO',
        'class': 'logging.StreamHandler',
        'formatter': 'django.server',
    },
},
'loggers': {
    'django.server': {
        'handlers': ['django.server'],
        'level': 'INFO',
        'propagate': False,
    }
}

auth.CustomUser and auth.ExtensionUser test models were removed

Since the introduction of migrations for the contrib apps in Django 1.8, the tables of these custom user test models were not created anymore making them unusable in a testing context.

Apps registry is no longer auto-populated when unpickling models outside of Django

The apps registry is no longer auto-populated when unpickling models. This was added in Django 1.7.2 as an attempt to allow unpickling models outside of Django, such as in an RQ worker, without calling django.setup(), but it creates the possibility of a deadlock. To adapt your code in the case of RQ, you can provide your own worker script that calls django.setup().

Removed null assignment check for non-null foreign key fields

In older versions, assigning None to a non-nullable ForeignKey or OneToOneField raised ValueError('Cannot assign None: "model.field" does not allow null values.'). For consistency with other model fields which don't have a similar check, this check is removed.

Removed weak password hashers from the default PASSWORD_HASHERS setting

Django 0.90 stored passwords as unsalted MD5. Django 0.91 added support for salted SHA1 with automatic upgrade of passwords when a user logs in. Django 1.4 added PBKDF2 as the default password hasher.

If you have an old Django project with MD5 or SHA1 (even salted) encoded passwords, be aware that these can be cracked fairly easily with today's hardware. To make Django users acknowledge continued use of weak hashers, the following hashers are removed from the default PASSWORD_HASHERS setting:

'django.contrib.auth.hashers.SHA1PasswordHasher'
'django.contrib.auth.hashers.MD5PasswordHasher'
'django.contrib.auth.hashers.UnsaltedSHA1PasswordHasher'
'django.contrib.auth.hashers.UnsaltedMD5PasswordHasher'
'django.contrib.auth.hashers.CryptPasswordHasher'

Consider using a wrapped password hasher to strengthen the hashes in your database. If that's not feasible, add the PASSWORD_HASHERS setting to your project and add back any hashers that you need.

You can check if your database has any of the removed hashers like this:

from django.contrib.auth import get_user_model
User = get_user_model()

# Unsalted MD5/SHA1:
User.objects.filter(password__startswith='md5$$')
User.objects.filter(password__startswith='sha1$$')
# Salted MD5/SHA1:
User.objects.filter(password__startswith='md5$').exclude(password__startswith='md5$$')
User.objects.filter(password__startswith='sha1$').exclude(password__startswith='sha1$$')
# Crypt hasher:
User.objects.filter(password__startswith='crypt$$')

from django.db.models import CharField
from django.db.models.functions import Length
CharField.register_lookup(Length)
# Unsalted MD5 passwords might not have an 'md5$$' prefix:
User.objects.filter(password__length=32)

Field.get_prep_lookup() and Field.get_db_prep_lookup() methods are removed

If you have a custom field that implements either of these methods, register a custom lookup for it. For example:

from django.db.models import Field
from django.db.models.lookups import Exact

class MyField(Field):
    ...

class MyFieldExact(Exact):
    def get_prep_lookup(self):
        # do_custom_stuff_for_myfield
        ....

MyField.register_lookup(MyFieldExact)

django.contrib.gis

• Support for SpatiaLite < 3.0 and GEOS < 3.3 is dropped.
• The add_postgis_srs() backwards compatibility alias for django.contrib.gis.utils.add_srs_entry() is removed.
• On Oracle/GIS, the Area aggregate function now returns a float instead of decimal.Decimal. (It's still wrapped in a measure of square meters.)
• The default GEOSGeometry representation (WKT output) is trimmed by default. That is, instead of POINT (23.0000000000000000 5.5000000000000000), you'll get POINT (23 5.5).

Maximum size of a request body and the number of GET/POST parameters is limited

Two new settings help mitigate denial-of-service attacks via large requests:

• DATA_UPLOAD_MAX_MEMORY_SIZE limits the size that a request body may be. File uploads don't count toward this limit.
• DATA_UPLOAD_MAX_NUMBER_FIELDS limits the number of GET/POST parameters that are parsed.

Applications that receive unusually large form posts may need to tune these settings.

杂项

• The repr() of a QuerySet is wrapped in <QuerySet > to disambiguate it from a plain list when debugging.
• utils.version.get_version() returns PEP 440 compliant release candidate versions (e.g. '1.10rc1' instead of '1.10c1').
• CSRF token values are now required to be strings of 64 alphanumerics; values of 32 alphanumerics, as set by older versions of Django by default, are automatically replaced by strings of 64 characters. Other values are considered invalid. This should only affect developers or users who replace these tokens.
• The LOGOUT_URL setting is removed as Django hasn't made use of it since pre-1.0. If you use it in your project, you can add it to your project's settings. The default value was '/accounts/logout/'.
• Objects with a close() method such as files and generators passed to HttpResponse are now closed immediately instead of when the WSGI server calls close() on the response.
• A redundant transaction.atomic() call in QuerySet.update_or_create() is removed. This may affect query counts tested by TransactionTestCase.assertNumQueries().
• Support for skip_validation in BaseCommand.execute(**options) is removed. Use skip_checks (added in Django 1.7) instead.
• loaddata now raises a CommandError instead of showing a warning when the specified fixture file is not found.
• Instead of directly accessing the LogEntry.change_message attribute, it's now better to call the LogEntry.get_change_message() method which will provide the message in the current language.
• The default error views now raise TemplateDoesNotExist if a nonexistent template_name is specified.
• The unused choices keyword argument of the Select and SelectMultiple widgets' render() method is removed. The choices argument of the render_options() method is also removed, making selected_choices the first argument.
• Tests that violate deferrable database constraints will now error when run on a database that supports deferrable constraints.
• Built-in management commands now use indexing of keys in options, e.g. options['verbosity'], instead of options.get() and no longer perform any type coercion. This could be a problem if you're calling commands using Command.execute() (which bypasses the argument parser that sets a default value) instead of call_command(). Instead of calling Command.execute(), pass the command object as the first argument to call_command().
• ModelBackend and RemoteUserBackend now reject inactive users. This means that inactive users can't login and will be logged out if they are switched from is_active=True to False. If you need the previous behavior, use the new AllowAllUsersModelBackend or AllowAllUsersRemoteUserBackend in AUTHENTICATION_BACKENDS instead.
• In light of the previous change, the test client's login() method no longer always rejects inactive users but instead delegates this decision to the authentication backend. force_login() also delegates the decision to the authentication backend, so if you're using the default backends, you need to use an active user.
• django.views.i18n.set_language() may now return a 204 status code for AJAX requests.
• The base_field attribute of RangeField is now a type of field, not an instance of a field. If you have created a custom subclass of RangeField, you should change the base_field attribute.
• Middleware classes are now initialized when the server starts rather than during the first request.
• If you override is_authenticated() or is_anonymous() in a custom user model, you must convert them to attributes or properties as described in the deprecation note.
• When using ModelAdmin.save_as=True, the "Save as new" button now redirects to the change view for the new object instead of to the model's changelist. If you need the previous behavior, set the new ModelAdmin.save_as_continue attribute to False.
• Required form fields now have the required HTML attribute. Set the Form.use_required_attribute attribute to False to disable it. You could also add the novalidate attribute to <form> if you don't want browser validation. To disable the required attribute on custom widgets, override the Widget.use_required_attribute() method.
• The WSGI handler no longer removes content of responses from HEAD requests or responses with a status_code of 100-199, 204, or 304. Most web servers already implement this behavior. Responses retrieved using the Django test client continue to have these "response fixes" applied.
• Model.__init__() now receives django.db.models.DEFERRED as the value of deferred fields.
• The Model._deferred attribute is removed as dynamic model classes when using QuerySet.defer() and only() is removed.
• Storage.save() no longer replaces '\' with '/'. This behavior is moved to FileSystemStorage since this is a storage specific implementation detail. Any Windows user with a custom storage implementation that relies on this behavior will need to implement it in the custom storage's save() method.
• Private FileField methods get_directory_name() and get_filename() are no longer called (and are now deprecated) which is a backwards incompatible change for users overriding those methods on custom fields. To adapt such code, override FileField.generate_filename() or Storage.generate_filename() instead. It might be possible to use upload_to also.
• The subject of mail sent by AdminEmailHandler is no longer truncated at 989 characters. If you were counting on a limited length, truncate the subject yourself.
• Private expressions django.db.models.expressions.Date and DateTime are removed. The new Trunc expressions provide the same functionality.
• The _base_manager and _default_manager attributes are removed from model instances. They remain accessible on the model class.
• Accessing a deleted field on a model instance, e.g. after del obj.field, reloads the field's value instead of raising AttributeError.
• If you subclass AbstractBaseUser and override clean(), be sure it calls super(). AbstractBaseUser.normalize_username() is called in a new AbstractBaseUser.clean() method.
• Private API django.forms.models.model_to_dict() returns a queryset rather than a list of primary keys for ManyToManyFields.
• If django.contrib.staticfiles is installed, the static template tag uses the staticfiles storage to construct the URL rather than simply joining the value with STATIC_ROOT. The new approach encodes the URL, which could be backwards-incompatible in cases such as including a fragment in a path, e.g. {% static 'img.svg#fragment' %}, since the # is encoded as %23. To adapt, move the fragment outside the template tag: {% static 'img.svg' %}#fragment.
• When USE_L10N is True, localization is now applied for the date and time filters when no format string is specified. The DATE_FORMAT and TIME_FORMAT specifiers from the active locale are used instead of the settings of the same name.

Direct assignment to a reverse foreign key or many-to-many relation

Instead of assigning related objects using direct assignment:

>>> new_list = [obj1, obj2, obj3]
>>> e.related_set = new_list

Use the set() method added in Django 1.9:

>>> e.related_set.set([obj1, obj2, obj3])

This prevents confusion about an assignment resulting in an implicit save.

Non-timezone-aware Storage API

The old, non-timezone-aware methods accessed_time(), created_time(), and modified_time() are deprecated in favor of the new get_*_time() methods.

Third-party storage backends should implement the new methods and mark the old ones as deprecated. Until then, the new get_*_time() methods on the base Storage class convert datetimes from the old methods as required and emit a deprecation warning as they do so.

Third-party storage backends may retain the old methods as long as they wish to support earlier versions of Django.

django.contrib.gis

• The get_srid() and set_srid() methods of GEOSGeometry are deprecated in favor of the srid property.
• The get_x(), set_x(), get_y(), set_y(), get_z(), and set_z() methods of Point are deprecated in favor of the x, y, and z properties.
• The get_coords() and set_coords() methods of Point are deprecated in favor of the tuple property.
• The cascaded_union property of MultiPolygon is deprecated in favor of the unary_union property.
• The django.contrib.gis.utils.precision_wkt() function is deprecated in favor of WKTWriter.

CommaSeparatedIntegerField model field

CommaSeparatedIntegerField is deprecated in favor of CharField with the validate_comma_separated_integer_list() validator:

from django.core.validators import validate_comma_separated_integer_list
from django.db import models

class MyModel(models.Model):
    numbers = models.CharField(..., validators=[validate_comma_separated_integer_list])

If you're using Oracle, CharField uses a different database field type (NVARCHAR2) than CommaSeparatedIntegerField (VARCHAR2). Depending on your database settings, this might imply a different encoding, and thus a different length (in bytes) for the same contents. If your stored values are longer than the 4000 byte limit of NVARCHAR2, you should use TextField (NCLOB) instead. In this case, if you have any queries that group by the field (e.g. annotating the model with an aggregation or using distinct()) you'll need to change them (to defer the field).

Using a model name as a query lookup when default_related_name is set

Assume the following models:

from django.db import models

class Foo(models.Model):
    pass

class Bar(models.Model):
    foo = models.ForeignKey(Foo)

    class Meta:
        default_related_name = 'bars'

In older versions, default_related_name couldn't be used as a query lookup. This is fixed and support for the old lookup name is deprecated. For example, since default_related_name is set in model Bar, instead of using the model name bar as the lookup:

>>> bar = Bar.objects.get(pk=1)
>>> Foo.objects.get(bar=bar)

use the default_related_name bars:

>>> Foo.objects.get(bars=bar)

Custom manager classes available through prefetch_related must define a _apply_rel_filters() method

If you defined a custom manager class available through prefetch_related() you must make sure it defines a _apply_rel_filters() method.

This method must accept a QuerySet instance as its single argument and return a filtered version of the queryset for the model instance the manager is bound to.

The "escape" half of django.utils.safestring

The mark_for_escaping() function and the classes it uses: EscapeData, EscapeBytes, EscapeText, EscapeString, and EscapeUnicode are deprecated.

As a result, the "lazy" behavior of the escape filter (where it would always be applied as the last filter no matter where in the filter chain it appeared) is deprecated. The filter will change to immediately apply conditional_escape() in Django 2.0.

Manager.use_for_related_fields and inheritance changes

Manager.use_for_related_fields is deprecated in favor of setting Meta.base_manager_name on the model.

Model Manager inheritance will follow MRO inheritance rules in Django 2.0, changing the current behavior where managers defined on non-abstract base classes aren't inherited by child classes. A deprecating warning with instructions on how to adapt your code is raised if you have any affected managers. You'll either redeclare a manager from an abstract model on the child class to override the manager from the concrete model, or you'll set the model's Meta.manager_inheritance_from_future=True option to opt-in to the new inheritance behavior.

During the deprecation period, use_for_related_fields will be honored and raise a warning, even if a base_manager_name is set. This allows third-party code to preserve legacy behavior while transitioning to the new API. The warning can be silenced by setting silence_use_for_related_fields_deprecation=True on the manager.

杂项

• The makemigrations --exit option is deprecated in favor of the makemigrations --check option.
• django.utils.functional.allow_lazy() is deprecated in favor of the new keep_lazy() function which can be used with a more natural decorator syntax.
• The shell --plain option is deprecated in favor of -i python or --interface python.
• Importing from the django.core.urlresolvers module is deprecated in favor of its new location, django.urls.
• The template Context.has_key() method is deprecated in favor of in.
• The private attribute virtual_fields of Model._meta is deprecated in favor of private_fields.
• The private keyword arguments virtual_only in Field.contribute_to_class() and virtual in Model._meta.add_field() are deprecated in favor of private_only and private, respectively.
• The javascript_catalog() and json_catalog() views are deprecated in favor of class-based views JavaScriptCatalog and JSONCatalog.
• In multi-table inheritance, implicit promotion of a OneToOneField to a parent_link is deprecated. Add parent_link=True to such fields.
• The private API Widget._format_value() is made public and renamed to format_value(). The old name will work through a deprecation period.
• Private FileField methods get_directory_name() and get_filename() are deprecated in favor of performing this work in Storage.generate_filename()).
• Old-style middleware that uses settings.MIDDLEWARE_CLASSES are deprecated. Adapt old, custom middleware and use the new MIDDLEWARE setting.