Commits

Mike Bayer committed bbb2972

- [feature] Added a new system
for registration of new dialects in-process
without using an entrypoint. See the
docs for "Registering New Dialects".
[ticket:2462]

Comments (0)

Files changed (7)

     [ticket:2454].  Courtesy Jeff Dairiki
     also in 0.7.7.
 
-- sql
+- engine
+  - [feature] Added a new system
+    for registration of new dialects in-process
+    without using an entrypoint.  See the
+    docs for "Registering New Dialects".
+    [ticket:2462]
+
   - [bug] The names of the columns on the
     .c. attribute of a select().apply_labels()
     is now based on <tablename>_<colkey> instead
     that have a distinctly named .key.
     [ticket:2397]
 
+
+- sql
   - [feature] The Inspector object can now be 
     acquired using the new inspect() service,
     part of [ticket:2208]

doc/build/core/connections.rst

 its resources until all other usages of that resource are closed as well, including
 that any ongoing transactions are rolled back or committed.
 
+Registering New Dialects
+========================
+
+The :func:`.create_engine` function call locates the given dialect
+using setuptools entrypoints.   These entry points can be established
+for third party dialects within the setup.py script.  For example,
+to create a new dialect "foodialect://", the steps are as follows:
+
+1. Create a package called ``foodialect``.
+2. The package should have a module containing the dialect class,
+   which is typically a subclass of :class:`sqlalchemy.engine.default.DefaultDialect`.
+   In this example let's say it's called ``FooDialect`` and its module is accessed
+   via ``foodialect.dialect``.
+3. The entry point can be established in setup.py as follows::
+
+      entry_points="""
+      [sqlalchemy.dialects]
+      foodialect = foodialect.dialect:FooDialect
+      """
+
+If the dialect is providing support for a particular DBAPI on top of
+an existing SQLAlchemy-supported database, the name can be given 
+including a database-qualification.  For example, if ``FooDialect``
+were in fact a MySQL dialect, the entry point could be established like this::
+
+      entry_points="""
+      [sqlalchemy.dialects]
+      mysql.foodialect = foodialect.dialect:FooDialect
+      """
+
+The above entrypoint would then be accessed as ``create_engine("mysql+foodialect://")``.
+
+Registering Dialects In-Process
+-------------------------------
+
+SQLAlchemy also allows a dialect to be registered within the current process, bypassing
+the need for separate installation.   Use the ``register()`` function as follows::
+
+    from sqlalchemy.dialects import register
+    registry.register("mysql.foodialect", "myapp.dialect", "MyMySQLDialect")
+
+The above will respond to ``create_engine("mysql+foodialect://")`` and load the
+``MyMySQLDialect`` class from the ``myapp.dialect`` module.
+
+The ``register()`` function is new in SQLAlchemy 0.8.
+
 Connection / Engine API
 =======================
 

lib/sqlalchemy/dialects/__init__.py

     'sqlite',
     'sybase',
     )
+
+from sqlalchemy import util
+
+def _auto_fn(name):
+    """default dialect importer.
+    
+    plugs into the :class:`.PluginLoader`
+    as a first-hit system.
+    
+    """
+    if "." in name:
+        dialect, driver = name.split(".")
+    else:
+        dialect = name
+        driver = "base"
+    try:
+        module = __import__('sqlalchemy.dialects.%s' % (dialect, )).dialects
+    except ImportError:
+        return None
+
+    module = getattr(module, dialect)
+    if hasattr(module, driver):
+        module = getattr(module, driver)
+        return lambda: module.dialect
+    else:
+        return None
+
+registry = util.PluginLoader("sqlalchemy.dialects", auto_fn=_auto_fn)

lib/sqlalchemy/engine/url.py

 
 import re, urllib
 from sqlalchemy import exc, util
