From a66fb14ae48a70d97926d197f3af157e2f2b1ab1 Mon Sep 17 00:00:00 2001 From: cliechti Date: Fri, 18 Mar 2011 00:49:16 +0000 Subject: - 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 --- documentation/pyserial_api.rst | 34 ++++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) (limited to 'documentation') diff --git a/documentation/pyserial_api.rst b/documentation/pyserial_api.rst index b2ba0d9..38aeb2c 100644 --- a/documentation/pyserial_api.rst +++ b/documentation/pyserial_api.rst @@ -698,8 +698,8 @@ Module version: .. versionadded:: 2.3 -Module functions -================ +Module functions and attributes +=============================== .. function:: device(number) @@ -732,20 +732,40 @@ Module functions .. versionadded:: 2.5 +.. attribute:: protocol_handler_packages + + This attribute is a list of package names (strings) that is searched for + protocol handlers. + + e.g. we want to support a URL ``foobar://``. A module + ``my_handlers.protocol_foobar`` is provided by the user:: + + serial.protocol_handler_packages.append("my_handlers") + s = serial.serial_for_url("foobar://") + + For an URL starting with ``XY://`` is the function :func:`serial_for_url` + attempts to import ``PACKAGE.protocol_XY`` with each candidate for + ``PACKAGE`` from this list. + + .. versionadded:: 2.6 + + .. function:: to_bytes(sequence) :param sequence: String or list of integers :returns: an instance of ``bytes`` - Convert a sequence to a bytes type. This is used to write code that is + Convert a sequence to a ``bytes`` type. This is used to write code that is compatible to Python 2.x and 3.x. - In Python versions prior 3.x, bytes is a subclass of str. They convert + In Python versions prior 3.x, ``bytes`` is a subclass of str. They convert ``str([17])`` to ``'[17]'`` instead of ``'\x11'`` so a simple - bytes(sequence) doesn't work for all versions of Python. + ``bytes(sequence)`` doesn't work for all versions of Python. This function is used internally and in the unit tests. + .. versionadded:: 2.5 + .. _URLs: @@ -762,7 +782,9 @@ Device names are also supported, e.g.: - ``/dev/ttyUSB0`` (Linux) - ``COM3`` (Windows) -(Future releases of pySerial might add more types). +Future releases of pySerial might add more types. Since pySerial 2.6 it is also +possible for the user to add protocol handlers using +:attr:`protocol_handler_packages`. ``rfc2217://`` Used to connect to :rfc:`2217` compatible servers. All serial port -- cgit v1.2.1