diff options
author | Mike Bayer <mike_mp@zzzcomputing.com> | 2013-11-12 23:50:25 -0500 |
---|---|---|
committer | Mike Bayer <mike_mp@zzzcomputing.com> | 2013-11-12 23:50:25 -0500 |
commit | 93bfaec9038566740a2742d801547c6e7dcb79d9 (patch) | |
tree | 1300d2f511f129e260510f7118785d26db8cc79b | |
parent | e05e78b800d4c1161235bb70ecdfe7caa34ef663 (diff) | |
parent | fe1d64473896b1e8abeb8ddb966447632c057321 (diff) | |
download | sqlalchemy-93bfaec9038566740a2742d801547c6e7dcb79d9.tar.gz |
Merge branch 'master' into rel_0_9
23 files changed, 163 insertions, 152 deletions
diff --git a/doc/build/changelog/changelog_01.rst b/doc/build/changelog/changelog_01.rst index 156599a13..0f66f99e4 100644 --- a/doc/build/changelog/changelog_01.rst +++ b/doc/build/changelog/changelog_01.rst @@ -182,7 +182,7 @@ :tickets: added a "mods" system which allows pluggable modules that modify/augment - core functionality, using the function "install_mods(*modnames)". + core functionality, using the function "install_mods(\*modnames)". .. change:: :tags: @@ -421,7 +421,7 @@ :tags: :tickets: - added *args, **kwargs pass-thru to engine.transaction(func) allowing easier + added \*args, \**kwargs pass-thru to engine.transaction(func) allowing easier creation of transactionalizing decorator functions .. change:: @@ -520,7 +520,7 @@ create_engine() now uses genericized parameters; host/hostname, db/dbname/database, password/passwd, etc. for all engine connections. makes - engine URIs much more "universal" + engine URIs much more "universal" .. change:: :tags: @@ -672,7 +672,7 @@ :tags: :tickets: - added 'get_session().invalidate(*obj)' method to objectstore, instances will + added 'get_session().invalidate(\*obj)' method to objectstore, instances will refresh() themselves upon the next attribute access. .. change:: @@ -805,7 +805,7 @@ :tags: :tickets: - added "refresh(*obj)" method to objectstore / Session to reload the attributes of + added "refresh(\*obj)" method to objectstore / Session to reload the attributes of any set of objects from the database unconditionally .. changelog:: @@ -856,14 +856,15 @@ two issues related to postgres, which doesnt want to give you the "lastrowid" since oids are deprecated: - * postgres database-side defaults that are on primary key cols *do* execute - explicitly beforehand, even though thats not the idea of a PassiveDefault. this is - because sequences on columns get reflected as PassiveDefaults, but need to be explicitly - executed on a primary key col so we know what we just inserted. - * if you did add a row that has a bunch of database-side defaults on it, - and the PassiveDefault thing was working the old way, i.e. they just execute on - the DB side, the "cant get the row back without an OID" exception that occurred - also will not happen unless someone (usually the ORM) explicitly asks for it. + + * postgres database-side defaults that are on primary key cols *do* execute + explicitly beforehand, even though thats not the idea of a PassiveDefault. this is + because sequences on columns get reflected as PassiveDefaults, but need to be explicitly + executed on a primary key col so we know what we just inserted. + * if you did add a row that has a bunch of database-side defaults on it, + and the PassiveDefault thing was working the old way, i.e. they just execute on + the DB side, the "cant get the row back without an OID" exception that occurred + also will not happen unless someone (usually the ORM) explicitly asks for it. .. change:: :tags: diff --git a/doc/build/changelog/changelog_02.rst b/doc/build/changelog/changelog_02.rst index 600dcc6eb..a2b0ab10b 100644 --- a/doc/build/changelog/changelog_02.rst +++ b/doc/build/changelog/changelog_02.rst @@ -170,7 +170,7 @@ :tags: :tickets: 287 - fix to using query.count() with distinct, **kwargs with SelectResults + fix to using query.count() with distinct, \**kwargs with SelectResults count() .. change:: diff --git a/doc/build/changelog/changelog_03.rst b/doc/build/changelog/changelog_03.rst index e47da340a..05e10e664 100644 --- a/doc/build/changelog/changelog_03.rst +++ b/doc/build/changelog/changelog_03.rst @@ -695,7 +695,7 @@ :tags: orm :tickets: - session.get() and session.load() propagate **kwargs through to + session.get() and session.load() propagate \**kwargs through to query .. change:: @@ -979,7 +979,7 @@ :tickets: query strings in unicode URLs get keys encoded to ascii - for **kwargs compat + for \**kwargs compat .. change:: :tags: sql @@ -1113,7 +1113,7 @@ :tickets: support for SSL arguments given as inline within URL query string, - prefixed with "ssl_", courtesy terjeros@gmail.com. + prefixed with "ssl\_", courtesy terjeros@gmail.com. .. change:: :tags: <schemaname>, mysql @@ -1266,7 +1266,7 @@ :tags: sql :tickets: - the "else_" parameter to the case statement now properly works when + the "else\_" parameter to the case statement now properly works when set to zero. .. change:: @@ -1279,16 +1279,15 @@ and a new one returned with additional criterion added. The new methods include: - filter() - applies select criterion to the query - filter_by() - applies "by"-style criterion to the query - avg() - return the avg() function on the given column - join() - join to a property (or across a list of properties) - outerjoin() - like join() but uses LEFT OUTER JOIN - limit()/offset() - apply LIMIT/OFFSET - range-based access which applies limit/offset: - session.query(Foo)[3:5] - distinct() - apply DISTINCT - list() - evaluate the criterion and return results + * filter() - applies select criterion to the query + * filter_by() - applies "by"-style criterion to the query + * avg() - return the avg() function on the given column + * join() - join to a property (or across a list of properties) + * outerjoin() - like join() but uses LEFT OUTER JOIN + * limit()/offset() - apply LIMIT/OFFSET range-based access + which applies limit/offset: session.query(Foo)[3:5] + * distinct() - apply DISTINCT + * list() - evaluate the criterion and return results no incompatible changes have been made to Query's API and no methods have been deprecated. Existing methods like select(), select_by(), @@ -1321,7 +1320,7 @@ :tags: orm :tickets: - strings and columns can also be sent to the *args of instances() + strings and columns can also be sent to the \*args of instances() where those exact result columns will be part of the result tuples. .. change:: @@ -1488,7 +1487,7 @@ :tags: mysql :tickets: - added a catchall **kwargs to MSString, to help reflection of + added a catchall \**kwargs to MSString, to help reflection of obscure types (like "varchar() binary" in MS 4.0) .. change:: @@ -1526,7 +1525,7 @@ :tickets: fixed argument passing to straight textual execute() on engine, - connection. can handle *args or a list instance for positional, **kwargs + connection. can handle \*args or a list instance for positional, \**kwargs or a dict instance for named args, or a list of list or dicts to invoke executemany() @@ -2364,7 +2363,7 @@ :tags: engine/pool :tickets: - create_engine() reworked to be strict about incoming **kwargs. all keyword + create_engine() reworked to be strict about incoming \**kwargs. all keyword arguments must be consumed by one of the dialect, connection pool, and engine constructors, else a TypeError is thrown which describes the full set of invalid kwargs in relation to the selected dialect/pool/engine configuration. diff --git a/doc/build/changelog/changelog_04.rst b/doc/build/changelog/changelog_04.rst index e1acfe4c0..61ea28c11 100644 --- a/doc/build/changelog/changelog_04.rst +++ b/doc/build/changelog/changelog_04.rst @@ -83,14 +83,11 @@ :tickets: Added "add()" and "add_all()" to scoped_session - methods. Workaround for 0.4.7: + methods. Workaround for 0.4.7:: - from sqlalchemy.orm.scoping import ScopedSession,\ - instrument - setattr( - ScopedSession, "add", instrument("add")) - setattr( - ScopedSession, "add_all", instrument("add_all")) + from sqlalchemy.orm.scoping import ScopedSession, instrument + setattr(ScopedSession, "add", instrument("add")) + setattr(ScopedSession, "add_all", instrument("add_all")) .. change:: :tags: orm @@ -344,7 +341,7 @@ :tags: orm :tickets: - set-based collections |=, -=, ^= and &= are stricter about + set-based collections \|=, -=, ^= and &= are stricter about their operands and only operate on sets, frozensets or subclasses of the collection type. Previously, they would accept any duck-typed set. @@ -424,7 +421,7 @@ :tags: ext :tickets: - set-based association proxies |=, -=, ^= and &= are + set-based association proxies \|=, -=, ^= and &= are stricter about their operands and only operate on sets, frozensets or other association proxies. Previously, they would accept any duck-typed set. @@ -541,11 +538,12 @@ The new approach also automatically allows eager loads to work for subclasses, if they are present, for - example + example:: + sess.query(Company).options( eagerload_all( - )) + to load Company objects, their employees, and the 'machines' collection of employees who happen to be Engineers. A "with_polymorphic" Query option should be @@ -561,7 +559,7 @@ is not carved in stone just yet: _values() and _from_self(). We'd like feedback on these. - - _values(*columns) is given a list of column + - _values(\*columns) is given a list of column expressions, and returns a new Query that only returns those columns. When evaluated, the return value is a list of tuples just like when using @@ -594,7 +592,7 @@ :tickets: query.order_by() and query.group_by() will accept - multiple arguments using *args (like select() + multiple arguments using \*args (like select() already does). .. change:: @@ -1780,7 +1778,7 @@ :tags: ext :tickets: - '+', '*', '+=' and '*=' support for association + '+', '*', '+=' and '\*=' support for association proxied lists. .. change:: @@ -1866,7 +1864,7 @@ :tickets: added new flag to String and create_engine(), - assert_unicode=(True|False|'warn'|None). Defaults to `False` or `None` on + assert_unicode=(True|False|'warn'\|None). Defaults to `False` or `None` on create_engine() and String, `'warn'` on the Unicode type. When `True`, results in all unicode conversion operations raising an exception when a non-unicode bytestring is passed as a bind parameter. 'warn' results @@ -2010,8 +2008,8 @@ :tickets: 908 mapped classes which extend "object" and do not provide an - __init__() method will now raise TypeError if non-empty *args - or **kwargs are present at instance construction time (and are + __init__() method will now raise TypeError if non-empty \*args + or \**kwargs are present at instance construction time (and are not consumed by any extensions such as the scoped_session mapper), consistent with the behavior of normal Python classes @@ -2818,10 +2816,10 @@ :tickets: Improvements and fixes on Firebird reflection: - . FBDialect now mimics OracleDialect, regarding case-sensitivity of TABLE and - COLUMN names (see 'case_sensitive remotion' topic on this current file). - . FBDialect.table_names() doesn't bring system tables (ticket:796). - . FB now reflects Column's nullable property correctly. + * FBDialect now mimics OracleDialect, regarding case-sensitivity of TABLE and + COLUMN names (see 'case_sensitive remotion' topic on this current file). + * FBDialect.table_names() doesn't bring system tables (ticket:796). + * FB now reflects Column's nullable property correctly. .. change:: :tags: @@ -2963,7 +2961,7 @@ :tags: :tickets: - Changed the API for the in_ operator. in_() now accepts a single argument + Changed the API for the in\_ operator. in_() now accepts a single argument that is a sequence of values or a selectable. The old API of passing in values as varargs still works but is deprecated. @@ -3246,7 +3244,7 @@ :tags: :tickets: - Tidied up what ends up in your namespace when you 'from sqlalchemy import *': + Tidied up what ends up in your namespace when you 'from sqlalchemy import \*': .. change:: :tags: @@ -3816,10 +3814,10 @@ is represented by more than one column, when using the ORM. Objects of the new type are fully functional in query expressions, comparisons, query.get() clauses, etc. and act as though they are regular single-column - scalars... except they're not! Use the function composite(cls, *columns) + scalars... except they're not! Use the function composite(cls, \*columns) inside of the mapper's "properties" dict, and instances of cls will be created/mapped to a single attribute, comprised of the values correponding - to *columns. + to \*columns. .. change:: :tags: orm @@ -3912,7 +3910,7 @@ :tickets: All "type" keyword arguments, such as those to bindparam(), column(), - Column(), and func.<something>(), renamed to "type_". Those objects still + Column(), and func.<something>(), renamed to "type\_". Those objects still name their "type" attribute as "type". .. change:: diff --git a/doc/build/changelog/changelog_05.rst b/doc/build/changelog/changelog_05.rst index 0bcc1aa3f..debcc29fd 100644 --- a/doc/build/changelog/changelog_05.rst +++ b/doc/build/changelog/changelog_05.rst @@ -1093,7 +1093,7 @@ Session.scalar() now converts raw SQL strings to text() the same way Session.execute() does and accepts same - alternative **kw args. + alternative \**kw args. .. change:: :tags: orm @@ -1506,7 +1506,7 @@ :tickets: ColumnProperty (and front-end helpers such as ``deferred``) no - longer ignores unknown **keyword arguments. + longer ignores unknown \**keyword arguments. .. change:: :tags: orm @@ -2903,7 +2903,7 @@ :tags: orm :tickets: - The RowTuple object returned by Query(*cols) now features + The RowTuple object returned by Query(\*cols) now features keynames which prefer mapped attribute names over column keys, column keys over column names, i.e. Query(Class.foo, Class.bar) will have names "foo" and "bar" even if those are @@ -2984,7 +2984,7 @@ :tickets: 1140 class.someprop.in_() raises NotImplementedError pending the - implementation of "in_" for relation + implementation of "in\_" for relation .. change:: :tags: orm @@ -3499,7 +3499,7 @@ Unicode, UnicodeText types now set "assert_unicode" and "convert_unicode" by default, but accept overriding - **kwargs for these values. + \**kwargs for these values. .. change:: :tags: sql diff --git a/doc/build/changelog/changelog_06.rst b/doc/build/changelog/changelog_06.rst index c7f4dcdea..18d61019a 100644 --- a/doc/build/changelog/changelog_06.rst +++ b/doc/build/changelog/changelog_06.rst @@ -1013,7 +1013,7 @@ New Query methods: query.label(name), query.as_scalar(), return the query's statement as a scalar subquery with /without label; - query.with_entities(*ent), replaces the SELECT list of + query.with_entities(\*ent), replaces the SELECT list of the query with new entities. Roughly equivalent to a generative form of query.values() which accepts mapped entities as well as column @@ -1246,7 +1246,7 @@ :tags: sql :tickets: - Added type_coerce(expr, type_) expression element. + Added type_coerce(expr, type\_) expression element. Treats the given expression as the given type when evaluating expressions and processing result rows, but does not affect the generation of SQL, other than an anonymous @@ -3005,7 +3005,7 @@ :tags: orm :tickets: - Query gains an add_columns(*columns) method which is a multi- + Query gains an add_columns(\*columns) method which is a multi- version of add_column(col). add_column(col) is future deprecated. @@ -3641,9 +3641,9 @@ :tags: declarative :tickets: - DeclarativeMeta exclusively uses cls.__dict__ (not dict_) + DeclarativeMeta exclusively uses cls.__dict__ (not dict\_) as the source of class information; _as_declarative exclusively - uses the dict_ passed to it as the source of class information + uses the dict\_ passed to it as the source of class information (which when using DeclarativeMeta is cls.__dict__). This should in theory make it easier for custom metaclasses to modify the state passed into _as_declarative. @@ -4190,10 +4190,10 @@ * Passing a single list of elements to eagerload(), eagerload_all(), contains_eager(), lazyload(), defer(), and undefer() instead of multiple positional - *args is deprecated. + \*args is deprecated. * Passing a single list of elements to query.order_by(), query.group_by(), query.join(), or query.outerjoin() - instead of multiple positional *args is deprecated. + instead of multiple positional \*args is deprecated. * query.iterate_instances() is removed. Use query.instances(). * Query.query_from_parent() is removed. Use the sqlalchemy.orm.with_parent() function to produce a @@ -4363,7 +4363,7 @@ "expr != expr" can be very expensive, and it's preferred that the user not issue in_() if the list is empty, instead simply not querying, or modifying the criterion - as appropriate for more complex situations. + as appropriate for more complex situations. .. change:: :tags: sql @@ -4523,7 +4523,7 @@ * the "connection" argument from engine.transaction() and engine.run_callable() is removed - Connection itself now has those methods. All four methods accept - *args and **kwargs which are passed to the given callable, + \*args and \**kwargs which are passed to the given callable, as well as the operating connection. .. change:: @@ -4570,11 +4570,13 @@ Removed public mutability from Index and Constraint objects: - - ForeignKeyConstraint.append_element() - - Index.append_column() - - UniqueConstraint.append_column() - - PrimaryKeyConstraint.add() - - PrimaryKeyConstraint.remove() + + * ForeignKeyConstraint.append_element() + * Index.append_column() + * UniqueConstraint.append_column() + * PrimaryKeyConstraint.add() + * PrimaryKeyConstraint.remove() + These should be constructed declaratively (i.e. in one construction). @@ -4682,18 +4684,22 @@ The signature of the "on" callable passed to DDL() and DDLElement() is revised as follows: - "ddl" - the DDLElement object itself. - "event" - the string event name. - "target" - previously "schema_item", the Table or - MetaData object triggering the event. - "connection" - the Connection object in use for the operation. - **kw - keyword arguments. In the case of MetaData before/after - create/drop, the list of Table objects for which - CREATE/DROP DDL is to be issued is passed as the kw - argument "tables". This is necessary for metadata-level - DDL that is dependent on the presence of specific tables. + ddl + the DDLElement object itself + event + the string event name. + target + previously "schema_item", the Table or MetaData object triggering the event. + connection + the Connection object in use for the operation. + \**kw + keyword arguments. In the case of MetaData before/after + create/drop, the list of Table objects for which + CREATE/DROP DDL is to be issued is passed as the kw + argument "tables". This is necessary for metadata-level + DDL that is dependent on the presence of specific tables. - - the "schema_item" attribute of DDL has been renamed to + The "schema_item" attribute of DDL has been renamed to "target". .. change:: diff --git a/doc/build/changelog/changelog_07.rst b/doc/build/changelog/changelog_07.rst index 0570ee0bf..35e443bf2 100644 --- a/doc/build/changelog/changelog_07.rst +++ b/doc/build/changelog/changelog_07.rst @@ -11,7 +11,7 @@ :tickets: 2851 :versions: 0.8.3, 0.9.0b1 - The regexp used by the :func:`.url.make_url` function now parses + The regexp used by the :func:`~.sqlalchemy.engine.url.make_url` function now parses ipv6 addresses, e.g. surrounded by brackets. .. change:: @@ -1188,12 +1188,12 @@ :tickets: Added some decent context managers - to Engine, Connection: + to Engine, Connection:: with engine.begin() as conn: <work with conn in a transaction> - and: + and:: with engine.connect() as conn: <work with conn> @@ -1778,10 +1778,10 @@ polymorphic_on now accepts many new kinds of values: - - standalone expressions that aren't + * standalone expressions that aren't otherwise mapped - - column_property() objects - - string names of any column_property() + * column_property() objects + * string names of any column_property() or attribute name of a mapped Column The docs include an example using @@ -2174,7 +2174,7 @@ Enhanced the instrumentation in the ORM to support Py3K's new argument style of "required kw arguments", - i.e. fn(a, b, *, c, d), fn(a, b, *args, c, d). + i.e. fn(a, b, \*, c, d), fn(a, b, \*args, c, d). Argument signatures of mapped object's __init__ method will be preserved, including required kw rules. @@ -2196,8 +2196,9 @@ Fixed a variety of synonym()-related regressions from 0.6: - - making a synonym against a synonym now works. - - synonyms made against a relationship() can + + * making a synonym against a synonym now works. + * synonyms made against a relationship() can be passed to query.join(), options sent to query.options(), passed by name to query.with_parent(). @@ -2306,19 +2307,20 @@ :tickets: 2239 New declarative features: - - __declare_last__() method, establishes an event - listener for the class method that will be called - when mappers are completed with the final "configure" - step. - - __abstract__ flag. The class will not be mapped - at all when this flag is present on the class. - - New helper classes ConcreteBase, AbstractConcreteBase. - Allow concrete mappings using declarative which automatically - set up the "polymorphic_union" when the "configure" - mapper step is invoked. - - The mapper itself has semi-private methods that allow - the "with_polymorphic" selectable to be assigned - to the mapper after it has already been configured. + + * __declare_last__() method, establishes an event + listener for the class method that will be called + when mappers are completed with the final "configure" + step. + * __abstract__ flag. The class will not be mapped + at all when this flag is present on the class. + * New helper classes ConcreteBase, AbstractConcreteBase. + Allow concrete mappings using declarative which automatically + set up the "polymorphic_union" when the "configure" + mapper step is invoked. + * The mapper itself has semi-private methods that allow + the "with_polymorphic" selectable to be assigned + to the mapper after it has already been configured. .. change:: :tags: orm @@ -2856,7 +2858,7 @@ :tickets: 2206 Fixed bug whereby adaptation of old append_ddl_listener() - function was passing unexpected **kw through + function was passing unexpected \**kw through to the Table event. Table gets no kws, the MetaData event in 0.6 would get "tables=somecollection", this behavior is preserved. @@ -4321,7 +4323,7 @@ :tickets: 1069 Query.distinct() now accepts column expressions - as *args, interpreted by the Postgresql dialect + as \*args, interpreted by the Postgresql dialect as DISTINCT ON (<expr>). .. change:: @@ -4421,7 +4423,7 @@ :tickets: 1069 select.distinct() now accepts column expressions - as *args, interpreted by the Postgresql dialect + as \*args, interpreted by the Postgresql dialect as DISTINCT ON (<expr>). Note this was already available via passing a list to the `distinct` keyword argument to select(). @@ -4431,7 +4433,7 @@ :tickets: select.prefix_with() accepts multiple expressions - (i.e. *expr), 'prefix' keyword argument to select() + (i.e. \*expr), 'prefix' keyword argument to select() accepts a list or tuple. .. change:: diff --git a/doc/build/changelog/migration_04.rst b/doc/build/changelog/migration_04.rst index 236bfc3ce..cb53534af 100644 --- a/doc/build/changelog/migration_04.rst +++ b/doc/build/changelog/migration_04.rst @@ -749,10 +749,10 @@ Just like it says: b = bindparam('foo', type_=String) -in_ Function Changed to Accept Sequence or Selectable ------------------------------------------------------ +in\_ Function Changed to Accept Sequence or Selectable +------------------------------------------------------ -The in_ function now takes a sequence of values or a +The in\_ function now takes a sequence of values or a selectable as its sole argument. The previous API of passing in values as positional arguments still works, but is now deprecated. This means that diff --git a/doc/build/changelog/migration_07.rst b/doc/build/changelog/migration_07.rst index 5bc7e74aa..95d6cb7db 100644 --- a/doc/build/changelog/migration_07.rst +++ b/doc/build/changelog/migration_07.rst @@ -288,8 +288,7 @@ events back to the owning parent or parents. The extension includes an approach for scalar database values, such as those managed by ``PickleType``, ``postgresql.ARRAY``, or other custom ``MutableType`` classes, as well as an approach -for ORM "composites", those configured using :ref:`composite() -<mapper_composite>`_. +for ORM "composites", those configured using :func:`~.sqlalchemy.orm.composite`. .. seealso:: diff --git a/doc/build/core/types.rst b/doc/build/core/types.rst index a40363135..47145837f 100644 --- a/doc/build/core/types.rst +++ b/doc/build/core/types.rst @@ -9,7 +9,7 @@ SQLAlchemy provides abstractions for most common database data types, and a mechanism for specifying your own custom data types. The methods and attributes of type objects are rarely used directly. -Type objects are supplied to :class:`~sqlalchemy.Table` definitions +Type objects are supplied to :class:`~sqlalchemy.schema.Table` definitions and can be supplied as type hints to `functions` for occasions where the database driver returns an incorrect type. @@ -24,7 +24,7 @@ the database driver returns an incorrect type. SQLAlchemy will use the ``Integer`` and ``String(32)`` type information when issuing a ``CREATE TABLE`` statement and will use it again when reading back rows ``SELECTed`` from the database. -Functions that accept a type (such as :func:`~sqlalchemy.Column`) will +Functions that accept a type (such as :func:`~sqlalchemy.schema.Column`) will typically accept a type class or instance; ``Integer`` is equivalent to ``Integer()`` with no construction arguments in this case. diff --git a/doc/build/orm/query.rst b/doc/build/orm/query.rst index d83bdb6ae..5e31d710f 100644 --- a/doc/build/orm/query.rst +++ b/doc/build/orm/query.rst @@ -13,7 +13,7 @@ For an in-depth introduction to querying with the SQLAlchemy ORM, please see the The Query Object ---------------- -:class:`~.Query` is produced in terms of a given :class:`~.Session`, using the :func:`~.Query.query` function:: +:class:`~.Query` is produced in terms of a given :class:`~.Session`, using the :meth:`~.Session.query` method:: q = session.query(SomeMappedClass) diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index 7289d5783..04c677cde 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -328,7 +328,7 @@ connect it to the :class:`~sqlalchemy.orm.session.Session` using This custom-made :class:`~sqlalchemy.orm.session.Session` class will create new :class:`~sqlalchemy.orm.session.Session` objects which are bound to our database. Other transactional characteristics may be defined when calling -:func:`~.sessionmaker` as well; these are described in a later +:class:`~.sessionmaker` as well; these are described in a later chapter. Then, whenever you need to have a conversation with the database, you instantiate a :class:`~sqlalchemy.orm.session.Session`:: @@ -628,7 +628,7 @@ class: <User(name='fred', fullname='Fred Flinstone', password='blah')> fred You can control the names of individual column expressions using the -:meth:`~.CompareMixin.label` construct, which is available from +:meth:`~.ColumnElement.label` construct, which is available from any :class:`.ColumnElement`-derived object, as well as any class attribute which is mapped to one (such as ``User.name``): @@ -646,7 +646,7 @@ is mapped to one (such as ``User.name``): The name given to a full entity such as ``User``, assuming that multiple entities are present in the call to :meth:`~.Session.query`, can be controlled using -:class:`~.orm.aliased` : +:func:`~.sqlalchemy.orm.aliased` : .. sourcecode:: python+sql diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index 06c4fca62..386cd7621 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -812,7 +812,8 @@ class Connectable(object): "object directly, i.e. :meth:`.Table.create`, " ":meth:`.Index.create`, :meth:`.MetaData.create_all`") def create(self, entity, **kwargs): - """Emit CREATE statements for the given schema entity.""" + """Emit CREATE statements for the given schema entity. + """ raise NotImplementedError() @@ -821,7 +822,8 @@ class Connectable(object): "object directly, i.e. :meth:`.Table.drop`, " ":meth:`.Index.drop`, :meth:`.MetaData.drop_all`") def drop(self, entity, **kwargs): - """Emit DROP statements for the given schema entity.""" + """Emit DROP statements for the given schema entity. + """ raise NotImplementedError() diff --git a/lib/sqlalchemy/ext/compiler.py b/lib/sqlalchemy/ext/compiler.py index 703475de7..6d97351ca 100644 --- a/lib/sqlalchemy/ext/compiler.py +++ b/lib/sqlalchemy/ext/compiler.py @@ -238,7 +238,7 @@ A synopsis is as follows: class timestamp(ColumnElement): type = TIMESTAMP() -* :class:`~sqlalchemy.sql.expression.FunctionElement` - This is a hybrid of a +* :class:`~sqlalchemy.sql.functions.FunctionElement` - This is a hybrid of a ``ColumnElement`` and a "from clause" like object, and represents a SQL function or stored procedure type of call. Since most databases support statements along the line of "SELECT FROM <some function>" diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index 3b67f767b..855841408 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -1295,9 +1295,9 @@ class SessionEvents(event.Events): :param session: The target :class:`.Session`. :param previous_transaction: The :class:`.SessionTransaction` - transactional marker object which was just closed. The current - :class:`.SessionTransaction` for the given :class:`.Session` is - available via the :attr:`.Session.transaction` attribute. + transactional marker object which was just closed. The current + :class:`.SessionTransaction` for the given :class:`.Session` is + available via the :attr:`.Session.transaction` attribute. .. versionadded:: 0.7.3 diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index c9e7d444b..1b83f3fb8 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -921,7 +921,7 @@ class Query(object): @_generative() def with_session(self, session): - """Return a :class:`Query` that will use the given :class:`.Session`. + """Return a :class:`.Query` that will use the given :class:`.Session`. """ @@ -1285,7 +1285,7 @@ class Query(object): """apply a HAVING criterion to the query and return the newly resulting :class:`.Query`. - :meth:`having` is used in conjunction with :meth:`group_by`. + :meth:`~.Query.having` is used in conjunction with :meth:`~.Query.group_by`. HAVING criterion makes it possible to use filters on aggregate functions like COUNT, SUM, AVG, MAX, and MIN, eg.:: @@ -1463,7 +1463,7 @@ class Query(object): q = session.query(User).join(Address) - The above calling form of :meth:`.join` will raise an error if + The above calling form of :meth:`~.Query.join` will raise an error if either there are no foreign keys between the two entities, or if there are multiple foreign key linkages between them. In the above calling form, :meth:`~.Query.join` is called upon to @@ -1632,7 +1632,7 @@ class Query(object): A special two-argument calling form of the form ``target, onclause`` is also accepted. :param aliased=False: If True, indicate that the JOIN target should be - anonymously aliased. Subsequent calls to :class:`~.Query.filter` + anonymously aliased. Subsequent calls to :meth:`~.Query.filter` and similar will adapt the incoming criterion to the target alias, until :meth:`~.Query.reset_joinpoint` is called. :param from_joinpoint=False: When using ``aliased=True``, a setting @@ -2573,7 +2573,7 @@ class Query(object): which normally occurs upon :meth:`.Session.commit` or can be forced by using :meth:`.Session.expire_all`. Accessing an expired object whose row has been deleted will invoke a SELECT to locate the - row; when the row is not found, an :class:`.ObjectDeletedError` + row; when the row is not found, an :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. * The :meth:`.MapperEvents.before_delete` and diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py index f0b23111c..8296be60a 100644 --- a/lib/sqlalchemy/orm/relationships.py +++ b/lib/sqlalchemy/orm/relationships.py @@ -732,7 +732,7 @@ class RelationshipProperty(StrategizedProperty): @util.memoized_property def mapper(self): """The target :class:`.Mapper` referred to by this - :class:`.RelationshipProperty.Comparator. + :class:`.RelationshipProperty.Comparator`. This is the "target" or "remote" side of the :func:`.relationship`. @@ -1372,7 +1372,8 @@ class RelationshipProperty(StrategizedProperty): def table(self): """Return the selectable linked to this :class:`.RelationshipProperty` object's target - :class:`.Mapper`.""" + :class:`.Mapper`. + """ return self.target def do_init(self): diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py index 4f3dbba36..59506edea 100644 --- a/lib/sqlalchemy/sql/compiler.py +++ b/lib/sqlalchemy/sql/compiler.py @@ -198,7 +198,8 @@ class Compiled(object): @util.deprecated("0.7", ":class:`.Compiled` objects now compile " "within the constructor.") def compile(self): - """Produce the internal string representation of this element.""" + """Produce the internal string representation of this element. + """ pass def _execute_on_connection(self, connection, multiparams, params): diff --git a/lib/sqlalchemy/sql/ddl.py b/lib/sqlalchemy/sql/ddl.py index 72ef07732..f239cdf0f 100644 --- a/lib/sqlalchemy/sql/ddl.py +++ b/lib/sqlalchemy/sql/ddl.py @@ -195,7 +195,7 @@ class DDLElement(Executable, _DDLCompiles): If the callable returns a true value, the DDL statement will be executed. - :param state: any value which will be passed to the callable_ + :param state: any value which will be passed to the callable\_ as the ``state`` keyword argument. .. seealso:: diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py index b651aef50..7bf543a61 100644 --- a/lib/sqlalchemy/sql/schema.py +++ b/lib/sqlalchemy/sql/schema.py @@ -364,7 +364,8 @@ class Table(SchemaItem, TableClause): @util.deprecated('0.9', 'Use ``table.schema.quote``') def quote_schema(self): """Return the value of the ``quote_schema`` flag passed - to this :class:`.Table`.""" + to this :class:`.Table`. + """ return self.schema.quote diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py index 550e250f1..4fcf06290 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -246,11 +246,11 @@ class FromClause(Selectable): :param column: the target :class:`.ColumnElement` to be matched :param require_embedded: only return corresponding columns for - the given :class:`.ColumnElement`, if the given - :class:`.ColumnElement` is actually present within a sub-element - of this :class:`.FromClause`. Normally the column will match if - it merely shares a common ancestor with one of the exported - columns of this :class:`.FromClause`. + the given :class:`.ColumnElement`, if the given :class:`.ColumnElement` + is actually present within a sub-element + of this :class:`.FromClause`. Normally the column will match if + it merely shares a common ancestor with one of the exported + columns of this :class:`.FromClause`. """ @@ -756,7 +756,7 @@ class Join(FromClause): ON table_b_1.id = table_c_1.b_id ) ON table_a_1.id = table_b_1.a_id - The standalone :func:`experssion.alias` function as well as the + The standalone :func:`~.expression.alias` function as well as the base :meth:`.FromClause.alias` method also support the ``flat=True`` argument as a no-op, so that the argument can be passed to the ``alias()`` method of any selectable. @@ -1352,7 +1352,8 @@ class SelectBase(Executable, FromClause): "'autocommit' flag.") def autocommit(self): """return a new selectable with the 'autocommit' flag set to - True.""" + True. + """ self._execution_options = \ self._execution_options.union({'autocommit': True}) diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py index 01d918120..82ab3d556 100644 --- a/lib/sqlalchemy/sql/sqltypes.py +++ b/lib/sqlalchemy/sql/sqltypes.py @@ -645,9 +645,9 @@ class DateTime(_DateAffinity, TypeEngine): """Construct a new :class:`.DateTime`. :param timezone: boolean. If True, and supported by the - backend, will produce 'TIMESTAMP WITH TIMEZONE'. For backends - that don't support timezone aware timestamps, has no - effect. + backend, will produce 'TIMESTAMP WITH TIMEZONE'. For backends + that don't support timezone aware timestamps, has no + effect. """ self.timezone = timezone diff --git a/lib/sqlalchemy/sql/type_api.py b/lib/sqlalchemy/sql/type_api.py index 5d81e4a0c..12babd2c2 100644 --- a/lib/sqlalchemy/sql/type_api.py +++ b/lib/sqlalchemy/sql/type_api.py @@ -594,7 +594,7 @@ class TypeDecorator(TypeEngine): coerce_to_is_types = (util.NoneType, ) """Specify those Python types which should be coerced at the expression level to "IS <constant>" when compared using ``==`` (and same for - ``IS NOT`` in conjunction with ``!=``. + ``IS NOT`` in conjunction with ``!=``. For most SQLAlchemy types, this includes ``NoneType``, as well as ``bool``. |