From 05e76a1430e91687d2bd65036a1f218d879d0bf0 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sat, 29 Oct 2011 22:48:52 +0200 Subject: [PATCH] update sqlalchemy documentation links use explicit code-block markup --- docs/changeset.rst | 223 +++++++++++++++++++++++++-------------------- 1 file changed, 125 insertions(+), 98 deletions(-) diff --git a/docs/changeset.rst b/docs/changeset.rst index 0ab0b2b..1ae070e 100644 --- a/docs/changeset.rst +++ b/docs/changeset.rst @@ -7,19 +7,18 @@ Database schema migrations .. currentmodule:: migrate.changeset.schema -Importing :mod:`migrate.changeset` adds some new methods to existing -SQLAlchemy objects, as well as creating functions of its own. Most operations -can be done either by a method or a function. Methods match -SQLAlchemy's existing API and are more intuitive when the object is -available; functions allow one to make changes when only the name of -an object is available (for example, adding a column to a table in the -database without having to load that table into Python). +Importing :mod:`migrate.changeset` adds some new methods to existing SQLAlchemy +objects, as well as creating functions of its own. Most operations can be done +either by a method or a function. Methods match SQLAlchemy's existing API and +are more intuitive when the object is available; functions allow one to make +changes when only the name of an object is available (for example, adding a +column to a table in the database without having to load that table into +Python). Changeset operations can be used independently of SQLAlchemy Migrate's :ref:`versioning `. -For more information, see the API documentation for -:mod:`migrate.changeset`. +For more information, see the API documentation for :mod:`migrate.changeset`. .. _summary-changeset-api: @@ -43,69 +42,76 @@ Here are some direct links to the relevent sections of the API documentations: .. note:: - Many of the schema modification methods above take an - ``alter_metadata`` keyword parameter. This parameter defaults to - ``True``. + Many of the schema modification methods above take an ``alter_metadata`` + keyword parameter. This parameter defaults to `True`. -The following sections give examples of how to make various kinds of -schema changes. +The following sections give examples of how to make various kinds of schema +changes. Column ====== -Given a standard SQLAlchemy table:: +Given a standard SQLAlchemy table: - table = Table('mytable', meta, - Column('id', Integer, primary_key=True), - ) - table.create() +.. code-block:: python + + table = Table('mytable', meta, + Column('id', Integer, primary_key=True), + ) + table.create() .. _column-create: -You can create a column with :meth:`~ChangesetColumn.create`:: +You can create a column with :meth:`~ChangesetColumn.create`: - col = Column('col1', String, default='foobar') - col.create(table, populate_default=True) +.. code-block:: python - # Column is added to table based on its name - assert col is table.c.col1 + col = Column('col1', String, default='foobar') + col.create(table, populate_default=True) - # col1 is populated with 'foobar' because of `populate_default` + # Column is added to table based on its name + assert col is table.c.col1 + + # col1 is populated with 'foobar' because of `populate_default` .. _column-drop: .. note:: - You can pass `primary_key_name`, `index_name` - and `unique_name` to the :meth:`~ChangesetColumn.create` method to issue ``ALTER TABLE ADD + You can pass `primary_key_name`, `index_name` and `unique_name` to the + :meth:`~ChangesetColumn.create` method to issue ``ALTER TABLE ADD CONSTRAINT`` after changing the column. - For multi columns constraints and other advanced configuration, - check the :ref:`constraint tutorial `. + For multi columns constraints and other advanced configuration, check the + :ref:`constraint tutorial `. .. versionadded:: 0.6.0 -You can drop a column with :meth:`~ChangesetColumn.drop`:: +You can drop a column with :meth:`~ChangesetColumn.drop`: - col.drop() +.. code-block:: python + + col.drop() .. _column-alter: -You can alter a column with :meth:`~ChangesetColumn.alter`:: +You can alter a column with :meth:`~ChangesetColumn.alter`: - col.alter(name='col2') +.. code-block:: python - # Renaming a column affects how it's accessed by the table object - assert col is table.c.col2 + col.alter(name='col2') - # Other properties can be modified as well - col.alter(type=String(42), default="life, the universe, and everything", nullable=False) + # Renaming a column affects how it's accessed by the table object + assert col is table.c.col2 - # Given another column object, col1.alter(col2), col1 will be changed to match col2 - col.alter(Column('col3', String(77), nullable=True)) - assert col.nullable - assert table.c.col3 is col + # Other properties can be modified as well + col.alter(type=String(42), default="life, the universe, and everything", nullable=False) + + # Given another column object, col1.alter(col2), col1 will be changed to match col2 + col.alter(Column('col3', String(77), nullable=True)) + assert col.nullable + assert table.c.col3 is col .. deprecated:: 0.6.0 Passing a :class:`~sqlalchemy.schema.Column` to @@ -121,11 +127,13 @@ Table SQLAlchemy includes support for `creating and dropping`__ tables.. -Tables can be renamed with :meth:`~ChangesetTable.rename`:: +Tables can be renamed with :meth:`~ChangesetTable.rename`: - table.rename('newtablename') +.. code-block:: python -.. __: http://www.sqlalchemy.org/docs/05/metadata.html#creating-and-dropping-database-tables + table.rename('newtablename') + +.. __: http://www.sqlalchemy.org/docs/core/schema.html#creating-and-dropping-database-tables .. currentmodule:: migrate.changeset.constraint @@ -136,11 +144,14 @@ Index SQLAlchemy supports `creating and dropping`__ indexes. -Indexes can be renamed using :meth:`~migrate.changeset.schema.ChangesetIndex.rename`:: +Indexes can be renamed using +:meth:`~migrate.changeset.schema.ChangesetIndex.rename`: - index.rename('newindexname') +.. code-block:: python -.. __: http://www.sqlalchemy.org/docs/05/metadata.html#indexes + index.rename('newindexname') + +.. __: http://www.sqlalchemy.org/docs/core/schema.html#indexes .. _constraint-tutorial: @@ -150,29 +161,33 @@ Constraint .. currentmodule:: migrate.changeset.constraint -SQLAlchemy supports creating or dropping constraints at the same time -a table is created or dropped. SQLAlchemy Migrate adds support for -creating and dropping -:class:`~sqlalchemy.schema.PrimaryKeyConstraint`, +SQLAlchemy supports creating or dropping constraints at the same time a table +is created or dropped. SQLAlchemy Migrate adds support for creating and +dropping :class:`~sqlalchemy.schema.PrimaryKeyConstraint`, :class:`~sqlalchemy.schema.ForeignKeyConstraint`, :class:`~sqlalchemy.schema.CheckConstraint` and -:class:`~sqlalchemy.schema.UniqueConstraint` constraints independently -using ``ALTER TABLE`` statements. +:class:`~sqlalchemy.schema.UniqueConstraint` constraints independently using +``ALTER TABLE`` statements. The following rundowns are true for all constraints classes: -1. Make sure you import the relevent constrain class Migrate and not - from SQLAlchemy, for example:: +#. Make sure you import the relevant constraint class from :mod:`migrate` and + not from :mod:`sqlalchemy`, for example: - from migrate.changeset.constraint import ForeignKeyConstraint + .. code-block:: python + + from migrate.changeset.constraint import ForeignKeyConstraint The classes in that module have the extra - :meth:`~ConstraintChangeset.create` and - :meth:`~ConstraintChangeset.drop` methods. + :meth:`~ConstraintChangeset.create` and :meth:`~ConstraintChangeset.drop` + methods. -2. You can also use Constraints as in SQLAlchemy. In this case passing table argument explicitly is required:: +#. You can also use constraints as in SQLAlchemy. In this case passing table + argument explicitly is required: - cons = PrimaryKeyConstraint('id', 'num', table=self.table) + .. code-block:: python + + cons = PrimaryKeyConstraint('id', 'num', table=self.table) # Create the constraint cons.create() @@ -180,11 +195,16 @@ The following rundowns are true for all constraints classes: # Drop the constraint cons.drop() - You can also pass in :class:`~sqlalchemy.schema.Column` objects (and table argument can be left out):: + You can also pass in :class:`~sqlalchemy.schema.Column` objects (and table + argument can be left out): + + .. code-block:: python cons = PrimaryKeyConstraint(col1, col2) -3. Some dialects support ``CASCADE`` option when dropping constraints:: +#. Some dialects support ``CASCADE`` option when dropping constraints: + + .. code-block:: python cons = PrimaryKeyConstraint(col1, col2) @@ -194,62 +214,69 @@ The following rundowns are true for all constraints classes: # Drop the constraint cons.drop(cascade=True) - .. note:: - SQLAlchemy Migrate will try to guess the name of the - constraints for databases, but if it's something other than - the default, you'll need to give its name. Best practice is - to always name your constraints. Note that Oracle requires - that you state the name of the constraint to be created or dropped. + SQLAlchemy Migrate will try to guess the name of the constraints for + databases, but if it's something other than the default, you'll need to + give its name. Best practice is to always name your constraints. Note that + Oracle requires that you state the name of the constraint to be created or + dropped. Examples --------- -Primary key constraints:: +Primary key constraints: - from migrate.changeset.constraint import PrimaryKeyConstraint +.. code-block:: python - cons = PrimaryKeyConstraint(col1, col2) + from migrate.changeset.constraint import PrimaryKeyConstraint - # Create the constraint - cons.create() + cons = PrimaryKeyConstraint(col1, col2) - # Drop the constraint - cons.drop() + # Create the constraint + cons.create() -Foreign key constraints:: + # Drop the constraint + cons.drop() - from migrate.changeset.constraint import ForeignKeyConstraint +Foreign key constraints: - cons = ForeignKeyConstraint([table.c.fkey], [othertable.c.id]) +.. code-block:: python - # Create the constraint - cons.create() + from migrate.changeset.constraint import ForeignKeyConstraint + + cons = ForeignKeyConstraint([table.c.fkey], [othertable.c.id]) + + # Create the constraint + cons.create() + + # Drop the constraint + cons.drop() - # Drop the constraint - cons.drop() +Check constraints: -Check constraints:: +.. code-block:: python - from migrate.changeset.constraint import CheckConstraint + from migrate.changeset.constraint import CheckConstraint + + cons = CheckConstraint('id > 3', columns=[table.c.id]) + + # Create the constraint + cons.create() - cons = CheckConstraint('id > 3', columns=[table.c.id]) + # Drop the constraint + cons.drop() - # Create the constraint - cons.create() +Unique constraints: - # Drop the constraint - cons.drop() +.. code-block:: python -Unique constraints:: + from migrate.changeset.constraint import UniqueConstraint + + cons = UniqueConstraint('id', 'age', table=self.table) - from migrate.changeset.constraint import UniqueConstraint + # Create the constraint + cons.create() - cons = UniqueConstraint('id', 'age', table=self.table) - - # Create the constraint - cons.create() - - # Drop the constraint - cons.drop() + # Drop the constraint + cons.drop()