rattail.labels

Label Printing

class rattail.labels.CommandFilePrinter(config)

Generic LabelPrinter implementation which “prints” labels to a file in the form of native printer (textual) commands. The output file is then expected to be picked up by a file monitor, and finally sent to the printer from there.

print_labels(labels, output_dir=None, progress=None)

“Prints” labels by generating a command file in the output folder. The full path of the output file to which commands are written will be returned to the caller.

If output_dir is not specified, and the printer instance is associated with a LabelProfile instance, then config will be consulted for the output path. If a path still is not found, the current (working) directory will be assumed.

class rattail.labels.CommandFormatter(config, template=None)

Base class and default implementation for label formatters which generate raw printer commands for sending (in)directly to the printer device.

There are various printer command languages out there; this class is not language-specific and should work for any of them.

template

Formatting template. This is a string containing a template of raw printer commands, suitable for printing a single label record. Value for this normally comes from rattail.db.model.labels.LabelProfile.format.

Normally these commands would print a “complete” label in terms of physical media, but not so for 2-up, in which case the template should only contain commands for “half” the label, i.e. only the commands to print one “record”.

There are 2 “languages” at play within the template:

• template language

• printer command language

The template language refers to the syntax of the template itself, which ultimately will be “rendered” into a final result which should contain valid printer command language. (See also format_labels().) Thus far there is only one template language supported, although it is likely more will be added in the future:

• printf-style String Formatting

The printer command language refers to the syntax of commands which can be sent to the printer in order to cause it to produce desired physical media, i.e. “formatted printed label”. There are a number of printer command languages out there; the one you need to use will depend on the make and/or model and/or settings for your printer device. Thus far the following languages have been used successfully:

• Cognitive Programming Language (CPL)

• Zebra Programming Language (ZPL)

A template example using ZPL:

^XA
^FO035,65^A0N,40,30^FD%(brand)-17.17s^FS
^FO035,110^A0N,30,30^FD%(description)s %(size)s^FS
^FO163,36^A0N,80,55^FB230,1,0,R,0^FD$%(price)0.2f^FS
^FO265,170,0^A0N,25,20^FD%(vendor)-14.14s^FS
^FO050,144^BY2%(barcode)s^FS
^XZ

A template example using CPL for a 2-up layout:

STRING 5X7 %(description_x)d 5 %(description1)s
STRING 5X7 %(description_x)d 15 %(description2)s
BARCODE %(barcode_type)s %(barcode_x)d 60 20 %(barcode)s

format_labels(labels, progress=None, **kwargs)

Format a set of labels and return the result. By “formatting” here we really mean generating a set of commands which ultimately will be submitted directly to a label printer device.

Each of the labels specified should be a 2-tuple like (data, quantity), where data is a dict of record data (e.g. product description, price etc.) and quantity is the number of labels to be printed for that record.

The formatter’s template is “rendered” by feeding it the data dict from a single label record. That process is repeated until all labels have been rendered.

Note that the formatting template is only able to reference fields present in the data dict for any given label record. If the incoming data is incomplete then you can add to it by overriding get_all_data().

Parameters:

• labels – Sequence of 2-tuples representing labels to be formatted for printing.

• progress – Optional progress factory.

Returns:

Unicode string containing the formatted label data, i.e. commands to print the labels.

get_all_data(data, **kwargs)

Returns the “complete’ data dict for a given label record.

When the caller asks us to format labels, it provides a data dict for each label to be printed. This method is able to add more things to that data dict, if needed.

Note that which fields are actually needed will depend on the contents of template.

By default this will check the data dict for a 'product' key, and if there is a value, calls get_product_data() to add common product fields.

Parameters:

data – Dict of data for a label record, as provided by the caller.

Returns:

Final data dict with all necessary fields.

get_product_data(data, product, **kwargs)

Add common product fields to the given data dict.

The intention is that even if data is an empty dict, this method should be able to add enough data to make basic label printing possible.

Default logic for this will call rattail.labels.LabelHandler.get_product_label_data() to get the product data dict, and then use data from the caller to override anything as needed, and return the result.

Parameters:

• data – Dict of data for a label record.

• product – A Product instance to which the label record applies, and from which additional field values will come.

Returns:

Final data dict including common product fields.

label_footer_commands()

This method, if implemented, must return a sequence of string commands to be interpreted by the printer. These commands will immedately follow each label in one-up printing, and immediately follow each label pair in two-up printing.

label_header_commands()

This method, if implemented, must return a sequence of string commands to be interpreted by the printer. These commands will immediately precede each label in one-up printing, and immediately precede each label pair in two-up printing.

class rattail.labels.CommandNetworkPrinter(config)

Generic LabelPrinter implementation which “prints” labels to a network socket in the form of native printer (textual) commands. The socket is assumed to exist on a networked label printer.

print_labels(labels, progress=None)

Prints labels by generating commands and sending directly to a socket which exists on a networked printer.

class rattail.labels.CommandPrinter(config)

Generic LabelPrinter class which “prints” labels via native printer (textual) commands. It does not directly implement any method for sending the commands to a printer; a subclass must be used for that.

batch_footer_commands()

This method, if implemented, must return a sequence of string commands to be interpreted by the printer. These commands will be the last which are written to the file.

batch_header_commands()

This method, if implemented, must return a sequence of string commands to be interpreted by the printer. These commands will be the first which are written to the file.

class rattail.labels.LabelFormatter(config, template=None)

Base class for all label formatters.

property default_template

Default formatting template. This will be used if no template is defined within the label profile; see also rattail.db.model.labels.LabelProfile.format.

format_labels(labels, progress=None, **kwargs)

Formats a set of labels and returns the result.

Parameters:

labels – Sequence of 2-tuples representing labels to be formatted, and ultimately printed.

class rattail.labels.LabelHandler(*args, **kwargs)

Base class and default implementation for label handlers.

get_formatter(profile, ignore_errors=False)

Return the label formatter for the given profile.

Parameters:

profile – A LabelProfile instance.

Returns:

A LabelFormatter instance.

get_label_profiles(session, visible=True, **kwargs)

Return the set of label profiles which are available for use with actual product label printing.

get_printer(profile, ignore_errors=False)

Return the label printer for the given profile.

Parameters:

profile – A LabelProfile instance.

Returns:

A LabelPrinter instance.

get_printer_setting(profile, name)

Read a printer setting from the DB.

get_product_label_data(product, **kwargs)

Return a data dict with common product fields, suitable for use with formatting labels for printing.

The intention is that this method should be able to provide enough data to make basic label printing possible. In fact when printing is done “ad-hoc” for one product at a time, the data used for printing comes only from this method.

Parameters:

product – A Product instance from which field values will come.

Returns:

Data dict containing common product fields.

save_printer_setting(profile, name, value)

Write a printer setting to the DB.

class rattail.labels.LabelPrinter(config)

Base class for all label printers.

Label printing devices which are “natively” supported by Rattail will each derive from this class in order to provide implementation details specific to the device. You will typically instantiate one of those subclasses (or one of your own design) in order to send labels to your physical printer.

print_labels(labels, *args, **kwargs)

Prints labels found in labels.

class rattail.labels.TwoUpCommandFormatter(config, template=None)

Generic subclass of LabelFormatter which generates native printer (textual) commands.

This class contains logic to implement “two-up” label printing.

property half_offset

The X-coordinate value by which the second label should be offset, when two labels are printed side-by-side.