Update the Column.nullable docstring for the primary_key=True casepr/312

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.

1 files changed, 2 insertions, 1 deletions

diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index df7e419ca..853852f9b 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -1051,7 +1051,8 @@ class Column(SchemaItem, ColumnClause):
         :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.
+            statements. If not explicitly set and ``primary_key=True``, then
+            the column is non-nullable by default.
 
         :param onupdate: A scalar, Python callable, or
             :class:`~sqlalchemy.sql.expression.ClauseElement` representing a