From b49e181a8620198183b344f111fed15a950784d6 Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Mon, 21 Sep 2015 16:29:23 -0500 Subject: [PATCH] Docstring fixes for enginefacade There were some issues with the docstrings, and there are probably still issues that I didn't get around to fixing. Change-Id: I84d60621246776f77f9022f0f1d61792edccbfb0 --- oslo_db/sqlalchemy/enginefacade.py | 119 ++++++++++++++--------------- 1 file changed, 58 insertions(+), 61 deletions(-) diff --git a/oslo_db/sqlalchemy/enginefacade.py b/oslo_db/sqlalchemy/enginefacade.py index 9243351a..0985ea81 100644 --- a/oslo_db/sqlalchemy/enginefacade.py +++ b/oslo_db/sqlalchemy/enginefacade.py @@ -183,12 +183,12 @@ class _TransactionFactory(object): The configurational options given here act as **defaults** when the :class:`._TransactionFactory` is configured using - a :class:`.oslo.config.cfg.ConfigOpts` object; the options - present within the :class:`.oslo.config.cfg.ConfigOpts` **take + a :class:`oslo_config.cfg.ConfigOpts` object; the options + present within the :class:`oslo_config.cfg.ConfigOpts` **take precedence** versus the arguments passed here. By default, the :class:`._TransactionFactory` loads in the configuration from - :data:`oslo.config.cfg.CONF`, after applying the - :data:`oslo.db.options.database_opts` configurational defaults to it. + :data:`oslo_config.cfg.CONF`, after applying the + :data:`oslo_db.options.database_opts` configurational defaults to it. .. seealso:: @@ -206,7 +206,7 @@ class _TransactionFactory(object): Behavior here is the same as that of :meth:`._TransactionFactory.configure_defaults`, with the exception that values specified here will **supersede** those - setup in the :class:`.oslo.config.cfg.ConfigOpts` options. + setup in the :class:`oslo_config.cfg.ConfigOpts` options. .. seealso:: @@ -841,9 +841,8 @@ writer = _context_manager.writer class LegacyEngineFacade(object): """A helper class for removing of global engine instances from oslo.db. - .. deprecated:: - EngineFacade is deprecated. Please use - oslo.db.sqlalchemy.enginefacade for new development. + .. deprecated:: 1.12.0 + Please use :mod:`oslo_db.sqlalchemy.enginefacade` for new development. As a library, oslo.db can't decide where to store/when to create engine and sessionmaker instances, so this must be left for a target application. @@ -866,64 +865,62 @@ class LegacyEngineFacade(object): transactional context (i.e. it's not thread-safe). sessionmaker is a factory of sessions. + :param sql_connection: the connection string for the database to use + :type sql_connection: string + + :param slave_connection: the connection string for the 'slave' database + to use. If not provided, the master database + will be used for all operations. Note: this + is meant to be used for offloading of read + operations to asynchronously replicated slaves + to reduce the load on the master database. + :type slave_connection: string + + :param sqlite_fk: enable foreign keys in SQLite + :type sqlite_fk: bool + + :param autocommit: use autocommit mode for created Session instances + :type autocommit: bool + + :param expire_on_commit: expire session objects on commit + :type expire_on_commit: bool + + Keyword arguments: + + :keyword mysql_sql_mode: the SQL mode to be used for MySQL sessions. + (defaults to TRADITIONAL) + :keyword idle_timeout: timeout before idle sql connections are reaped + (defaults to 3600) + :keyword connection_debug: verbosity of SQL debugging information. + -1=Off, 0=None, 100=Everything (defaults + to 0) + :keyword max_pool_size: maximum number of SQL connections to keep open + in a pool (defaults to SQLAlchemy settings) + :keyword max_overflow: if set, use this value for max_overflow with + sqlalchemy (defaults to SQLAlchemy settings) + :keyword pool_timeout: if set, use this value for pool_timeout with + sqlalchemy (defaults to SQLAlchemy settings) + :keyword sqlite_synchronous: if True, SQLite uses synchronous mode + (defaults to True) + :keyword connection_trace: add python stack traces to SQL as comment + strings (defaults to False) + :keyword max_retries: maximum db connection retries during startup. + (setting -1 implies an infinite retry count) + (defaults to 10) + :keyword retry_interval: interval between retries of opening a sql + connection (defaults to 10) + :keyword thread_checkin: boolean that indicates that between each + engine checkin event a sleep(0) will occur to + allow other greenthreads to run (defaults to + True) + """ def __init__(self, sql_connection, slave_connection=None, sqlite_fk=False, autocommit=True, expire_on_commit=False, _conf=None, _factory=None, **kwargs): - """Initialize engine and sessionmaker instances. - - :param sql_connection: the connection string for the database to use - :type sql_connection: string - - :param slave_connection: the connection string for the 'slave' database - to use. If not provided, the master database - will be used for all operations. Note: this - is meant to be used for offloading of read - operations to asynchronously replicated slaves - to reduce the load on the master database. - :type slave_connection: string - - :param sqlite_fk: enable foreign keys in SQLite - :type sqlite_fk: bool - - :param autocommit: use autocommit mode for created Session instances - :type autocommit: bool - - :param expire_on_commit: expire session objects on commit - :type expire_on_commit: bool - - Keyword arguments: - - :keyword mysql_sql_mode: the SQL mode to be used for MySQL sessions. - (defaults to TRADITIONAL) - :keyword idle_timeout: timeout before idle sql connections are reaped - (defaults to 3600) - :keyword connection_debug: verbosity of SQL debugging information. - -1=Off, 0=None, 100=Everything (defaults - to 0) - :keyword max_pool_size: maximum number of SQL connections to keep open - in a pool (defaults to SQLAlchemy settings) - :keyword max_overflow: if set, use this value for max_overflow with - sqlalchemy (defaults to SQLAlchemy settings) - :keyword pool_timeout: if set, use this value for pool_timeout with - sqlalchemy (defaults to SQLAlchemy settings) - :keyword sqlite_synchronous: if True, SQLite uses synchronous mode - (defaults to True) - :keyword connection_trace: add python stack traces to SQL as comment - strings (defaults to False) - :keyword max_retries: maximum db connection retries during startup. - (setting -1 implies an infinite retry count) - (defaults to 10) - :keyword retry_interval: interval between retries of opening a sql - connection (defaults to 10) - :keyword thread_checkin: boolean that indicates that between each - engine checkin event a sleep(0) will occur to - allow other greenthreads to run (defaults to - True) - """ warnings.warn( "EngineFacade is deprecated; please use " - "oslo.db.sqlalchemy.enginefacade", + "oslo_db.sqlalchemy.enginefacade", exception.OsloDBDeprecationWarning, stacklevel=2) @@ -997,7 +994,7 @@ class LegacyEngineFacade(object): """Initialize EngineFacade using oslo.config config instance options. :param conf: oslo.config config instance - :type conf: oslo.config.cfg.ConfigOpts + :type conf: oslo_config.cfg.ConfigOpts :param sqlite_fk: enable foreign keys in SQLite :type sqlite_fk: bool