- The new

  :meth"`repoze.bfg.configuration.Configurator.absolute_resource_spec`
  method resolves a potentially relative :term:`resource
  specification` string into an absolute version.

5 files changed, 49 insertions, 4 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 823bc7e38..283ae3db6 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -19,13 +19,20 @@ Features
   references are allowed (the work to allow dotted names isntead of
   object references everywhere has not yet been done, however).
 
-- The ``repoze.bfg.configuration.Configurator.maybe_dotted`` method
-  resolves a Python dotted name string supplied as its ``dotted``
-  argument to a global Python object.  If the value cannot be
-  resolved, a ``repoze.bfg.configuration.ConfigurationError`` is
+- The new ``repoze.bfg.configuration.Configurator.maybe_dotted``
+  method resolves a Python dotted name string supplied as its
+  ``dotted`` argument to a global Python object.  If the value cannot
+  be resolved, a ``repoze.bfg.configuration.ConfigurationError`` is
   raised.  If the value supplied as ``dotted`` is not a string, the
   value is returned unconditionally without any resolution attempted.
 
+- The new
+  ``repoze.bfg.configuration.Configurator.absolute_resource_spec``
+  method resolves a potentially relative "resource specification"
+  string into an absolute version.  If the value supplied as
+  ``relative_spec`` is not a string, the value is returned
+  unconditionally without any resolution attempted.
+
 Internal
 --------
 
diff --git a/docs/api/configuration.rst b/docs/api/configuration.rst
index ef0d7f631..36e4c5186 100644
--- a/docs/api/configuration.rst
+++ b/docs/api/configuration.rst
@@ -26,6 +26,8 @@
 
      .. automethod:: maybe_dotted
 
+     .. automethod:: absolute_resource_spec
+
      .. automethod:: setup_registry(settings=None, root_factory=None, authentication_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None)
 
      .. automethod:: add_renderer(name, factory)
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index f72a76e19..8daefa1b0 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -289,6 +289,11 @@ Minor Feature Additions
   raised.  If the value supplied as ``dotted`` is not a string, the
   value is returned unconditionally without any resolution attempted.
 
+- The new
+  :meth"`repoze.bfg.configuration.Configurator.absolute_resource_spec`
+  method resolves a potentially relative :term:`resource
+  specification` string into an absolute version.
+
 Backwards Incompatibilities
 ---------------------------
 
diff --git a/repoze/bfg/configuration.py b/repoze/bfg/configuration.py
index 59ae63989..89d287f14 100644
--- a/repoze/bfg/configuration.py
+++ b/repoze/bfg/configuration.py
@@ -325,6 +325,19 @@ class Configurator(object):
         constructor."""
         return self.name_resolver.maybe_resolve(dotted)
 
+    def absolute_resource_spec(self, relative_spec):
+        """ Resolve the potentially relative :term:`resource
+        specification` string passed as ``relative_spec`` into an
+        absolute resource specification string and return the string.
+        Use the ``package`` of this configurator as the package to
+        which the resource specification will be considered relative
+        when generating an absolute resource specification.  If the
+        provided ``relative_spec`` argument is already absolute, or if
+        the ``relative_spec`` is not a string, it is simply returned."""
+        if not isinstance(relative_spec, basestring):
+            return relative_spec
+        return self._make_spec(relative_spec)
+
     def setup_registry(self, settings=None, root_factory=None,
                        authentication_policy=None, authorization_policy=None,
                        renderers=DEFAULT_RENDERERS, debug_logger=None,
diff --git a/repoze/bfg/tests/test_configuration.py b/repoze/bfg/tests/test_configuration.py
index f11aee2c1..58a4a2eda 100644
--- a/repoze/bfg/tests/test_configuration.py
+++ b/repoze/bfg/tests/test_configuration.py
@@ -210,6 +210,24 @@ class ConfiguratorTests(unittest.TestCase):
         result = config.maybe_dotted(repoze.bfg.tests)
         self.assertEqual(result, repoze.bfg.tests)
 
+    def test_absolute_resource_spec_already_absolute(self):
+        import repoze.bfg.tests
+        config = self._makeOne(package=repoze.bfg.tests)
+        result = config.absolute_resource_spec('already:absolute')
+        self.assertEqual(result, 'already:absolute')
+
+    def test_absolute_resource_spec_notastring(self):
+        import repoze.bfg.tests
+        config = self._makeOne(package=repoze.bfg.tests)
+        result = config.absolute_resource_spec(None)
+        self.assertEqual(result, None)
+
+    def test_absolute_resource_spec_relative(self):
+        import repoze.bfg.tests
+        config = self._makeOne(package=repoze.bfg.tests)
+        result = config.absolute_resource_spec('templates')
+        self.assertEqual(result, 'repoze.bfg.tests:templates')
+
     def test_setup_registry_fixed(self):
         class DummyRegistry(object):
             def subscribers(self, events, name):