Feature request: add user defined types to write()

[jmcnamara]

The worksheet write() method maps common Python types to corresponding Excel types. It deliberately doesn't try to map unknown/unhandled types to Excel strings (for example) since the decision on the type mapping should be made by the end user.

This mapping can be done by remapping data types before calling write() but there are cases where it is cleaner to do it in write().

This is available in the Perl version of this module in a method called add_write_handler(). The Perl version relies on regular expressions but an equivalent version in Python could use types.

For example, currently if you write an unhandled data type you get an TypeError:

import xlsxwriter
import uuid

# Set up the workbook as usual.
workbook = xlsxwriter.Workbook('user_type.xlsx')
worksheet = workbook.add_worksheet()

# Make the first column wider for clarity.
worksheet.set_column('A:A', 40)

# Create a UUID.
my_uuid = uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')

# Write the UUID.
worksheet.write('A1', my_uuid)

workbook.close()

Output:

$ python myuuid.py
Traceback (most recent call last):
  File "myuuid0.py", line 15, in <module>
    worksheet.write('A1', my_uuid)
  File "/path/xlsxwriter/worksheet.py", line 69, in cell_wrapper
    return method(self, *args, **kwargs)
  File "/path/xlsxwriter/worksheet.py", line 413, in write
    return self._write(row, col, *args)
  File "/path/xlsxwriter/worksheet.py", line 493, in _write
    raise TypeError("Unsupported type %s in write()" % type(token))
TypeError: Unsupported type <class 'uuid.UUID'> in write()

With the proposed new API you could add a handler/callback for this, or other, types:

import xlsxwriter
import uuid

# Create a function that will behave like a worksheet write() method. 
#
# This function takes a UUID and writes it as as string. It should take the
# parameters shown below and return the return value from the called worksheet
# write_*() method.
#
def write_uuid(worksheet, row, col, token, format=None):
    return worksheet.write_string(row, col, str(token), format)

# Set up the workbook as usual.
workbook = xlsxwriter.Workbook('user_type.xlsx')
worksheet = workbook.add_worksheet()

# Make the first column wider for clarity.
worksheet.set_column('A:A', 40)

# Add the write() handler/callback to the worksheet.
worksheet.add_write_handler(uuid.UUID, write_uuid)

# Create a UUID.
my_uuid = uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')

# Write the UUID.
worksheet.write('A1', my_uuid)

workbook.close()

Output:

[jmcnamara]

Initial working code is available to test this on the https://github.com/jmcnamara/XlsxWriter/tree/write_handler branch.

[jmcnamara]

Added in version 1.2.1. See: https://xlsxwriter.readthedocs.io/working_with_data.html#writing-user-defined-types