- add a "search path" for (URL) protocol handlers so that user can add its own

- add unit test for custom handler
- doc update
- increment version to 2.6-pre1


git-svn-id: http://svn.code.sf.net/p/pyserial/code/trunk/pyserial@388 f19166aa-fa4f-0410-85c2-fa1106f25c8a

1 files changed, 26 insertions, 9 deletions

diff --git a/serial/__init__.py b/serial/__init__.py
index cc5e6dc..be1647c 100644
--- a/serial/__init__.py
+++ b/serial/__init__.py
@@ -6,7 +6,7 @@
 # (C) 2001-2010 Chris Liechti <cliechti@gmx.net>
 # this is distributed under a free software license, see license.txt
 
-VERSION = '2.5'
+VERSION = '2.6-pre1'
 
 import sys
 
@@ -24,11 +24,24 @@ else:
     else:
         raise Exception("Sorry: no implementation for your platform ('%s') available" % os.name)
 
+protocol_handler_packages = [
+        'serial.urlhandler',
+        ]
 
 def serial_for_url(url, *args, **kwargs):
-    """Get a native, a RFC2217 or socket implementation of the Serial class,
+    """\
+    Get a native, a RFC2217 or socket implementation of the Serial class,
     depending on port/url. The port is not opened when the keyword parameter
-    'do_not_open' is true, by default it is."""
+    'do_not_open' is true, by default it is.
+
+    The list of package names that is searched for protocol handlers is kept in
+    ``protocol_handler_packages``
+
+    e.g. we want to support a URL ``foobar://``. A module
+    ``my_handlers.protocol_foobar`` is provided by the user. Then
+    ``protocol_handler_packages.append("my_handlers")`` would extend the search
+    path so that ``serial_for_url("foobar://"))`` would work.
+    """
     # check remove extra parameter to not confuse the Serial class
     do_open = 'do_not_open' not in kwargs or not kwargs['do_not_open']
     if 'do_not_open' in kwargs: del kwargs['do_not_open']
@@ -43,13 +56,17 @@ def serial_for_url(url, *args, **kwargs):
     else:
         if '://' in url_nocase:
             protocol = url_nocase.split('://', 1)[0]
-            module_name = 'serial.urlhandler.protocol_%s' % (protocol,)
-            try:
-                handler_module = __import__(module_name)
-            except ImportError:
-                raise ValueError('invalid URL, protocol %r not known' % (protocol,))
+            for package_name in protocol_handler_packages:
+                module_name = '%s.protocol_%s' % (package_name, protocol,)
+                try:
+                    handler_module = __import__(module_name)
+                except ImportError:
+                    pass
+                else:
+                    klass = sys.modules[module_name].Serial
+                    break
             else:
-                klass = sys.modules[module_name].Serial
+                raise ValueError('invalid URL, protocol %r not known' % (protocol,))
         else:
             klass = Serial   # 'native' implementation
     # instantiate and open when desired