From 7970d97a708f0d2f4fbd654eaf785338ab04cc1e Mon Sep 17 00:00:00 2001 From: Andrew Godwin Date: Sat, 10 Aug 2013 20:00:12 +0100 Subject: [PATCH] Docs tweaks (thanks timgraham) --- django/db/backends/mysql/introspection.py | 6 +++--- django/db/migrations/autodetector.py | 2 +- django/db/migrations/graph.py | 8 ++++---- django/test/runner.py | 2 +- django/utils/datastructures.py | 2 +- docs/ref/django-admin.txt | 14 +++++++++----- docs/ref/signals.txt | 5 ----- docs/releases/1.7.txt | 18 +++++++++++++----- docs/topics/migrations.txt | 12 ++++++------ 9 files changed, 38 insertions(+), 31 deletions(-) diff --git a/django/db/backends/mysql/introspection.py b/django/db/backends/mysql/introspection.py index 0cad8d9b9d7..d7a29057de4 100644 --- a/django/db/backends/mysql/introspection.py +++ b/django/db/backends/mysql/introspection.py @@ -1,6 +1,6 @@ import re from .base import FIELD_TYPE -from django.utils.datastructures import SortedSet +from django.utils.datastructures import OrderedSet from django.db.backends import BaseDatabaseIntrospection, FieldInfo from django.utils.encoding import force_text @@ -142,7 +142,7 @@ class DatabaseIntrospection(BaseDatabaseIntrospection): for constraint, column, ref_table, ref_column in cursor.fetchall(): if constraint not in constraints: constraints[constraint] = { - 'columns': SortedSet(), + 'columns': OrderedSet(), 'primary_key': False, 'unique': False, 'index': False, @@ -170,7 +170,7 @@ class DatabaseIntrospection(BaseDatabaseIntrospection): for table, non_unique, index, colseq, column in [x[:5] for x in cursor.fetchall()]: if index not in constraints: constraints[index] = { - 'columns': SortedSet(), + 'columns': OrderedSet(), 'primary_key': False, 'unique': False, 'index': True, diff --git a/django/db/migrations/autodetector.py b/django/db/migrations/autodetector.py index 259ee0bd5b3..ff5957fe7ed 100644 --- a/django/db/migrations/autodetector.py +++ b/django/db/migrations/autodetector.py @@ -29,7 +29,7 @@ class MigrationAutodetector(object): """ Returns a dict of migration plans which will achieve the change from from_state to to_state. The dict has app labels - as kays and a list of migrations as values. + as keys and a list of migrations as values. The resulting migrations aren't specially named, but the names do matter for dependencies inside the set. diff --git a/django/db/migrations/graph.py b/django/db/migrations/graph.py index 3b6495689a1..fcd83913c8b 100644 --- a/django/db/migrations/graph.py +++ b/django/db/migrations/graph.py @@ -1,4 +1,4 @@ -from django.utils.datastructures import SortedSet +from django.utils.datastructures import OrderedSet from django.db.migrations.state import ProjectState @@ -13,7 +13,7 @@ class MigrationGraph(object): branch merges can be detected and resolved. Migrations files can be marked as replacing another set of migrations - - this is to support the "squash" feature. The graph handler isn't resposible + this is to support the "squash" feature. The graph handler isn't responsible for these; instead, the code to load them in here should examine the migration files and if the replaced migrations are all either unapplied or not present, it should ignore the replaced ones, load in just the @@ -109,8 +109,8 @@ class MigrationGraph(object): for n in children: results = _dfs(n, get_children, path) + results path.pop() - # Use SortedSet to ensure only one instance of each result - results = list(SortedSet(results)) + # Use OrderedSet to ensure only one instance of each result + results = list(OrderedSet(results)) # Populate DP cache cache[(start, get_children)] = results # Done! diff --git a/django/test/runner.py b/django/test/runner.py index c7881ada635..84fe2499f1d 100644 --- a/django/test/runner.py +++ b/django/test/runner.py @@ -267,7 +267,7 @@ def setup_databases(verbosity, interactive, **kwargs): # Second pass -- actually create the databases. old_names = [] mirrors = [] - + for signature, (db_name, aliases) in dependency_ordered( test_databases.items(), dependencies): test_db_name = None diff --git a/django/utils/datastructures.py b/django/utils/datastructures.py index d61b569112e..a0ee3e06ef5 100644 --- a/django/utils/datastructures.py +++ b/django/utils/datastructures.py @@ -237,7 +237,7 @@ class SortedDict(dict): super(SortedDict, self).clear() self.keyOrder = [] -class SortedSet(object): +class OrderedSet(object): """ A set which keeps the ordering of the inserted items. Currently backs onto OrderedDict. diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index ab83e2cf33c..27b68e4f1cf 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -575,20 +575,22 @@ makemigrations [] .. django-admin:: makemigrations +.. versionadded:: 1.7 + Creates new migrations based on the changes detected to your models. Migrations, their relationship with apps and more are covered in depth in :doc:`the migrations documentation`. Providing one or more app names as arguments will limit the migrations created -to the app specified and any dependencies needed (the table at the other end -of a ForeignKey, for example) +to the app(s) specified and any dependencies needed (the table at the other end +of a ``ForeignKey``, for example). .. django-admin-option:: --empty The ``--empty`` option will cause ``makemigrations`` to output an empty migration for the specified apps, for manual editing. This option is only for advanced users and should not be used unless you are familiar with -the migration format, migration operations and the dependencies between +the migration format, migration operations, and the dependencies between your migrations. migrate [ []] @@ -596,11 +598,13 @@ migrate [ []] .. django-admin:: migrate -Synchronises the database state with the current set of models and migrations. +.. versionadded:: 1.7 + +Synchronizes the database state with the current set of models and migrations. Migrations, their relationship with apps and more are covered in depth in :doc:`the migrations documentation`. -The behaviour of this command changes depending on the arguments provided: +The behavior of this command changes depending on the arguments provided: * No arguments: All migrated apps have all of their migrations run, and all unmigrated apps are synchronized with the database, diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt index b988371aa74..ca1668000c9 100644 --- a/docs/ref/signals.txt +++ b/docs/ref/signals.txt @@ -403,7 +403,6 @@ Arguments sent with this signal: ``db`` The alias of database on which a command will operate. - pre_syncdb ---------- @@ -421,7 +420,6 @@ is present, for backwards-compatability this signal has an extra argument it sen A list of the model classes from any app which :djadmin:`migrate` is going to create, **only if the app has no migrations**. - post_migrate ------------ @@ -479,7 +477,6 @@ For example, ``yourapp/management/__init__.py`` could be written like:: post_migrate.connect(my_callback, sender=yourapp.models) - post_syncdb ----------- @@ -497,8 +494,6 @@ is present, for backwards-compatability this signal has an extra argument it sen A list of the model classes from any app which :djadmin:`migrate` has created, **only if the app has no migrations**. - - Request/response signals ======================== diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt index c20a2784968..3b1fe0c40e8 100644 --- a/docs/releases/1.7.txt +++ b/docs/releases/1.7.txt @@ -33,15 +33,16 @@ What's new in Django 1.7 Schema migrations ~~~~~~~~~~~~~~~~~ -Django now has built-in support for schema migrations, which allows models -to be updated, changed and deleted and the changes stored into migration files -and then run on any deployed database. +Django now has built-in support for schema migrations. It allows models +to be updated, changed, and deleted by creating migration files that represent +the model changes and which can be run on any development, staging or production +database. Migrations are covered in :doc:`their own documentation`, but a few of the key features are: * ``syncdb`` has been deprecated and replaced by ``migrate``. Don't worry - - calls to ``syncdb`` will still work as before. + calls to ``syncdb`` will still work as before. * A new ``makemigrations`` command provides an easy way to autodetect changes to your models and make migrations for them. @@ -60,7 +61,7 @@ but a few of the key features are: New method on Field subclasses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To help power both schema migrations and composite keys, the Field API now +To help power both schema migrations and composite keys, the :class:`~django.db.models.Field` API now has a new required method: ``deconstruct()``. This method takes no arguments, and returns a tuple of four items: @@ -278,3 +279,10 @@ work until Django 1.9. it will go through a regular deprecation path. This attribute was mostly used by methods that bypassed ``ModelAdmin.get_fieldsets()`` but this was considered a bug and has been addressed. + +``syncdb`` +~~~~~~~~~~ + +The ``syncdb`` command has been deprecated in favour of the new ``migrate`` +command. ``migrate`` takes the same arguments as ``syncdb`` used to plus a few +more, so it's safe to just change the name you're calling and nothing else. diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt index 5f7def7107c..5862c5defec 100644 --- a/docs/topics/migrations.txt +++ b/docs/topics/migrations.txt @@ -49,7 +49,7 @@ The migration files for each app live in a "migrations" directory inside of that app, and are designed to be committed to, and distributed as part of, its codebase. You should be making them once on your development machine and then running the same migrations on your colleagues' machines, your -staging machines and eventually your production machines. +staging machines, and eventually your production machines. Migrations will run the same way every time and produce consistent results, meaning that what you see in development and staging is exactly what will @@ -60,7 +60,7 @@ Backend Support Migrations are supported on all backends that Django ships with, as well as any third-party backends if they have programmed in support for schema -alteration (done via the SchemaEditor class). +alteration (done via the ``SchemaEditor`` class). However, some databases are more capable than others when it comes to schema migrations; some of the caveats are covered below. @@ -169,7 +169,7 @@ app - in the file, so it's possible to detect when there's two new migrations for the same app that aren't ordered. When this happens, Django will prompt you and give you some options. If it -thinks it's safe enough, it will offer to automatically linearise the two +thinks it's safe enough, it will offer to automatically linearize the two migrations for you. If not, you'll have to go in and modify the migrations yourself - don't worry, this isn't difficult, and is explained more in :ref:`migration-files` below. @@ -184,8 +184,8 @@ you add a ForeignKey in your ``books`` app to your ``authors`` app - the resulting migration will contain a dependency on a migration in ``authors``. This means that when you run the migrations, the ``authors`` migration runs -first and creates the table the ForeignKey references, and then the migration -that makes the ForeignKey column runs afterwards and creates the constraint. +first and creates the table the ``ForeignKey`` references, and then the migration +that makes the ``ForeignKey`` column runs afterwards and creates the constraint. If this didn't happen, the migration would try to create the ForeignKey column without the table it's referencing existing and your database would throw an error. @@ -271,7 +271,7 @@ Note that this only works given two things: * You have not manually edited your database - Django won't be able to detect that your database doesn't match your models, you'll just get errors when - migrations try and modify those tables. + migrations try to modify those tables. .. historical-models: