Class Environment

Parameters:

• path - the absolute path to the Trac environment
• create - if True, the environment is created and populated with default data; otherwise, the environment is expected to already exist.
• options - A list of (section, name, value) tuples that define configuration options

Overrides: object.__init__

Parameters:

• dest - Destination file; if not specified, the backup is stored in a file called db_name.trac_version.bak

Initialize additional member variables for components.

Every component activated through the Environment object gets three member variables: env (the environment object), config (the environment configuration) and log (a logger object).

Overrides: core.ComponentManager.component_activated

This section is used to enable or disable components provided by plugins, as well as by Trac itself. The component to enable/disable is specified via the name of the option. Whether its enabled is determined by the option value; setting the value to enabled or on will enable the component, any other value (typically disabled or off) will disable the component.

The option name is either the fully qualified name of the components or the module/package prefix of the component. The former enables/disables a specific component, while the latter enables/disables any component in the specified package/module.

Consider the following configuration snippet: {{{ [components] trac.ticket.report.ReportModule = disabled webadmin.* = enabled }}}

The first option tells Trac to disable the [wiki:TracReports report module]. The second option instructs Trac to enable all components in the webadmin package. Note that the trailing wildcard is required for module/package matching.

To view the list of active components, go to the ''Plugins'' page on ''About Trac'' (requires CONFIG_VIEW [wiki:TracPermissions permissions]).

See also: TracPlugins

Create the basic directory structure of the environment, initialize the database and populate the configuration file with default values.

If options contains ('inherit', 'file'), default values will not be loaded; they are expected to be provided by that file or other options.

Parameters:

• component - can be a class or an instance.

Overrides: core.ComponentManager.enable_component

Return a database connection from the connection pool

:deprecated: Use :meth:`db_transaction` or :meth:`db_query` instead.
             Removed in Trac 1.1.2.

`db_transaction` for obtaining the `db` database connection
which can be used for performing any query
(SELECT/INSERT/UPDATE/DELETE)::

   with env.db_transaction as db:
       ...

Note that within the block, you don't need to (and shouldn't)
call ``commit()`` yourself, the context manager will take care
of it (if it's the outermost such context manager on the
stack).


`db_query` for obtaining a `db` database connection which can
be used for performing SELECT queries only::

   with env.db_query as db:
       ...

Generator that yields information about all known users, i.e. users that have logged in to this Trac environment and possibly set their name and email.

This function generates one tuple for every user, of the form (username, name, email) ordered alpha-numerically by username.

Parameters:

• cnx - the database connection; if ommitted, a new connection is retrieved

Return a database connection for read purposes.

See `trac.db.api.get_read_db` for detailed documentation.

:deprecated: Use :meth:`db_query` instead.
             Will be removed in Trac 1.3.1.

Return the version control repository with the given name, or the default repository if None.

The standard way of retrieving repositories is to use the methods of RepositoryManager. This method is retained here for backward compatibility.

Parameters:

• reponame - the name of the repository
• authname - the user name for authorization (not used anymore, left here for compatibility with 0.11)

Return the current version of the database. If the optional argument initial is set to True, the version of the database used at the time of creation will be returned.

In practice, for database created before 0.11, this will return False which is "older" than any db version number.

Implemented to only allow activation of components that are not disabled in the configuration.

This is called by the ComponentManager base class when a component is about to be activated. If this method returns False, the component does not get activated. If it returns None, the component only gets activated if it is located in the plugins directory of the environment.

Overrides: core.ComponentManager.is_component_enabled

Parameters:

• backup - whether or not to backup before upgrading
• backup_dest - name of the backup file

Returns:

whether the upgrade was performed

anonymous_session_lifetime

Value:

<IntOption [trac] "anonymous_session_lifetime">

base_url_for_redirect

Value:

<BoolOption [trac] "use_base_url_for_redirect">

database_initial_version

Value:

<trac.util.lazy object at 0x7f41cce58390>

db_query

Return a context manager (~trac.db.api.QueryContextManager) which can be used to obtain a read-only database connection.

Example:

with env.db_query as db:
    cursor = db.cursor()
    cursor.execute("SELECT ...")
    for row in cursor.fetchall():
        ...

Note that a connection retrieved this way can be "called" directly in order to execute a query:

with env.db_query as db:
    for row in db("SELECT ..."):
        ...

If you don't need to manipulate the connection itself, this can even be simplified to:

for row in env.db_query("SELECT ..."):
    ...

Get Method:

unreachable.db_query(self) - Return a context manager (~trac.db.api.QueryContextManager) which can be used to obtain a read-only database connection.

db_transaction

Return a context manager (~trac.db.api.TransactionContextManager) which can be used to obtain a writable database connection.

Example:

with env.db_transaction as db:
    cursor = db.cursor()
    cursor.execute("UPDATE ...")

Upon successful exit of the context, the context manager will commit the transaction. In case of nested contexts, only the outermost context performs a commit. However, should an exception happen, any context manager will perform a rollback. You should not call commit() yourself within such block, as this will force a commit even if that transaction is part of a larger transaction.

Like for its read-only counterpart, you can directly execute a DML query on the db:

with env.db_transaction as db:
    db("UPDATE ...")

If you don't need to manipulate the connection itself, this can also be simplified to:

env.db_transaction("UPDATE ...")

Get Method:

unreachable.db_transaction(self) - Return a context manager (~trac.db.api.TransactionContextManager) which can be used to obtain a writable database connection.

env

Get Method:

unreachable.env(self) - Property returning the Environment object, which is often required for functions and methods that take a Component instance.

setup_participants

Get Method:

unreachable.extensions(component) - Return a list of components that declare to implement the extension point interface.

system_info_providers

Get Method:

unreachable.extensions(component) - Return a list of components that declare to implement the extension point interface.