Added unique return codes

dev/docs/source/page_setup.rst

@@ -571,8 +571,8 @@ worksheet.print_area()
    :type  last_row:    integer
    :type  last_col:    integer
 
-   :returns:  0: Success.
-   :returns: -1: Row or column is out of worksheet bounds.
+   :returns: ReturnCode.XW_NO_ERROR: Success.
+   :returns: None : Max print area selected
 
 This method is used to specify the area of the worksheet that will be printed.
 

dev/docs/source/workbook.rst

@@ -531,6 +531,10 @@ workbook.set_custom_property()
    :type name:           string
    :type property_type:  string
 
+   :returns: XW_NO_ERROR: Success.
+   :returns: XW_ERROR_INCORRECT_PARAMETER_OR_OPTION: Incorrect parameter or
+                                                     option.
+
 
 The ``set_custom_property()`` method can be used to set one or more custom
 document properties not covered by the standard properties in the
@@ -578,6 +582,10 @@ workbook.define_name()
    :param string name:    The defined name.
    :param string formula: The cell or range that the defined name refers to.
 
+   :returns: XW_NO_ERROR: Success.
+   :returns: XW_ERROR_INCORRECT_PARAMETER_OR_OPTION: Incorrect parameter or
+                                                     option.
+
 This method is used to defined a name that can be used to represent a value, a
 single cell or a range of cells in a workbook. These are sometimes referred to
 as a "Named Range".

examples/inheritance2.py

@@ -17,6 +17,7 @@
 from xlsxwriter.workbook import Workbook
 from xlsxwriter.worksheet import Worksheet
 from xlsxwriter.worksheet import convert_cell_args
+from xlsxwriter.returncodes import ReturnCode
 
 
 def excel_string_width(str):
@@ -48,7 +49,7 @@ def write_string(self, row, col, string, cell_format=None):
 
         # Check that row and col are valid and store max and min values.
         if self._check_dimensions(row, col):
-            return -1
+            return ReturnCode.XW_ERROR_WORKSHEET_INDEX_OUT_OF_RANGE
 
         # Set the min width for the cell. In some cases this might be the
         # default width of 8.43. In this case we use 0 and adjust for all

xlsxwriter/returncodes.py

@@ -0,0 +1,59 @@
+###############################################################################
+#
+# ReturnCodes - A class for XlsxWriter return codes.
+#
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright 2013-2022, John McNamara, [email protected]
+#
+
+from enum import Enum
+
+
+class ReturnCode(str, Enum):
+    """Return codes enumeration for XlsxWriter functions
+
+    These values can be converted to string in different ways:
+    - direct assignment: mystr = retcode
+    - through format function: mystr = "Value {0}".format(retcode)
+    - through f-string: mystr = f'Value {retcode}'
+
+    Conversion through str() function will result in the internal Enum
+    representation, i.e. str(ReturnCode.XW_NO_ERROR) will return
+    "ReturnCode.XW_NO_ERROR"
+    """
+
+    # Note: the following are not tuples, but strings on multiple lines
+    # This is required to be compliant to E501
+
+    ###########################################################################
+    #
+    # Values from libxlsxwriter library
+    #
+    ###########################################################################
+
+    XW_NO_ERROR = "No error"
+    XW_ERROR_MAX_STRING_LENGTH_EXCEEDED = ("String exceeds Excel's limit of "
+                                           "32,767 characters")
+    XW_ERROR_WORKSHEET_INDEX_OUT_OF_RANGE = ("Worksheet row or column index "
+                                             "out of range")
+    XW_ERROR_WORKSHEET_MAX_URL_LENGTH_EXCEEDED = ("Maximum hyperlink length "
+                                                  "(2079) exceeded")
+    XW_ERROR_WORKSHEET_MAX_NUMBER_URLS_EXCEEDED = ("Maximum number of "
+                                                   "worksheet URLs (65530) "
+                                                   "exceeded")
+
+    ###########################################################################
+    #
+    # Values added only for this library
+    #
+    ###########################################################################
+
+    XW_ERROR_VBA_FILE_NOT_FOUND = "VBA project binary file not found"
+    XW_ERROR_FORMULA_CANT_BE_NONE_OR_EMPTY = "Formula can't be None or empty"
+    XW_ERROR_2_CONSECUTIVE_FORMATS = "2 consecutive formats used"
+    XW_ERROR_EMPTY_STRING_USED = "Empty string used"
+    XW_ERROR_INSUFFICIENT_PARAMETERS = "Insufficient parameters"
+    XW_ERROR_IMAGE_FILE_NOT_FOUND = "Image file not found"
+    XW_ERROR_INCORRECT_PARAMETER_OR_OPTION = "Incorrect parameter or option"
+    XW_ERROR_NOT_SUPPORTED_COSTANT_MEMORY = ("Not supported in "
+                                             "constant_memory mode")