Skip to content

Commit 369edbb

Browse files
jvanascojvanasco
committed
standardizing docs sqlalchemy#6821
(redo of 2999/I5609025feee8cfdecc09b55bfbf1bd13fa2e6602) This PR is designed to bring more clarity within the docs by renaming object instances that may be consfusingly similar to class, method, and attribute names. For example, instances of the class `MetaData` are available on some objects as `.metadata` property, and had appeared within the docs as both `meta` and `metadata` which has confused some users in the past. By this PR, the docs now utilize the following naming convention: * MetaData - SQLAlchemy class * .metadata - SQLAlchemy API attributes * metadata_obj - developer instantiated metadata objects or references Detailed Changes: * standardized `meta` and `metadata` instances to `metadata_obj`. note: the docs were evenly split between 'meta' and 'metadata'. * standardized 'cursor' to 'cursor_obj' to avoid confusion with the method. * standardized a 'scalar_subquery = ' to 'scalar_subq' to avoid confusion with the method. * standardized a 'cte = ' to 'cte_obj' to avoid confusion with the method Change-Id: I79c98aee16c5fc6649289b2dd7d6dfc368222fb4
1 parent 207ec35 commit 369edbb

26 files changed

Lines changed: 199 additions & 199 deletions

‎doc/build/changelog/migration_13.rst‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1006,12 +1006,12 @@ joined together either with no separator or with an underscore
10061006
separator. Below we define a convention that will name :class:`.UniqueConstraint`
10071007
constraints with a name that joins together the names of all columns::
10081008