+from sqlalchemy.engine import base
 
 
 class URL(object):
         to this URL's driver name.
         """
 
-        try:
-            if '+' in self.drivername:
-                dialect, driver = self.drivername.split('+')
-            else:
-                dialect, driver = self.drivername, 'base'
-
-            module = __import__('sqlalchemy.dialects.%s' % (dialect, )).dialects
-            module = getattr(module, dialect)
-            if hasattr(module, driver):
-                module = getattr(module, driver)
-            else:
-                module = self._load_entry_point()
-                if module is None:
-                    raise exc.ArgumentError(
-                        "Could not determine dialect for '%s'." % 
-                        self.drivername)
-
-            return module.dialect
-        except ImportError:
-            module = self._load_entry_point()
-            if module is not None:
-                return module
-            else:
-                raise exc.ArgumentError(
-                    "Could not determine dialect for '%s'." % self.drivername)
-
-    def _load_entry_point(self):
-        """attempt to load this url's dialect from entry points, or return None
-        if pkg_resources is not installed or there is no matching entry point.
-
-        Raise ImportError if the actual load fails.
-
-        """
-        try:
-            import pkg_resources
-        except ImportError:
-            return None
-
-        for res in pkg_resources.iter_entry_points('sqlalchemy.dialects'):
-            if res.name == self.drivername.replace("+", "."):
-                return res.load()
+        if '+' not in self.drivername:
+            name = self.drivername
         else:
-            return None
+            name = self.drivername.replace('+', '.')
+        from sqlalchemy.dialects import registry
+        cls = registry.load(name)
+        # check for legacy dialects that
+        # would return a module with 'dialect' as the
+        # actual class
+        if hasattr(cls, 'dialect') and \
+            isinstance(cls.dialect, type) and \
+            issubclass(cls.dialect, base.Dialect):
+            return cls.dialect
+        else:
+            return cls
 
     def translate_connect_args(self, names=[], **kw):
         """Translate url attributes into a dictionary of connection arguments.

lib/sqlalchemy/util/__init__.py

     duck_type_collection, assert_arg_type, symbol, dictlike_iteritems,\
     classproperty, set_creation_order, warn_exception, warn, NoneType,\
     constructor_copy, methods_equivalent, chop_traceback, asint,\
-    generic_repr, counter
+    generic_repr, counter, PluginLoader
 
 from deprecations import warn_deprecated, warn_pending_deprecation, \
     deprecated, pending_deprecation

lib/sqlalchemy/util/langhelpers.py

         return update_wrapper(decorated, fn)
     return update_wrapper(decorate, target)
 
+class PluginLoader(object):
+    def __init__(self, group, auto_fn=None):
+        self.group = group
+        self.impls = {}
+        self.auto_fn = auto_fn
+
+    def load(self, name):
+        if name in self.impls:
+             return self.impls[name]()
+
+        if self.auto_fn:
+            loader = self.auto_fn(name)
+            if loader:
+                self.impls[name] = loader
+                return loader()
+
+        try:
+            import pkg_resources
+        except ImportError:
+            pass
+        else:
+            for impl in pkg_resources.iter_entry_points(
+                                self.group, name):
+                self.impls[name] = impl.load
+                return impl.load()
+
+        from sqlalchemy import exc
+        raise exc.ArgumentError(
+                "Can't load plugin: %s:%s" % 
+                (self.group, name))
+
+    def register(self, name, modulepath, objname):
+        def load():
+            mod = __import__(modulepath)
+            for token in modulepath.split(".")[1:]:
+                mod = getattr(mod, token)
+            return getattr(mod, objname)
+        self.impls[name] = load
+
 
 def get_cls_kwargs(cls):
     """Return the full set of inherited kwargs for the given `cls`.

test/engine/test_parseconnect.py

 import sqlalchemy.engine.url as url
 from sqlalchemy import create_engine, engine_from_config, exc, pool
 from sqlalchemy.engine import _coerce_config
+from sqlalchemy.engine.default import DefaultDialect
 import sqlalchemy as tsa
 from test.lib import fixtures, testing
 
             _initialize=False,
             )
 
+class TestRegNewDBAPI(fixtures.TestBase):
+    def test_register_base(self):
+        from sqlalchemy.dialects import registry
+        registry.register("mockdialect", __name__, "MockDialect")
+
+        e = create_engine("mockdialect://")
+        assert isinstance(e.dialect, MockDialect)
+
+    def test_register_dotted(self):
+        from sqlalchemy.dialects import registry
+        registry.register("mockdialect.foob", __name__, "MockDialect")
+
+        e = create_engine("mockdialect+foob://")
+        assert isinstance(e.dialect, MockDialect)
+
+    def test_register_legacy(self):
+        from sqlalchemy.dialects import registry
+        tokens = __name__.split(".")
+
+        global dialect
+        dialect = MockDialect
+        registry.register("mockdialect.foob", ".".join(tokens[0:-1]), tokens[-1])
+
+        e = create_engine("mockdialect+foob://")
+        assert isinstance(e.dialect, MockDialect)
+
+    def test_register_per_dbapi(self):
+        from sqlalchemy.dialects import registry
+        registry.register("mysql.my_mock_dialect", __name__, "MockDialect")
+
+        e = create_engine("mysql+my_mock_dialect://")
+        assert isinstance(e.dialect, MockDialect)
+
+class MockDialect(DefaultDialect):
+    @classmethod
+    def dbapi(cls, **kw):
+        return MockDBAPI()
+
 class MockDBAPI(object):
     version_info = sqlite_version_info = 99, 9, 9
     sqlite_version = '99.9.9'