| # -*- coding: UTF-8 -*- |
| # |
| # Licensed to the Apache Software Foundation (ASF) under one |
| # or more contributor license agreements. See the NOTICE file |
| # distributed with this work for additional information |
| # regarding copyright ownership. The ASF licenses this file |
| # to you under the Apache License, Version 2.0 (the |
| # "License"); you may not use this file except in compliance |
| # with the License. You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, |
| # software distributed under the License is distributed on an |
| # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| # KIND, either express or implied. See the License for the |
| # specific language governing permissions and limitations |
| # under the License. |
| |
| import os.path |
| from urlparse import urlsplit |
| |
| from trac.config import BoolOption, ConfigSection, Option |
| from trac.core import Component, ComponentManager, ExtensionPoint, implements, \ |
| ComponentMeta |
| from trac.db.api import TransactionContextManager, QueryContextManager, \ |
| DatabaseManager |
| from trac.perm import IPermissionRequestor, PermissionSystem |
| from trac.util import get_pkginfo, lazy |
| from trac.util.compat import sha1 |
| from trac.util.text import to_unicode, unicode_quote |
| from trac.versioncontrol import RepositoryManager |
| from trac.web.href import Href |
| |
| from multiproduct.api import MultiProductSystem, ISupportMultiProductEnvironment |
| from multiproduct.cache import lru_cache, default_keymap |
| from multiproduct.config import Configuration |
| from multiproduct.dbcursor import BloodhoundConnectionWrapper, BloodhoundIterableCursor, \ |
| ProductEnvContextManager |
| from multiproduct.model import Product |
| |
| import trac.env |
| |
| |
| class ComponentEnvironmentContext(object): |
| def __init__(self, env, component): |
| self._env = env |
| self._component = component |
| |
| def __enter__(self): |
| self._old_env = self._component.env |
| self._env.component_activated(self._component) |
| return self |
| |
| def __exit__(self, type, value, traceback): |
| self._old_env.component_activated(self._component) |
| |
| |
| class Environment(trac.env.Environment): |
| """Bloodhound environment manager |
| |
| This class is intended as monkey-patch replacement for |
| trac.env.Environment. Required database access methods/properties |
| are replaced to provide global view of the database in contrast |
| to ProductEnvironment that features per-product view of the database |
| (in the context of selected product). |
| |
| :param path: the absolute path to the Trac environment |
| :param create: if `True`, the environment is created and |
| populated with default data; otherwise, the |
| environment is expected to already exist. |
| :param options: A list of `(section, name, value)` tuples that |
| define configuration options |
| """ |
| |
| multi_product_support_components = ExtensionPoint(ISupportMultiProductEnvironment) |
| |
| @property |
| def global_setup_participants(self): |
| """If multi product schema is enabled, return only setup participants |
| that implement ISupportMultiProduct. Otherwise, all setup participants |
| are considered global. |
| """ |
| if self._multiproduct_schema_enabled: |
| all_participants = self.setup_participants |
| multiproduct_aware = set(self.multi_product_support_components) |
| priority = lambda x: 0 if isinstance(x, MultiProductSystem) else 10 |
| |
| return sorted( |
| (c for c in all_participants if c in multiproduct_aware), |
| key=priority |
| ) |
| else: |
| return self.setup_participants |
| |
| @property |
| def product_setup_participants(self): |
| """If multi product schema is enabled, return setup participants that |
| need to be instantiated for each product env. Otherwise, return an |
| empty list. |
| """ |
| if self._multiproduct_schema_enabled: |
| all_participants = self.setup_participants |
| multiproduct_aware = set(self.multi_product_support_components) |
| return [ |
| c for c in all_participants if c not in multiproduct_aware |
| ] |
| else: |
| return [] |
| |
| def __init__(self, path, create=False, options=[]): |
| # global environment w/o parent, set these two before super.__init__ |
| # as database access can take place within trac.env.Environment |
| self.parent = None |
| self.product = None |
| |
| # `trac.env.Environment.__init__` is not invoked as creation is handled differently |
| # from base implementation - different setup participants are invoked when creating |
| # global environment. |
| ComponentManager.__init__(self) |
| |
| self.path = path |
| self.systeminfo = [] |
| self._href = self._abs_href = None |
| |
| self._multiproduct_schema_enabled = False |
| |
| if create: |
| self.create(options) |
| else: |
| self.verify() |
| self.setup_config() |
| |
| # invoke `IEnvironmentSetupParticipant.environment_created` for all |
| # global setup participants |
| if create: |
| for participant in self.global_setup_participants: |
| with ComponentEnvironmentContext(self, participant): |
| participant.environment_created() |
| |
| @property |
| def db_query(self): |
| return ProductEnvContextManager(super(Environment, self).db_query, self) \ |
| if self._multiproduct_schema_enabled else self.db_direct_query |
| |
| @property |
| def db_transaction(self): |
| return ProductEnvContextManager(super(Environment, self).db_transaction, self) \ |
| if self._multiproduct_schema_enabled else self.db_direct_transaction |
| |
| @property |
| def db_direct_query(self): |
| return ProductEnvContextManager(super(Environment, self).db_query) |
| |
| @property |
| def db_direct_transaction(self): |
| return ProductEnvContextManager(super(Environment, self).db_transaction) |
| |
| def all_product_envs(self): |
| return [ProductEnvironment(self, product) for product in Product.select(self)] |
| |
| def needs_upgrade(self): |
| """Return whether the environment needs to be upgraded.""" |
| def needs_upgrade_in_env(participant, env): |
| with ComponentEnvironmentContext(env, participant): |
| with env.db_query as db: |
| if participant.environment_needs_upgrade(db): |
| self.log.warn("component %s.%s requires environment upgrade in environment %s...", |
| participant.__module__, participant.__class__.__name__, |
| env) |
| return True |
| if any(needs_upgrade_in_env(participant, self) |
| for participant in self.global_setup_participants): |
| return True |
| |
| # until schema is multi product aware, product environments can't (and shouldn't) be |
| # instantiated |
| if self._multiproduct_schema_enabled: |
| if any(needs_upgrade_in_env(participant, env) |
| for env in [self] + self.all_product_envs() |
| for participant in self.product_setup_participants): |
| return True |
| return False |
| |
| def upgrade(self, backup=False, backup_dest=None): |
| """Upgrade database. |
| |
| :param backup: whether or not to backup before upgrading |
| :param backup_dest: name of the backup file |
| :return: whether the upgrade was performed |
| """ |
| def upgrader_for_env(participant, env): |
| with ComponentEnvironmentContext(env, participant): |
| with env.db_query as db: |
| if participant.environment_needs_upgrade(db): |
| self.log.info( |
| "%s.%s needs upgrade in environment %s...", |
| participant.__module__, |
| participant.__class__.__name__, |
| env) |
| return env, participant |
| |
| def upgraders_for_product_envs(): |
| upgraders = (upgrader_for_env(participant, env) |
| for participant in self.product_setup_participants |
| for env in [self] + self.all_product_envs()) |
| return [u for u in upgraders if u] |
| |
| # first enumerate components that are multi product aware and |
| # require upgrade in global environment |
| global_upgraders = [upgrader_for_env(participant, self) |
| for participant in self.global_setup_participants] |
| global_upgraders = [u for u in global_upgraders if u] |
| product_upgraders = None |
| if not global_upgraders and self._multiproduct_schema_enabled: |
| # if no upgrades required in global environment, enumerate |
| # required upgrades for product environments |
| product_upgraders = upgraders_for_product_envs() |
| |
| if not global_upgraders + (product_upgraders or []): |
| return False |
| |
| if backup: |
| try: |
| self.backup(backup_dest) |
| except Exception, e: |
| raise trac.env.BackupError(e) |
| |
| def execute_upgrades(upgraders_list): |
| for env, participant in upgraders_list: |
| self.log.info("%s.%s upgrading in environment %s...", |
| participant.__module__, |
| participant.__class__.__name__, |
| env) |
| with ComponentEnvironmentContext(env, participant): |
| with env.db_transaction as db: |
| participant.upgrade_environment(db) |
| # Database schema may have changed, so close all connections |
| DatabaseManager(env).shutdown() |
| |
| # execute global upgrades first, product environment upgrades next |
| execute_upgrades(global_upgraders) |
| if product_upgraders is None and self._multiproduct_schema_enabled: |
| product_upgraders = upgraders_for_product_envs() |
| if product_upgraders: |
| execute_upgrades(product_upgraders) |
| return True |
| |
| def get_version(self, db=None, initial=False): |
| """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. |
| """ |
| rows = self.db_direct_query(""" |
| SELECT value FROM system WHERE name='%sdatabase_version' |
| """ % ('initial_' if initial else '')) |
| return (rows and int(rows[0][0])) or 0 |
| |
| def enable_multiproduct_schema(self, enable=True): |
| self._multiproduct_schema_enabled = enable |
| BloodhoundIterableCursor.cache_reset() |
| |
| # replace trac.env.Environment with Environment |
| trac.env.Environment = Environment |
| |
| |
| # this must follow the monkey patch (trac.env.Environment) above, otherwise |
| # trac.test.EnvironmentStub will not be correct as the class will derive from |
| # not replaced trac.env.Environment |
| import trac.test |
| |
| class EnvironmentStub(trac.test.EnvironmentStub): |
| """Bloodhound test environment stub |
| |
| This class replaces trac.test.EnvironmentStub and extends it with parent |
| and product properties (same case as with the Environment). |
| """ |
| def __init__(self, default_data=False, enable=None, disable=None, |
| path=None, destroying=False): |
| self.parent = None |
| self.product = None |
| |
| self._multiproduct_schema_enabled = False |
| |
| super(EnvironmentStub, self).__init__(default_data=False, |
| enable=enable, disable=disable, |
| path=path, destroying=destroying) |
| if default_data: |
| self.reset_db(default_data) |
| |
| @staticmethod |
| def enable_component_in_config(env, cls): |
| """Keep track of enabled state in configuration as well |
| during test runs. This is closer to reality than |
| inherited `enable_component` method. |
| """ |
| env.config['components'].set(env._component_name(cls), 'enabled') |
| env.enabled.clear() |
| env.components.pop(cls, None) |
| try: |
| del env._rules |
| except AttributeError: |
| pass |
| # FIXME: Shall we ? |
| #env.config.save() |
| |
| @staticmethod |
| def disable_component_in_config(env, component): |
| """Keep track of disabled state in configuration as well |
| during test runs. This is closer to reality than |
| inherited `disable_component` method. |
| """ |
| if isinstance(component, type): |
| cls = component |
| else: |
| cls = component.__class__ |
| env.config['components'].set(env._component_name(cls), 'disabled') |
| env.enabled.clear() |
| env.components.pop(cls, None) |
| try: |
| del env._rules |
| except AttributeError: |
| pass |
| env.config.save() |
| |
| def reset_db(self, default_data=None): |
| multiproduct_schema = self._multiproduct_schema_enabled |
| self._multiproduct_schema_enabled = False |
| try: |
| super(EnvironmentStub, self).reset_db(default_data=default_data) |
| finally: |
| self._multiproduct_schema_enabled = multiproduct_schema |
| |
| # replace trac.test.EnvironmentStub |
| trac.test.EnvironmentStub = EnvironmentStub |
| |
| |
| class ProductEnvironment(Component, ComponentManager): |
| """Bloodhound product-aware environment manager. |
| |
| Bloodhound encapsulates access to product resources stored inside a |
| Trac environment via product environments. They are compatible lightweight |
| irepresentations of top level environment. |
| |
| Product environments contain among other things: |
| |
| * configuration key-value pairs stored in the database, |
| * product-aware clones of the wiki and ticket attachments files, |
| |
| Product environments do not have: |
| |
| * product-specific templates and plugins, |
| * a separate database |
| * active participation in database upgrades and other setup tasks |
| |
| See https://issues.apache.org/bloodhound/wiki/Proposals/BEP-0003 |
| """ |
| |
| class __metaclass__(ComponentMeta): |
| |
| def select_global_env(f): |
| """Replaces env with env.parent where appropriate""" |
| # Keep the signature of __call__ method |
| def __call__(self, env, *args, **kwargs): |
| g_env = env.parent if isinstance(env, |
| ProductEnvironment) else env |
| return f(self, g_env, *args, **kwargs) |
| __call__.clear = f.clear |
| |
| return __call__ |
| |
| def product_env_keymap(args, kwds, kwd_mark): |
| # Remove meta-reference to self (i.e. product env class) |
| args = args[1:] |
| try: |
| product = kwds['product'] |
| except KeyError: |
| # Product provided as positional argument |
| if isinstance(args[1], Product): |
| args = (args[0], args[1].prefix) + args[2:] |
| else: |
| # Product supplied as keyword argument |
| if isinstance(product, Product): |
| kwds['product'] = product.prefix |
| return default_keymap(args, kwds, kwd_mark) |
| |
| @select_global_env |
| @lru_cache(maxsize=100, keymap=product_env_keymap) |
| def __call__(self, *args, **kwargs): |
| """Return an existing instance if there is a hit |
| in the global LRU cache, otherwise create a new instance. |
| """ |
| return ComponentMeta.__call__(self, *args, **kwargs) |
| |
| del product_env_keymap, select_global_env |
| |
| implements(trac.env.ISystemInfoProvider, IPermissionRequestor) |
| |
| setup_participants = ExtensionPoint(trac.env.IEnvironmentSetupParticipant) |
| multi_product_support_components = ExtensionPoint(ISupportMultiProductEnvironment) |
| |
| @classmethod |
| def clear_env_cache(cls): |
| cls.__metaclass__.__call__.clear() |
| |
| @property |
| def product_setup_participants(self): |
| return [ |
| component for component in self.setup_participants |
| if component not in self.multi_product_support_components |
| ] |
| |
| components_section = ConfigSection('components', |
| """This section is used to enable or disable components |
| provided by plugins, as well as by Trac itself. |
| |
| See also: TracIni , TracPlugins |
| """) |
| |
| @property |
| def shared_plugins_dir(): |
| """Product environments may not add plugins. |
| """ |
| return '' |
| |
| _base_url = Option('trac', 'base_url', '', |
| """Reference URL for the Trac deployment. |
| |
| This is the base URL that will be used when producing |
| documents that will be used outside of the web browsing |
| context, like for example when inserting URLs pointing to Trac |
| resources in notification e-mails.""", doc_domain='multiproduct') |
| |
| @property |
| def base_url(self): |
| base_url = self._base_url |
| if base_url == self.parent.base_url: |
| return '' |
| return base_url |
| |
| _base_url_for_redirect = BoolOption('trac', 'use_base_url_for_redirect', |
| False, |
| """Optionally use `[trac] base_url` for redirects. |
| |
| In some configurations, usually involving running Trac behind |
| a HTTP proxy, Trac can't automatically reconstruct the URL |
| that is used to access it. You may need to use this option to |
| force Trac to use the `base_url` setting also for |
| redirects. This introduces the obvious limitation that this |
| environment will only be usable when accessible from that URL, |
| as redirects are frequently used. ''(since 0.10.5)''""", |
| doc_domain='multiproduct') |
| |
| @property |
| def project_name(self): |
| """Name of the product. |
| """ |
| return self.product.name |
| |
| @property |
| def project_description(self): |
| """Short description of the product. |
| """ |
| return self.product.description |
| |
| @property |
| def project_url(self): |
| """URL of the main project web site, usually the website in |
| which the `base_url` resides. This is used in notification |
| e-mails. |
| """ |
| # FIXME: Should products have different values i.e. config option ? |
| return self.parent.project_url |
| |
| project_admin = Option('project', 'admin', '', |
| """E-Mail address of the product's leader / administrator.""", |
| doc_domain='multiproduct') |
| |
| @property |
| def project_footer(self): |
| """Page footer text (right-aligned). |
| """ |
| # FIXME: Should products have different values i.e. config option ? |
| return self.parent.project_footer |
| |
| project_icon = Option('project', 'icon', 'common/trac.ico', |
| """URL of the icon of the product.""", doc_domain='multiproduct') |
| |
| log_type = Option('logging', 'log_type', 'inherit', |
| """Logging facility to use. |
| |
| Should be one of (`inherit`, `none`, `file`, `stderr`, |
| `syslog`, `winlog`).""", doc_domain='multiproduct') |
| |
| log_file = Option('logging', 'log_file', 'trac.log', |
| """If `log_type` is `file`, this should be a path to the |
| log-file. Relative paths are resolved relative to the `log` |
| directory of the environment.""", doc_domain='multiproduct') |
| |
| log_level = Option('logging', 'log_level', 'DEBUG', |
| """Level of verbosity in log. |
| |
| Should be one of (`CRITICAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`).""", |
| doc_domain='multiproduct') |
| |
| log_format = Option('logging', 'log_format', None, |
| """Custom logging format. |
| |
| If nothing is set, the following will be used: |
| |
| Trac[$(module)s] $(levelname)s: $(message)s |
| |
| In addition to regular key names supported by the Python |
| logger library (see |
| http://docs.python.org/library/logging.html), one could use: |
| |
| - $(path)s the path for the current environment |
| - $(basename)s the last path component of the current environment |
| - $(project)s the project name |
| |
| Note the usage of `$(...)s` instead of `%(...)s` as the latter form |
| would be interpreted by the ConfigParser itself. |
| |
| Example: |
| `($(thread)d) Trac[$(basename)s:$(module)s] $(levelname)s: $(message)s` |
| |
| ''(since 0.10.5)''""", doc_domain='multiproduct') |
| |
| def __init__(self, env, product, create=False): |
| """Initialize the product environment. |
| |
| :param env: the global Trac environment |
| :param product: product prefix or an instance of |
| multiproduct.model.Product |
| """ |
| if not isinstance(env, trac.env.Environment): |
| cls = self.__class__ |
| raise TypeError("Initializer must be called with " \ |
| "trac.env.Environment instance as first argument " \ |
| "(got %s instance instead)" % |
| (cls.__module__ + '.' + cls.__name__, )) |
| |
| ComponentManager.__init__(self) |
| |
| if isinstance(product, Product): |
| if product._env is not env: |
| raise ValueError("Product's environment mismatch") |
| elif isinstance(product, basestring): |
| products = Product.select(env, where={'prefix': product}) |
| if len(products) == 1 : |
| product = products[0] |
| else: |
| env.log.debug("Products for '%s' : %s", |
| product, products) |
| raise LookupError("Missing product %s" % (product,)) |
| |
| self.parent = env |
| self.product = product |
| self.systeminfo = [] |
| |
| self.setup_config() |
| |
| # when creating product environment, invoke `IEnvironmentSetupParticipant.environment_created` |
| # for all setup participants that don't support multi product environments |
| if create: |
| for participant in self.product_setup_participants: |
| with ComponentEnvironmentContext(self, participant): |
| participant.environment_created() |
| |
| def __getitem__(self, cls): |
| if issubclass(cls, trac.env.Environment): |
| return self.parent |
| elif cls is self.__class__: |
| return self |
| else: |
| return ComponentManager.__getitem__(self, cls) |
| |
| def __getattr__(self, attrnm): |
| """Forward attribute access request to parent environment. |
| |
| Initially this will affect the following members of |
| `trac.env.Environment` class: |
| |
| system_info_providers, secure_cookies, project_admin_trac_url, |
| get_system_info, get_version, get_templates_dir, get_templates_dir, |
| get_log_dir, backup |
| """ |
| try: |
| if attrnm in ('parent', '_rules'): |
| raise AttributeError |
| return getattr(self.parent, attrnm) |
| except AttributeError: |
| raise AttributeError("'%s' object has no attribute '%s'" % |
| (self.__class__.__name__, attrnm)) |
| |
| def __repr__(self): |
| return "<%s %s at %s>" % (self.__class__.__name__, |
| repr(self.product.prefix), |
| hex(id(self))) |
| |
| @lazy |
| def path(self): |
| """The subfolder `./products/<product prefix>` relative to the |
| top-level directory of the global environment will be the root of |
| product file system area. |
| """ |
| folder = os.path.join(self.parent.path, 'products', self.product.prefix) |
| if not os.path.exists(folder): |
| os.makedirs(folder) |
| return folder |
| |
| # IPermissionRequestor methods |
| def get_permission_actions(self): |
| """Implement the product-specific `PRODUCT_ADMIN` meta permission. |
| """ |
| actions = set() |
| permsys = PermissionSystem(self) |
| for requestor in permsys.requestors: |
| if requestor is not self and requestor is not permsys: |
| for action in requestor.get_permission_actions() or []: |
| if isinstance(action, tuple): |
| actions.add(action[0]) |
| else: |
| actions.add(action) |
| # PermissionSystem's method was not invoked |
| actions.add('EMAIL_VIEW') |
| # FIXME: should not be needed, JIC better double check |
| actions.discard('TRAC_ADMIN') |
| return [('PRODUCT_ADMIN', list(actions))] |
| |
| # ISystemInfoProvider methods |
| |
| # Same as parent environment's . Avoid duplicated code |
| component_activated = trac.env.Environment.component_activated.im_func |
| _component_name = trac.env.Environment._component_name.im_func |
| _component_rules = trac.env.Environment._component_rules |
| enable_component = trac.env.Environment.enable_component.im_func |
| get_known_users = trac.env.Environment.get_known_users.im_func |
| get_repository = trac.env.Environment.get_repository.im_func |
| |
| is_component_enabled_local = trac.env.Environment.is_component_enabled.im_func |
| |
| def is_enabled(self, cls): |
| """Return whether the given component class is enabled.""" |
| modtime = max(self.config.get_lock_file_mtime(), |
| self.config._lastmtime) |
| if modtime > self._config_mtime: |
| self.enabled.clear() |
| try: |
| del self._rules |
| except AttributeError: |
| pass |
| # FIXME : Improve cache hits by tracking global env last mtime |
| self.parent.enabled.clear() |
| try: |
| del self.parent._rules |
| except AttributeError: |
| pass |
| self._config_mtime = modtime |
| return super(ProductEnvironment, self).is_enabled(cls) |
| |
| def is_component_enabled(self, cls): |
| """Implemented to only allow activation of components already |
| activated in the global environment that are in turn 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. |
| """ |
| if cls is self.__class__: |
| # Prevent lookups in parent env ... will always fail |
| return True |
| # FIXME : Maybe checking for ComponentManager is too drastic |
| elif issubclass(cls, ComponentManager): |
| # Avoid clashes with overridden Environment's options |
| return False |
| elif self.parent[cls] is None: |
| return False |
| return self.is_component_enabled_local(cls) |
| |
| def get_db_cnx(self): |
| """Return a database connection from the connection pool |
| |
| :deprecated: Use :meth:`db_transaction` or :meth:`db_query` instead |
| |
| `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: |
| ... |
| |
| |
| `db_query` for obtaining a `db` database connection which can |
| be used for performing SELECT queries only:: |
| |
| with env.db_query as db: |
| ... |
| """ |
| return BloodhoundConnectionWrapper(self.parent.get_db_cnx(), self) |
| |
| @property |
| def db_exc(self): |
| """Return an object (typically a module) containing all the |
| backend-specific exception types as attributes, named |
| according to the Python Database API |
| (http://www.python.org/dev/peps/pep-0249/). |
| |
| To catch a database exception, use the following pattern:: |
| |
| try: |
| with env.db_transaction as db: |
| ... |
| except env.db_exc.IntegrityError, e: |
| ... |
| """ |
| # exception types same as in global environment |
| return self.parent.db_exc |
| |
| def with_transaction(self, db=None): |
| """Decorator for transaction functions :deprecated: |
| """ |
| raise NotImplementedError('Deprecated method') |
| |
| def get_read_db(self): |
| """Return a database connection for read purposes :deprecated: |
| |
| See `trac.db.api.get_read_db` for detailed documentation. |
| """ |
| return BloodhoundConnectionWrapper(self.parent.get_read_db(), self) |
| |
| @property |
| def db_query(self): |
| """Return a context manager 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 ..."): |
| ... |
| |
| :warning: after a `with env.db_query as db` block, though the |
| `db` variable is still available, you shouldn't use it as it |
| might have been closed when exiting the context, if this |
| context was the outermost context (`db_query` or |
| `db_transaction`). |
| """ |
| return ProductEnvContextManager(QueryContextManager(self.parent), self) |
| |
| @property |
| def db_transaction(self): |
| """Return a context manager 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. |
| |
| 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 ...") |
| |
| :warning: after a `with env.db_transaction` as db` block, |
| though the `db` variable is still available, you shouldn't |
| use it as it might have been closed when exiting the |
| context, if this context was the outermost context |
| (`db_query` or `db_transaction`). |
| """ |
| return ProductEnvContextManager(TransactionContextManager(self.parent), self) |
| |
| def shutdown(self, tid=None): |
| """Close the environment.""" |
| RepositoryManager(self).shutdown(tid) |
| # FIXME: Shared DB so IMO this should not happen ... at least not here |
| #DatabaseManager(self).shutdown(tid) |
| if tid is None: |
| self.log.removeHandler(self._log_handler) |
| self._log_handler.flush() |
| self._log_handler.close() |
| del self._log_handler |
| |
| def create(self, options=[]): |
| """Placeholder for compatibility when trying to create the basic |
| directory structure of the environment, etc ... |
| |
| This method does nothing at all. |
| """ |
| # TODO: Handle options args |
| |
| def setup_config(self): |
| """Load the configuration object. |
| """ |
| import trac.config |
| |
| parent_path = MultiProductSystem(self.parent).product_config_parent |
| if parent_path and os.path.isfile(parent_path): |
| parents = [trac.config.Configuration(parent_path)] |
| else: |
| parents = [self.parent.config] |
| self.config = Configuration(self.parent, self.product.prefix, parents) |
| self._config_mtime = 0 |
| self.setup_log() |
| |
| def setup_log(self): |
| """Initialize the logging sub-system.""" |
| from trac.log import logger_handler_factory |
| logtype = self.log_type |
| logfile = self.log_file |
| format = self.log_format |
| |
| self.parent.log.debug("Log type '%s' for product '%s'", |
| logtype, self.product.prefix) |
| |
| # Force logger inheritance on identical configuration |
| if (logtype, logfile, format) == (self.parent.log_type, |
| self.parent.log_file, self.parent.log_format): |
| logtype = 'inherit' |
| |
| if logtype == 'inherit': |
| self.log = self.parent.log |
| self._log_handler = self.parent._log_handler |
| self.parent.log.info("Inheriting parent logger for product '%s'", |
| self.product.prefix) |
| else: |
| if logtype == 'file' and not os.path.isabs(logfile): |
| logfile = os.path.join(self.get_log_dir(), logfile) |
| logid = 'Trac.%s.%s' % \ |
| (sha1(self.parent.path).hexdigest(), self.product.prefix) |
| if format: |
| format = format.replace('$(', '%(') \ |
| .replace('%(path)s', self.path) \ |
| .replace('%(basename)s', os.path.basename(self.path)) \ |
| .replace('%(project)s', self.project_name) |
| self.log, self._log_handler = logger_handler_factory( |
| logtype, logfile, self.log_level, logid, format=format) |
| |
| from trac import core, __version__ as VERSION |
| self.log.info('-' * 32 + |
| ' product %s environment startup [Trac %s] ' + |
| '-' * 32, |
| self.product.prefix, |
| get_pkginfo(core).get('version', VERSION)) |
| |
| def needs_upgrade(self): |
| """Return whether the environment needs to be upgraded.""" |
| # Upgrades are handled by global environment |
| return False |
| |
| def upgrade(self, backup=False, backup_dest=None): |
| """Upgrade database. |
| |
| :param backup: whether or not to backup before upgrading |
| :param backup_dest: name of the backup file |
| :return: whether the upgrade was performed |
| """ |
| # Upgrades handled by global environment |
| return True |
| |
| @lazy |
| def href(self): |
| """The application root path""" |
| return Href(urlsplit(self.abs_href.base).path) |
| |
| @lazy |
| def abs_href(self): |
| """The application URL""" |
| if not self.base_url: |
| urlpattern = MultiProductSystem(self.parent).product_base_url |
| if not urlpattern: |
| self.log.warn("product_base_url option not set in " |
| "configuration, generated links may be " |
| "incorrect") |
| urlpattern = 'products/$(prefix)s' |
| envname = os.path.basename(self.parent.path) |
| prefix = unicode_quote(self.product.prefix, safe="") |
| name = unicode_quote(self.product.name, safe="") |
| url = urlpattern.replace('$(', '%(') \ |
| .replace('%(envname)s', envname) \ |
| .replace('%(prefix)s', prefix) \ |
| .replace('%(name)s', name) |
| if urlsplit(url).netloc: |
| # Absolute URLs |
| _abs_href = Href(url) |
| else: |
| # Relative URLs |
| parent_href = Href(self.parent.abs_href(), |
| path_safe="/!~*'()%", |
| query_safe="!~*'()%") |
| _abs_href = Href(parent_href(url)) |
| else: |
| _abs_href = Href(self.base_url) |
| return _abs_href |
| |
| # Multi-product API extensions |
| |
| @classmethod |
| def lookup_global_env(cls, env): |
| return env.parent if isinstance(env, ProductEnvironment) else env |
| |
| @classmethod |
| def lookup_env(cls, env, prefix=None, name=None): |
| """Instantiate environment according to product prefix or name |
| |
| @throws LookupError if no product matches neither prefix nor name |
| """ |
| if isinstance(env, ProductEnvironment): |
| global_env = env.parent |
| else: |
| global_env = env |
| |
| # FIXME: Update if multiproduct.dbcursor.GLOBAL_PRODUCT != '' |
| if not prefix and not name: |
| return global_env |
| elif isinstance(env, ProductEnvironment) and \ |
| env.product.prefix == prefix: |
| return env |
| if prefix: |
| try: |
| return ProductEnvironment(global_env, prefix) |
| except LookupError: |
| if not name: |
| raise |
| if name: |
| # Lookup product by name |
| products = Product.select(global_env, where={'name' : name}) |
| if products: |
| return ProductEnvironment(global_env, products[0]) |
| else: |
| raise LookupError("Missing product '%s'" % (name,)) |
| else: |
| raise LookupError("Mising product '%s'" % (prefix or name,)) |
| |
| @classmethod |
| def resolve_href(cls, to_env, at_env): |
| """Choose absolute or relative href when generating links to |
| a product (or global) environment. |
| |
| @param at_env: href expansion is taking place in the |
| scope of this environment |
| @param to_env: generated URLs point to resources in |
| this environment |
| """ |
| at_href = at_env.abs_href() |
| target_href = to_env.abs_href() |
| if urlsplit(at_href)[1] == urlsplit(target_href)[1]: |
| return to_env.href |
| else: |
| return to_env.abs_href |
| |
| |
| lookup_product_env = ProductEnvironment.lookup_env |
| resolve_product_href = ProductEnvironment.resolve_href |
| |
| # Override product-specific options |
| from multiproduct.config import ProductPermissionPolicyOption |
| PermissionSystem.policies.__class__ = ProductPermissionPolicyOption |
