backends: rename string_descr -> identifier

The strings like tcp://192.168.0.23:9100 or
usb://0x04f9:0x2015 are rather 'identifiers'
than descriptors (terminology).
Users relying on the returned dictionaries of the
list_available_devices() function need to update
the key from 'string_descr' to 'identifier'.
Sorry for the inconvenience.

brother_ql/backends/__init__.py

@@ -8,16 +8,16 @@ available_backends = [
   'linux_kernel',
 ]
 
-def guess_backend(descr):
+def guess_backend(identifier):
-    """ guess the backend from a given string descriptor for the device """
+    """ guess the backend from a given identifier string for the device """
-    if descr.startswith('usb://') or descr.startswith('0x'):
+    if identifier.startswith('usb://') or identifier.startswith('0x'):
         return 'pyusb'
-    elif descr.startswith('file://') or descr.startswith('/dev/usb/') or descr.startswith('lp'):
+    elif identifier.startswith('file://') or identifier.startswith('/dev/usb/') or identifier.startswith('lp'):
         return 'linux_kernel'
-    elif descr.startswith('tcp://'):
+    elif identifier.startswith('tcp://'):
         return 'network'
     else:
-        raise ValueError('Cannot guess backend for given string descriptor: %s' % descr)
+        raise ValueError('Cannot guess backend for given identifier: %s' % identifier)
     
 
 def backend_factory(backend_name):

brother_ql/backends/generic.py

@@ -5,8 +5,8 @@ logger = logging.getLogger(__name__)
 
 def list_available_devices():
     """ List all available devices for the respective backend """
-    # returns a list of dictionaries with the keys 'string_descr' and 'instance':
+    # returns a list of dictionaries with the keys 'identifier' and 'instance':
-    # [ {'string_descr': '/dev/usb/lp0', 'instance': os.open('/dev/usb/lp0', os.O_RDWR)}, ]
+    # [ {'identifier': '/dev/usb/lp0', 'instance': os.open('/dev/usb/lp0', os.O_RDWR)}, ]
     raise NotImplementedError()
 
 

brother_ql/backends/linux_kernel.py

@@ -13,14 +13,14 @@ def list_available_devices():
     """
     List all available devices for the linux kernel backend
 
-    returns: devices: a list of dictionaries with the keys 'string_descr' and 'instance': \
+    returns: devices: a list of dictionaries with the keys 'identifier' and 'instance': \
-        [ {'string_descr': 'file:///dev/usb/lp0', 'instance': None}, ] \
+        [ {'identifier': 'file:///dev/usb/lp0', 'instance': None}, ] \
         Instance is set to None because we don't want to open (and thus potentially block) the device here.
     """
 
     paths = glob.glob('/dev/usb/lp*')
 
-    return [{'string_descr': 'file://' + path, 'instance': None} for path in paths]
+    return [{'identifier': 'file://' + path, 'instance': None} for path in paths]
 
 class BrotherQLBackendLinuxKernel(BrotherQLBackendGeneric):
     """
@@ -29,7 +29,7 @@ class BrotherQLBackendLinuxKernel(BrotherQLBackendGeneric):
 
     def __init__(self, device_specifier):
         """
-        device_specifier: string or os.open(): string descriptor in the \
+        device_specifier: string or os.open(): identifier in the \
             format file:///dev/usb/lp0 or os.open() raw device handle.
         """
 

brother_ql/backends/network.py

@@ -13,14 +13,14 @@ def list_available_devices():
     """
     List all available devices for the network backend
 
-    returns: devices: a list of dictionaries with the keys 'string_descr' and 'instance': \
+    returns: devices: a list of dictionaries with the keys 'identifier' and 'instance': \
-        [ {'string_descr': 'tcp://hostname[:port]', 'instance': None}, ] \
+        [ {'identifier': 'tcp://hostname[:port]', 'instance': None}, ] \
         Instance is set to None because we don't want to connect to the device here yet.
     """
 
     # We need some snmp request sent to 255.255.255.255 here
     raise NotImplementedError()
-    return [{'string_descr': 'tcp://' + path, 'instance': None} for path in paths]
+    return [{'identifier': 'tcp://' + path, 'instance': None} for path in paths]
 
 class BrotherQLBackendNetwork(BrotherQLBackendGeneric):
     """
