Update the Column.nullable docstring for the primary_key=True case

While reviewing a change that created a new table, the
primary_key column value was set to True but nullable was not
explicitly set, which led to some confusion over the default
behavior for the nullable column value when setting a primary_key.

Looking at the docs it's not clear, but the code shows that if
nullable is not specified, then nullable = not primary_key, so
nullable defaults to False when primary_key is True.

This patch adds a simple clarification to the docs so people
don't have to check the code.

Change-Id: I8553339d56fbae11370c7c6af6d8d4723163be1c
Pull-request: https://github.com/zzzeek/sqlalchemy/pull/312

diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index df7e419ca63dd1236b0507814d67a55d7c2f95d5..27ef9e01b134d588ce087c33c85c1031094e9929 100644 (file)
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -1048,10 +1048,14 @@ class Column(SchemaItem, ColumnClause):
         :param info: Optional data dictionary which will be populated into the
             :attr:`.SchemaItem.info` attribute of this object.
 
-        :param nullable: If set to the default of ``True``, indicates the
-            column will be rendered as allowing NULL, else it's rendered as
-            NOT NULL. This parameter is only used when issuing CREATE TABLE
-            statements.
+        :param nullable: When set to ``False``, will cause the "NOT NULL"
+            phrase to be added when generating DDL for the column.   When
+            ``True``, will normally generate nothing (in SQL this defaults to
+            "NULL"), except in some very specific backend-specific edge cases
+            where "NULL" may render explicitly.   Defaults to ``True`` unless
+            :paramref:`~.Column.primary_key` is also ``True``, in which case it
+            defaults to ``False``.  This parameter is only used when issuing
+            CREATE TABLE statements.
 
         :param onupdate: A scalar, Python callable, or
             :class:`~sqlalchemy.sql.expression.ClauseElement` representing a