[core] add a global configuration system

Author: Emanuele Palazzetti

ddtrace/__init__.py

@@ -2,11 +2,13 @@
 from .pin import Pin
 from .span import Span
 from .tracer import Tracer
+from .configuration import Config
 
 __version__ = '0.11.0'
 
-# a global tracer instance
+# a global tracer instance with integration settings
 tracer = Tracer()
+config = Config()
 
 __all__ = [
     'patch',
@@ -15,4 +17,5 @@
     'Span',
     'tracer',
     'Tracer',
+    'config',
 ]

ddtrace/configuration.py

@@ -0,0 +1,36 @@
+class ConfigException(Exception):
+    """Configuration exception when an integration that is not available
+    is called in the `Config` object.
+    """
+    pass
+
+
+class Config(object):
+    """Configuration object that exposes an API to set and retrieve
+    global settings for each integration. All integrations must use
+    this instance to register their defaults, so that they're public
+    available and can be updated by users.
+    """
+    def __init__(self):
+        # use a dict as underlying storing mechanism
+        self._config = {}
+
+    def __getattr__(self, name):
+        try:
+            return self._config[name]
+        except KeyError as e:
+            raise ConfigException(
+                'Integration "{}" is not registered in this configuration'.format(e.message)
+            )
+
+    def _add(self, integration, settings):
+        """Internal API that registers an integration with given default
+        settings.
+
+        :param str integration: The integration name (i.e. `requests`)
+        :param dict settings: A dictionary that contains integration settings;
+            to preserve immutability of these values, the dictionary is copied
+            since it contains integration defaults.
+        """
+
+        self._config[integration] = settings.copy()

tests/test_configuration.py

@@ -0,0 +1,45 @@
+from unittest import TestCase
+
+from nose.tools import eq_, ok_, assert_raises
+
+from ddtrace import config as global_config
+from ddtrace.configuration import Config, ConfigException
+
+
+class ConfigTestCase(TestCase):
+    """Test the `Configuration` class that stores integration settings"""
+    def setUp(self):
+        self.config = Config()
+
+    def test_registration(self):
+        # ensure an integration can register a new list of settings
+        settings = {
+            'distributed_tracing': True,
+        }
+        self.config._add('requests', settings)
+        ok_(self.config.requests['distributed_tracing'] is True)
+
+    def test_settings_copy(self):
+        # ensure that once an integration is registered, a copy
+        # of the settings is stored to avoid side-effects
+        settings = {
+            'distributed_tracing': True,
+        }
+        self.config._add('requests', settings)
+
+        settings['distributed_tracing'] = False
+        ok_(self.config.requests['distributed_tracing'] is True)
+
+    def test_missing_integration(self):
+        # ensure a meaningful exception is raised when an integration
+        # that is not available is retrieved in the configuration
+        # object
+        with assert_raises(ConfigException) as e:
+            self.config.new_integration['some_key']
+
+        ok_(isinstance(e.exception, ConfigException))
+        eq_(e.exception.message, 'Integration "new_integration" is not registered in this configuration')
+
+    def test_global_configuration(self):
+        # ensure a global configuration is available in the `ddtrace` module
+        ok_(isinstance(global_config, Config))