@@ -29,7 +29,7 @@ class BrotherQLBackendNetwork(BrotherQLBackendGeneric):
 
     def __init__(self, device_specifier):
         """
-        device_specifier: string or os.open(): string descriptor in the \
+        device_specifier: string or os.open(): identifier in the \
             format file:///dev/usb/lp0 or os.open() raw device handle.
         """
 

brother_ql/backends/pyusb.py

@@ -19,9 +19,9 @@ def list_available_devices():
     """
     List all available devices for the respective backend
 
-    returns: devices: a list of dictionaries with the keys 'string_descr' and 'instance': \
+    returns: devices: a list of dictionaries with the keys 'identifier' and 'instance': \
-        [ {'string_descr': 'usb://0x04f9:0x2015/C5Z315686', 'instance': pyusb.core.Device()}, ]
+        [ {'identifier': 'usb://0x04f9:0x2015/C5Z315686', 'instance': pyusb.core.Device()}, ]
-        The 'string_descr' is of the format idVendor:idProduct_iSerialNumber.
+        The 'identifier' is of the format idVendor:idProduct_iSerialNumber.
     """
 
     class find_class(object):
@@ -42,14 +42,14 @@ def list_available_devices():
     # only Brother printers
     printers = usb.core.find(find_all=1, custom_match=find_class(7), idVendor=0x04f9)
 
-    def string_descr(dev):
+    def identifier(dev):
         try:
             serial = usb.util.get_string(dev, 256, dev.iSerialNumber)
             return 'usb://0x{:04x}:0x{:04x}_{}'.format(dev.idVendor, dev.idProduct, serial)
         except:
             return 'usb://0x{:04x}:0x{:04x}'.format(dev.idVendor, dev.idProduct)
 
-    return [{'string_descr': string_descr(printer), 'instance': printer} for printer in printers]
+    return [{'identifier': identifier(printer), 'instance': printer} for printer in printers]
 
 class BrotherQLBackendPyUSB(BrotherQLBackendGeneric):
     """
@@ -58,7 +58,7 @@ class BrotherQLBackendPyUSB(BrotherQLBackendGeneric):
 
     def __init__(self, device_specifier):
         """
-        device_specifier: string or pyusb.core.Device: string descriptor of the \
+        device_specifier: string or pyusb.core.Device: identifier of the \
             format usb://idVendor:idProduct/iSerialNumber or pyusb.core.Device instance.
         """
 

brother_ql/brother_ql_print.py

@@ -19,7 +19,7 @@ def main():
     parser.add_argument('--list-printers', action='store_true', help='List the devices available with the selected --backend')
     parser.add_argument('--debug', action='store_true', help='Enable debugging output')
     parser.add_argument('instruction_file', nargs='?', help='file containing the instructions to be sent to the printer')
-    parser.add_argument('device', metavar='DEVICE_STRING_DESCRIPTOR', nargs='?', help='String descriptor for specific device. If not specified, select first detected device')
+    parser.add_argument('device', metavar='DEVICE_IDENTIFIER', nargs='?', help='Identifier string specifying the device. If not specified, select first detected device')
     args = parser.parse_args()
 
     if args.list_printers and not args.backend:
@@ -61,25 +61,25 @@ def main():
         for ad in available_devices:
             result = {'model': 'unknown'}
             result.update(ad)
-            logger.info("  Found a label printer: {string_descr}  (model: {model})".format(**result))
+            logger.info("  Found a label printer: {identifier}  (model: {model})".format(**result))
 
     if args.list_printers:
         for printer in available_devices:
-            print(printer['string_descr'])
+            print(printer['identifier'])
         sys.exit(0)
 
-    string_descr = None
+    identifier = None
     if not args.device:
         "We need to search for available devices and select the first."
         if not available_devices:
             sys.exit("No printer found")
-        string_descr = available_devices[0]['string_descr']
+        identifier = available_devices[0]['identifier']
-        print("Selecting first device %s" % string_descr)
+        print("Selecting first device %s" % identifier)
     else:
-        "A string descriptor for the device was given, let's use it."
+        "An identifier for the device was given, let's use it."
-        string_descr = args.device
+        identifier = args.device
 
-    printer = BrotherQLBackend(string_descr)
+    printer = BrotherQLBackend(identifier)
 
     start = time.time()
     logger.info('Sending instructions to the printer. Total: %d bytes.', len(content))