1009-
metadata = MetaData(naming_convention={
1009+
metadata_obj = MetaData(naming_convention={
10101010
"uq": "uq_%(table_name)s_%(column_0_N_name)s"
10111011
})
10121012

10131013
table = Table(
1014-
'info', metadata,
1014+
'info', metadata_obj,
10151015
Column('a', Integer),
10161016
Column('b', Integer),
10171017
Column('c', Integer),
@@ -1037,7 +1037,7 @@ PostgreSQL where identifiers cannot be longer than 63 characters, a long
10371037
constraint name would normally be generated from the table definition below::
10381038

10391039
long_names = Table(
1040-
'long_names', metadata,
1040+
'long_names', metadata_obj,
10411041
Column('information_channel_code', Integer, key='a'),
10421042
Column('billing_convention_name', Integer, key='b'),
10431043
Column('product_identifier', Integer, key='c'),
@@ -1445,7 +1445,7 @@ queries used until now.
14451445
Given a schema such as::
14461446

14471447
dv = Table(
1448-
'data_values', metadata,
1448+
'data_values', metadata_obj,
14491449
Column('modulus', Integer, nullable=False),
14501450
Column('data', String(30)),
14511451
postgresql_partition_by='range(modulus)')
@@ -1542,7 +1542,7 @@ keyword added to objects like :class:`.UniqueConstraint` as well
15421542
as several :class:`_schema.Column` -specific variants::
15431543

15441544
some_table = Table(
1545-
'some_table', metadata,
1545+
'some_table', metadata_obj,
15461546
Column('id', Integer, primary_key=True, sqlite_on_conflict_primary_key='FAIL'),
15471547
Column('data', Integer),
15481548
UniqueConstraint('id', 'data', sqlite_on_conflict='IGNORE')
@@ -1678,7 +1678,7 @@ new ``mssql_identity_start`` and ``mssql_identity_increment`` parameters
16781678
on :class:`_schema.Column`::
16791679

16801680
test = Table(
1681-
'test', metadata,
1681+
'test', metadata_obj,
16821682
Column(
16831683
'id', Integer, primary_key=True, mssql_identity_start=100,
16841684
mssql_identity_increment=10
@@ -1693,7 +1693,7 @@ primary key column::
16931693

16941694

16951695
test = Table(
1696-
'test', metadata,
1696+
'test', metadata_obj,
16971697
Column('id', Integer, primary_key=True, autoincrement=False),
16981698
Column('number', Integer, autoincrement=True)
16991699
)

‎doc/build/changelog/migration_20.rst‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -556,13 +556,13 @@ execution patterns, is removed::
556556

557557
from sqlalchemy import MetaData
558558

559-
metadata = MetaData(bind=engine) # no longer supported
559+
metadata_obj = MetaData(bind=engine) # no longer supported
560560

561-
metadata.create_all() # requires Engine or Connection
561+
metadata_obj.create_all() # requires Engine or Connection
562562

563-
metadata.reflect() # requires Engine or Connection
563+
metadata_obj.reflect() # requires Engine or Connection
564564

565-
t = Table('t', metadata, autoload=True) # use autoload_with=engine
565+
t = Table('t', metadata_obj, autoload=True) # use autoload_with=engine
566566

567567
result = engine.execute(t.select()) # no longer supported
568568

@@ -581,18 +581,18 @@ the ORM-level :meth:`_orm.Session.execute` method)::
581581

582582
from sqlalchemy import MetaData
583583

584-
metadata = MetaData()
584+
metadata_obj = MetaData()
585585

586586
# engine level:
587587

588588
# create tables
589-
metadata.create_all(engine)
589+
metadata_obj.create_all(engine)
590590

591591
# reflect all tables
592-
metadata.reflect(engine)
592+
metadata_obj.reflect(engine)
593593

594594
# reflect individual table
595-
t = Table('t', metadata, autoload_with=engine)
595+
t = Table('t', metadata_obj, autoload_with=engine)
596596

597597

598598
# connection level:
@@ -601,13 +601,13 @@ the ORM-level :meth:`_orm.Session.execute` method)::
601601
with engine.connect() as connection:
602602
# create tables, requires explicit begin and/or commit:
603603
with connection.begin():
604-
metadata.create_all(connection)
604+
metadata_obj.create_all(connection)
605605

606606
# reflect all tables
607-
metadata.reflect(connection)
607+
metadata_obj.reflect(connection)
608608

609609
# reflect individual table
610-
t = Table('t', metadata, autoload_with=connection)
610+
t = Table('t', metadata_obj, autoload_with=connection)
611611

612612
# execute SQL statements
613613
result = conn.execute(t.select())
@@ -685,10 +685,10 @@ Core from "many choices"::
685685
# many choices
686686

687687
# bound metadata?
688-
metadata = MetaData(engine)
688+
metadata_obj = MetaData(engine)
689689

690690
# or not?
691-
metadata = MetaData()
691+
metadata_obj = MetaData()
692692

693693
# execute from engine?
694694
result = engine.execute(stmt)
@@ -973,7 +973,7 @@ documented style in the Core tutorial.
973973
Examples of "structural" vs. "data" elements are as follows::
974974

975975
# table columns for CREATE TABLE - structural
976-
table = Table("table", metadata, Column('x', Integer), Column('y', Integer))
976+
table = Table("table", metadata_obj, Column('x', Integer), Column('y', Integer))
977977

978978
# columns in a SELECT statement - structural
979979
stmt = select(table.c.x, table.c.y)

‎doc/build/core/connections.rst‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -617,8 +617,8 @@ Given a table as below::
617617

618618
from sqlalchemy import MetaData, Table, Column, Integer
619619

620-
meta = MetaData()
621-
users_table = Table('users', meta,
620+
metadata_obj = MetaData()
621+
users_table = Table('users', metadata_obj,
622622
Column('id', Integer, primary_key=True),
623623
Column('name', String(50))
624624
)
@@ -658,7 +658,7 @@ has been used to associate a series of
658658
engine::
659659

660660
engine = create_engine('sqlite:///file.db')
661-
meta.bind = engine
661+
metadata_obj.bind = engine
662662
result = users_table.select().execute()
663663
for row in result:
664664
# ....
@@ -734,7 +734,7 @@ to render under different schema names without any changes.
734734
Given a table::
735735

736736
user_table = Table(
737-
'user', metadata,
737+
'user', metadata_obj,
738738
Column('id', Integer, primary_key=True),
739739
Column('name', String(50))
740740
)
@@ -1756,10 +1756,10 @@ may be used::
17561756

17571757
connection = engine.raw_connection()
17581758
try:
1759-
cursor = connection.cursor()
1760-
cursor.callproc("my_procedure", ['x', 'y', 'z'])
1761-
results = list(cursor.fetchall())
1762-
cursor.close()
1759+
cursor_obj = connection.cursor()
1760+
cursor_obj.callproc("my_procedure", ['x', 'y', 'z'])
1761+
results = list(cursor_obj.fetchall())
1762+
cursor_obj.close()
17631763
connection.commit()
17641764
finally:
17651765
connection.close()
@@ -1772,12 +1772,12 @@ Multiple result set support is available from a raw DBAPI cursor using the
17721772

17731773
connection = engine.raw_connection()
17741774
try:
1775-
cursor = connection.cursor()
1776-
cursor.execute("select * from table1; select * from table2")
1777-
results_one = cursor.fetchall()
1778-
cursor.nextset()
1779-
results_two = cursor.fetchall()
1780-
cursor.close()
1775+
cursor_obj = connection.cursor()
1776+
cursor_obj.execute("select * from table1; select * from table2")
1777+
results_one = cursor_obj.fetchall()
1778+
cursor_obj.nextset()
1779+
results_two = cursor_obj.fetchall()
1780+
cursor_obj.close()
17811781
finally:
17821782
connection.close()
17831783

0 commit comments

Comments
 (0)