excelize.py

"""Copyright 2024 - 2025 The excelize Authors. All rights reserved. Use of this
source code is governed by a BSD-style license that can be found in the LICENSE
file.

Package excelize-py is a Python port of Go Excelize library, providing a set of
functions that allow you to write and read from XLAM / XLSM / XLSX / XLTM / XLTX
files. Supports reading and writing spreadsheet documents generated by Microsoft
Excel™ 2007 and later. Supports complex components by high compatibility, and
provided streaming API for generating or reading data from a worksheet with huge
amounts of data. This library needs Python version 3.9 or later.
"""

from dataclasses import fields
from datetime import datetime, date, time
from enum import Enum
from typing import Tuple, get_args, get_origin, List, Optional, Union
import types_go
from types_py import *
from ctypes import (
    byref,
    c_bool,
    c_char_p,
    c_char,
    c_double,
    c_int,
    c_ubyte,
    cast,
    CDLL,
    create_string_buffer,
    POINTER,
    pointer,
    string_at,
)
import os
import platform


def load_lib():
    system = platform.system().lower()
    arch = platform.architecture()[0]
    machine = platform.machine().lower()
    ext_map = {"linux": ".so", "darwin": ".dylib", "windows": ".dll"}
    arch_map = {
        "linux": {
            "64bit": {
                "x86_64": "amd64",
                "amd64": "amd64",
                "aarch64": "arm64",
            },
            "32bit": {
                "x86": "386",
                "i386": "386",
                "i686": "386",
            },
        },
        "darwin": {
            "64bit": {
                "x86_64": "amd64",
                "amd64": "amd64",
                "arm64": "arm64",
            },
        },
        "windows": {
            "64bit": {
                "x86_64": "amd64",
                "amd64": "amd64",
                "arm64": "arm64",
            },
            "32bit": {
                "x86": "386",
                "i386": "386",
                "i686": "386",
            },
        },
    }
    if system in ext_map and arch in arch_map.get(system, {}):
        arch_name = arch_map[system][arch].get(machine)
        if arch_name:
            return f"libexcelize.{arch_name}.{system}{ext_map[system]}"

    print("This platform or architecture is not supported.")
    exit(1)


lib = CDLL(os.path.join(os.path.dirname(__file__), load_lib()))
ENCODE = "utf-8"
__version__ = "0.0.2"
uppercase_words = ["id", "rgb", "sq", "xml"]


def py_to_base_ctype(py_value, c_type):
    """
    Convert a Python value to a specified C type.

    Args:
        py_value: The Python value to be converted. If the value is a string, it will be encoded.
        c_type: The target C type to which the Python value should be converted.

    Returns:
        The converted value in the specified C type.
    """
    return (
        c_type(py_value.encode(ENCODE)) if str is type(py_value) else c_type(py_value)
    )


def is_py_primitive_type(t: type) -> bool:
    """
    Check if the given type is a Python primitive type.

    Args:
        t (type): The type to check.

    Returns:
        bool: True if the type is a Python primitive type or an Enum subclass, False otherwise.
    """
    return True if issubclass(t, Enum) else t in {int, float, bool, str, bytes, complex}


def snake_to_pascal(snake_str: str) -> str:
    """
    Convert a snake_case string to PascalCase.

    Args:
        snake_str (str): The snake_case string to convert.

    Returns:
        str: The converted PascalCase string.
    """
    return "".join(
        word.upper() if word.lower() in uppercase_words else word.capitalize()
        for word in snake_str.split("_")
    )


def c_value_to_py(ctypes_instance, py_instance):
    """
    Convert a ctypes instance to a Python instance by mapping fields from the
    to the corresponding fields in the Python instance.

    Args:
        ctypes_instance: The ctypes instance representing the Go data structure.
        py_instance: The Python instance to populate with data from the ctypes instance.

    Returns:
        The populated Python instance, or None if the ctypes instance is None.
    """
    if ctypes_instance is None:
        return None
    for py_field in fields(py_instance):
        py_field_name = py_field.name
        c_field_name = snake_to_pascal(py_field.name)
        # The Go base type
        py_field_args = get_args(py_field.type)

        if type(None) not in py_field_args:
            if is_py_primitive_type(py_field.type):
                c_val = getattr(ctypes_instance, c_field_name)
                if c_val:
                    setattr(
                        py_instance,
                        py_field_name,
                        (c_val.decode(ENCODE) if str is py_field.type else c_val),
                    )
                    continue
            else:
                # The Go struct, for example: excelize.Options, convert sub fields recursively
                setattr(
                    py_instance,
                    py_field_name,
                    c_value_to_py(
                        getattr(ctypes_instance, c_field_name), py_field.type()
                    ),
                )
        else:
            if get_origin(py_field_args[0]) is not list:
                # Pointer of the Go data type, for example: *excelize.Options or *string
                value = getattr(ctypes_instance, c_field_name)
                if value:
                    if any(is_py_primitive_type(arg) for arg in py_field_args):
                        # Pointer of the Go basic data type, for example: *string
                        value = getattr(ctypes_instance, c_field_name)
                        setattr(
                            py_instance,
                            py_field_name,
                            (
                                value.contents.value.decode(ENCODE)
                                if str in py_field_args
                                else value.contents.value
                            ),
                        )
                    else:
                        # Pointer of the Go struct, for example: *excelize.Options
                        setattr(
                            py_instance,
                            py_field_name,
                            c_value_to_py(
                                value.contents,
                                py_field_args[0](),
                            ),
                        )
            else:
                # The Go data type array, for example:
                # []*excelize.Options, []excelize.Options, []string, []*string
                if type(None) not in get_args(get_args(py_field_args[0])[0]):
                    # The Go data type array, for example: []excelize.Options or []string
                    py_list = []
                    l = getattr(ctypes_instance, c_field_name + "Len")
                    c_array = getattr(ctypes_instance, c_field_name)
                    if c_array:
                        if is_py_primitive_type(get_args(py_field_args[0])[0]):
                            # The Go basic data type array, for example: []string
                            for i in range(l):
                                py_list.append(
                                    string_at(c_array[i]).decode(ENCODE)
                                    if str is get_args(py_field_args[0])[0]
                                    else c_array[i]
                                )
                        else:
                            # The Go struct array, for example: []excelize.Options
                            for i in range(l):
                                py_list.append(
                                    c_value_to_py(
                                        c_array[i],
                                        get_args(py_field_args[0])[0](),
                                    ),
                                )
                        setattr(py_instance, py_field_name, py_list)
                else:
                    # Pointer array of the Go data type, for example: []*excelize.Options or []*string
                    py_list = []
                    l = getattr(ctypes_instance, c_field_name + "Len")
                    c_array = getattr(ctypes_instance, c_field_name)
                    if c_array:
                        if is_py_primitive_type(
                            get_args(get_args(py_field_args[0])[0])[0]
                        ):
                            # Pointer array of the Go basic data type, for example: []*string
                            for i in range(l):
                                py_list.append(
                                    string_at(c_array[i]).decode(ENCODE)
                                    if str is get_args(get_args(py_field_args[0])[0])[0]
                                    else c_array[i].contents.value
                                )
                        else:
                            #  Pointer array of the Go struct, for example: []*excelize.Options
                            for i in range(l):
                                py_list.append(
                                    c_value_to_py(
                                        c_array[i].contents,
                                        get_args(get_args(py_field_args[0])[0])[0](),
                                    ),
                                )
                        setattr(py_instance, py_field_name, py_list)
    return py_instance


def get_c_field_type(struct, field_name):
    """
    Retrieve the type of a specified field from a C structure.

    Args:
        struct (ctypes.Structure): The C structure containing the fields.
        field_name (str): The name of the field whose type is to be retrieved.

    Returns:
        type: The type of the specified field if found, otherwise None.
    """
    for field in struct._fields_:
        if field[0] == field_name:
            return field[1]


def py_value_to_c(py_instance, ctypes_instance):
    """
    Converts a Python instance to a corresponding C instance using ctypes.

    This function recursively converts fields of a Python instance to their
    corresponding C types and assigns them to the provided ctypes instance.
    It handles primitive types, structs, pointers, and arrays.

    Args:
        py_instance (object): The Python instance to be converted.
        ctypes_instance (ctypes.Structure): The ctypes instance to which the
            converted values will be assigned.

    Returns:
        ctypes.Structure: The ctypes instance with the converted values from
            the Python instance.
    """
    if py_instance is None:
        return None
    for py_field in fields(py_instance):
        py_field_name = py_field.name
        c_field_name = snake_to_pascal(py_field.name)
        # The Go base type
        py_field_args = get_args(py_field.type)

        if type(None) not in py_field_args:
            if is_py_primitive_type(py_field.type):
                if hasattr(py_instance, py_field_name):
                    c_type = get_c_field_type(ctypes_instance, c_field_name)
                    setattr(
                        ctypes_instance,
                        c_field_name,
                        py_to_base_ctype(getattr(py_instance, py_field_name), c_type),
                    )
                    continue
            else:
                # The Go struct, for example: excelize.Options, convert sub fields recursively
                c_type = get_c_field_type(ctypes_instance, c_field_name)
                if hasattr(py_instance, py_field_name):
                    setattr(
                        ctypes_instance,
                        c_field_name,
                        py_value_to_c(getattr(py_instance, py_field_name), c_type()),
                    )
        else:
            arg_type = py_field_args[0]
            if get_origin(arg_type) is not list and arg_type is not bytes:
                # Pointer of the Go data type, for example: *excelize.Options or *string
                value = getattr(py_instance, py_field_name)
                c_type = get_c_field_type(ctypes_instance, c_field_name)._type_
                if value is not None:
                    if any(is_py_primitive_type(arg) for arg in py_field_args):
                        # Pointer of the Go basic data type, for example: *string
                        setattr(
                            ctypes_instance,
                            c_field_name,
                            pointer(py_to_base_ctype(value, c_type)),
                        )
                    else:
                        # Pointer of the Go struct, for example: *excelize.Options
                        setattr(
                            ctypes_instance,
                            c_field_name,
                            pointer(py_value_to_c(value, c_type())),
                        )
            else:
                # The Go data type array, for example:
                # []*excelize.Options, []excelize.Options, []string, []*string
                if arg_type is bytes:  # []byte
                    c_type = get_c_field_type(ctypes_instance, c_field_name)._type_
                    value = getattr(py_instance, py_field_name)
                    ctypes_instance.__setattr__(
                        c_field_name, cast(value, POINTER(c_ubyte))
                    )
                    ctypes_instance.__setattr__(c_field_name + "Len", c_int(len(value)))
                    continue
                py_field_type = get_args(arg_type)[0]
                if type(None) not in get_args(py_field_type):
                    # The Go data type array, for example: []excelize.Options or []string
                    c_type = get_c_field_type(ctypes_instance, c_field_name)._type_
                    py_list = getattr(py_instance, py_field_name)
                    if py_list:
                        l = len(py_list)
                        c_array = (c_type * l)()
                        if is_py_primitive_type(py_field_type):
                            # The Go basic data type array, for example: []string
                            if str is py_field_type:
                                c_array_type = POINTER(c_char) * l
                                ctypes_instance.__setattr__(
                                    c_field_name,
                                    c_array_type(
                                        *[
                                            create_string_buffer(c.encode(ENCODE))
                                            for c in py_list
                                        ]
                                    ),
                                )
                            else:
                                for i in range(l):
                                    c_array.__setitem__(
                                        i, py_to_base_ctype(py_list[i], c_type)
                                    )
                                ctypes_instance.__setattr__(c_field_name, c_array)
                        else:
                            # The Go struct array, for example: []excelize.Options
                            for i in range(l):
                                c_array.__setitem__(
                                    i, py_value_to_c(py_list[i], c_type())
                                )
                            ctypes_instance.__setattr__(c_field_name, c_array)
                        ctypes_instance.__setattr__(c_field_name + "Len", c_int(l))

                else:
                    # Pointer array of the Go data type, for example: []*excelize.Options or []*string
                    c_type = get_c_field_type(
                        ctypes_instance, c_field_name
                    )._type_._type_
                    py_list = getattr(py_instance, py_field_name)
                    if py_list:
                        l = len(py_list)
                        c_array = (POINTER(c_type) * l)()
                        if is_py_primitive_type(get_args(py_field_type)[0]):
                            # Pointer array of the Go basic data type, for example: []*string
                            for i in range(l):
                                c_array.__setitem__(
                                    i,
                                    pointer(py_to_base_ctype(py_list[i], c_type)),
                                )
                        else:
                            #  Pointer array of the Go struct, for example: []*excelize.Options
                            for i in range(l):
                                c_array.__setitem__(
                                    i,
                                    pointer(py_value_to_c(py_list[i], c_type())),
                                )
                        ctypes_instance.__setattr__(c_field_name + "Len", c_int(l))
                        ctypes_instance.__setattr__(c_field_name, c_array)
    return ctypes_instance


def py_value_to_c_interface(py_value):
    """
    Converts a Python value to a C interface representation.

    Args:
        py_value: The Python value to be converted.

    Returns:
        An Interface object representing the Python value in a C-compatible format.

    Raises:
        TypeError: If the type of py_value is not supported.
    """
    type_mappings = {
        int: lambda: Interface(type=1, integer=py_value),
        str: lambda: Interface(type=2, string=py_value),
        float: lambda: Interface(type=3, float64=py_value),
        bool: lambda: Interface(type=4, boolean=py_value),
        datetime: lambda: Interface(type=5, integer=int(py_value.timestamp())),
        date: lambda: Interface(
            type=5,
            integer=int(datetime.combine(py_value, time.min).timestamp()),
        ),
    }
    interface = type_mappings.get(type(py_value), lambda: Interface())()
    return py_value_to_c(interface, types_go._Interface())


class File:
    file_index: int

    def __init__(self, file_index):
        self.file_index = file_index

    def save(self, *opts: Options) -> Optional[Exception]:
        """
        Override the spreadsheet with origin path.

        Args:
            *opts (Options): Optional parameters for saving the file.

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.Save.restype = None, c_char_p
        options = POINTER(types_go._Options)()
        options = (
            byref(py_value_to_c(opts[0], types_go._Options()))
            if opts
            else POINTER(types_go._Options)()
        )
        err = lib.Save(self.file_index, options).decode(ENCODE)
        return None if err == "" else Exception(err)

    def save_as(self, filename: str, *opts: Options) -> Optional[Exception]:
        """
        Create or update to a spreadsheet at the provided path.

        Args:
            filename (str): The name of the file to save.
            *opts (Options): Optional parameters for saving the file.

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SaveAs.restype = c_char_p
        options = (
            byref(py_value_to_c(opts[0], types_go._Options()))
            if opts
            else POINTER(types_go._Options)()
        )
        err = lib.SaveAs(self.file_index, filename.encode(ENCODE), options).decode(
            ENCODE
        )
        return None if err == "" else Exception(err)

    def add_chart(
        self, sheet: str, cell: str, chart: Chart, **combo: Chart
    ) -> Optional[Exception]:
        """
        Add chart in a sheet by given chart format set (such as offset, scale,
        aspect ratio setting and print settings) and properties set.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            chart (Chart): Chart options
            **combo (Chart): Optional parameters for combo chart

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.AddChart.restype = c_char_p
        opts = [chart] + list(combo.values())
        charts = (types_go._Chart * len(opts))()
        for i, opt in enumerate(opts):
            charts[i] = py_value_to_c(opt, types_go._Chart())
        err = lib.AddChart(
            self.file_index,
            sheet.encode(ENCODE),
            cell.encode(ENCODE),
            byref(charts),
            len(charts),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def add_chart_sheet(
        self, sheet: str, chart: Chart, **combo: Chart
    ) -> Optional[Exception]:
        """
        Create a chartsheet by given chart format set (such as offset, scale,
        aspect ratio setting and print settings) and properties set. In Excel a
        chartsheet is a worksheet that only contains a chart.

        Args:
            sheet (str): The worksheet name
            chart (Chart): Chart options
            **combo (Chart): Optional parameters for combo chart

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.AddChartSheet.restype = c_char_p
        opts = [chart] + list(combo.values())
        charts = (types_go._Chart * len(opts))()
        for i, opt in enumerate(opts):
            charts[i] = py_value_to_c(opt, types_go._Chart())
        err = lib.AddChartSheet(
            self.file_index,
            sheet.encode(ENCODE),
            byref(charts),
            len(charts),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def add_comment(self, sheet: str, opts: Comment) -> Optional[Exception]:
        """
        Add comments in a sheet by giving the worksheet name, cell reference,
        and format set (such as author and text). Note that the maximum author
        name length is 255 and the max text length is 32512.

        Args:
            sheet (str): The worksheet name
            opts (Comment): The comment options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.AddComment.restype = c_char_p
        options = py_value_to_c(opts, types_go._Comment())
        err = lib.AddComment(
            self.file_index, sheet.encode(ENCODE), byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def add_form_control(self, sheet: str, opts: FormControl) -> Optional[Exception]:
        """
        Add form control button in a worksheet by given worksheet name and form
        control options. Supported form control type: button, check box, group
        box, label, option button, scroll bar and spinner. If set macro for the
        form control, the workbook extension should be XLSM or XLTM. Scroll
        value must be between 0 and 30000.

        Args:
            sheet (str): The worksheet name
            opts (FormControl): The form control options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.AddFormControl.restype = c_char_p
        options = py_value_to_c(opts, types_go._FormControl())
        err = lib.AddFormControl(
            self.file_index, sheet.encode(ENCODE), byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def add_picture(
        self, sheet: str, cell: str, name: str, opts: Optional[GraphicOptions]
    ) -> Optional[Exception]:
        """
        Add picture in a sheet by given picture format set (such as offset,
        scale, aspect ratio setting and print settings) and file path, supported
        image types: BMP, EMF, EMZ, GIF, JPEG, JPG, PNG, SVG, TIF, TIFF, WMF,
        and WMZ.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            name (str): The image file path
            *opts (GraphicOptions): The image options

        Returns:
            Optional[GraphicOptions]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.AddPicture.restype = c_char_p
        options = (
            byref(py_value_to_c(opts, types_go._GraphicOptions()))
            if opts
            else POINTER(types_go._GraphicOptions)()
        )
        err = lib.AddPicture(
            self.file_index,
            sheet.encode(ENCODE),
            cell.encode(ENCODE),
            name.encode(ENCODE),
            options,
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def add_picture_from_bytes(
        self, sheet: str, cell: str, picture: Picture
    ) -> Optional[Exception]:
        """
        Add picture in a sheet by given picture format set (such as offset,
        scale, aspect ratio setting and print settings), file base name,
        extension name and file bytes, supported image types: EMF, EMZ, GIF,
        JPEG, JPG, PNG, SVG, TIF, TIFF, WMF, and WMZ. Note that this function
        only supports adding pictures placed over the cells currently, and
        doesn't support adding pictures placed in cells or creating the Kingsoft
        WPS Office embedded image cells

        Args:
            sheet (str): The worksheet name
            extension (str): The image extension
            picture (Picture): The picture options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.AddPictureFromBytes.restype = c_char_p
        err = lib.AddPictureFromBytes(
            self.file_index,
            sheet.encode(ENCODE),
            cell.encode(ENCODE),
            byref(py_value_to_c(picture, types_go._Picture())),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def add_pivot_table(self, opts: Optional[PivotTableOptions]) -> Optional[Exception]:
        """
        Add pivot table by given pivot table options. Note that the same fields
        can not in Columns, Rows and Filter fields at the same time.

        Args:
            opts (PivotTableOptions): The pivot table options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, create a pivot table on the range reference
            Sheet1!G2:M34 with the range reference Sheet1!A1:E31 as the data
            source, summarize by sum for sales:

            .. code-block:: python

            import excelize
            import random

            f = excelize.new_file()
            month = [
                "Jan", "Feb", "Mar", "Apr", "May", "Jun",
                "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
            ]
            year = [2017, 2018, 2019]
            types = ["Meat", "Dairy", "Beverages", "Produce"]
            region = ["East", "West", "North", "South"]
            err = f.set_sheet_row("Sheet1", "A1", ["Month", "Year", "Type", "Sales", "Region"])
            if err:
                print(err)
            for row in range(2, 32):
                err = f.set_cell_value("Sheet1", f"A{row}", month[random.randrange(12)])
                if err:
                    print(err)
                err = f.set_cell_value("Sheet1", f"B{row}", year[random.randrange(3)])
                if err:
                    print(err)
                err = f.set_cell_value("Sheet1", f"C{row}", types[random.randrange(4)])
                if err:
                    print(err)
                err = f.set_cell_value("Sheet1", f"D{row}", random.randrange(5000))
                if err:
                    print(err)
                err = f.set_cell_value("Sheet1", f"E{row}", region[random.randrange(4)])
                if err:
                    print(err)

            err = f.add_pivot_table(
                excelize.PivotTableOptions(
                    data_range="Sheet1!A1:E31",
                    pivot_table_range="Sheet1!G2:M34",
                    rows=[
                        excelize.PivotTableField(data="Month", default_subtotal=True),
                        excelize.PivotTableField(data="Year"),
                    ],
                    filter=[excelize.PivotTableField(data="Region")],
                    columns=[
                        excelize.PivotTableField(data="Type", default_subtotal=True),
                    ],
                    data=[
                        excelize.PivotTableField(data="Sales", name="Summarize", subtotal="Sum"),
                    ],
                    row_grand_totals=True,
                    col_grand_totals=True,
                    show_drill=True,
                    show_row_headers=True,
                    show_col_headers=True,
                    show_last_column=True,
                )
            )
            if err:
                print(err)
            err = f.save_as("Book1.xlsx")
            if err:
                print(err)
            err = f.close()
            if err:
                print(err)
        """
        lib.AddPivotTable.restype = c_char_p
        err = lib.AddPivotTable(
            self.file_index,
            byref(py_value_to_c(opts, types_go._PivotTableOptions())),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def add_shape(self, sheet: str, opts: Shape) -> Optional[Exception]:
        """
        Add shape in a sheet by given worksheet name and shape format set (such
        as offset, scale, aspect ratio setting and print settings).

        Args:
            sheet (str): The worksheet name
            opts (Shape): The shape options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, add text box (rect shape) in Sheet1:

            .. code-block:: python

            import excelize

            f = excelize.new_file()
            err = f.add_shape(
                "Sheet1",
                excelize.Shape(
                    cell="G6",
                    type="rect",
                    line=excelize.ShapeLine(
                        color="4286F4",
                        width=1.2,
                    ),
                    fill=excelize.Fill(
                        color=["8EB9FF"],
                        pattern=1,
                    ),
                    paragraph=[
                        excelize.RichTextRun(
                            text="Rectangle Shape",
                            font=excelize.Font(
                                bold=True,
                                italic=True,
                                family="Times New Roman",
                                size=19,
                                color="777777",
                                underline="sng",
                            ),
                        )
                    ],
                    width=80,
                    height=40,
                ),
            )
            if err:
                print(err)
            err = f.save_as("Book1.xlsx")
            if err:
                print(err)
            err = f.close()
            if err:
                print(err)
        """
        lib.AddShape.restype = c_char_p
        options = py_value_to_c(opts, types_go._Shape())
        err = lib.AddShape(
            self.file_index, sheet.encode(ENCODE), byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def add_slicer(self, sheet: str, opts: SlicerOptions) -> Optional[Exception]:
        """
        Inserts a slicer by giving the worksheet name and slicer settings.

        Args:
            sheet (str): The worksheet name
            opts (SlicerOptions): The slicer options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, insert a slicer on the Sheet1!E1 with field Column1 for
            the table named Table1:

            .. code-block:: python

            err = f.add_slicer(
                "Sheet1",
                excelize.SlicerOptions(
                    name="Column1",
                    cell="E1",
                    table_sheet="Sheet1",
                    table_name="Table1",
                    caption="Column1",
                    width=200,
                    height=200,
                ),
            )
        """
        lib.AddSlicer.restype = c_char_p
        options = py_value_to_c(opts, types_go._SlicerOptions())
        err = lib.AddSlicer(
            self.file_index, sheet.encode(ENCODE), byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def add_sparkline(self, sheet: str, opts: SparklineOptions) -> Optional[Exception]:
        """
        add sparklines to the worksheet by given formatting options. Sparklines
        are small charts that fit in a single cell and are used to show trends
        in data. Sparklines are a feature of Excel 2010 and later only. You can
        write them to workbook that can be read by Excel 2007, but they won't be
        displayed.

        Args:
            sheet (str): The worksheet name
            opts (SparklineOptions): The sparklines options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, add a grouped sparkline. Changes are applied to all
            three:

            .. code-block:: python

            err = f.add_sparkline(
                "Sheet1",
                excelize.SparklineOptions(
                    location=["A1", "A2", "A3"],
                    range=["Sheet2!A1:J1", "Sheet2!A2:J2", "Sheet2!A3:J3"],
                    markers=True,
                ),
            )
        """
        lib.AddSparkline.restype = c_char_p
        options = py_value_to_c(opts, types_go._SparklineOptions())
        err = lib.AddSparkline(
            self.file_index, sheet.encode(ENCODE), byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def add_table(self, sheet: str, table: Table) -> Optional[Exception]:
        """
        Add table in a worksheet by given worksheet name, range reference and
        format set.

        Note that the table must be at least two lines including the header. The
        header cells must contain strings and must be unique, and must set the
        header row data of the table before calling the AddTable function.
        Multiple tables range reference that can't have an intersection.

        Args:
            sheet (str): The worksheet name
            table (Table): The table options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, create a table of A1:D5 on Sheet1:

            .. code-block:: python

            err = f.add_table("Sheet1", excelize.Table(range="A1:D5"))
        """
        lib.AddTable.restype = c_char_p
        options = py_value_to_c(table, types_go._Table())
        err = lib.AddTable(
            self.file_index, sheet.encode(ENCODE), byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def add_vba_project(self, file: bytes) -> Optional[Exception]:
        """
        Add vbaProject.bin file which contains functions and/or macros. The file
        extension should be XLSM or XLTM.

        Args:
            file (bytes): The contents buffer of the file

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.AddVBAProject.restype = c_char_p
        err = lib.AddVBAProject(
            self.file_index,
            cast(file, POINTER(c_ubyte)),
            len(file),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def auto_filter(
        self,
        sheet: str,
        range_ref: str,
        opts: List[AutoFilterOptions],
    ) -> Optional[Exception]:
        """
        Add auto filter in a worksheet by given worksheet name, range reference
        and settings. An auto filter in Excel is a way of filtering a 2D range
        of data based on some simple criteria.

        Column defines the filter columns in an auto filter range based on simple
        criteria

        It isn't sufficient to just specify the filter condition. You must also
        hide any rows that don't match the filter condition. Rows are hidden using
        the SetRowVisible function. Excelize can't filter rows automatically since
        this isn't part of the file format.

        Args:
            sheet (str): The worksheet name
            range_ref (str): The top-left and right-bottom cell range reference
            opts (List[AutoFilterOptions]): The auto filter options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.AutoFilter.restype = c_char_p
        options = (types_go._AutoFilterOptions * len(opts))()
        for i, opt in enumerate(opts):
            options[i] = py_value_to_c(opt, types_go._AutoFilterOptions())
        err = lib.AutoFilter(
            self.file_index,
            sheet.encode(ENCODE),
            range_ref.encode(ENCODE),
            byref(options),
            len(options),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def calc_cell_value(
        self, sheet: str, cell: str, *opts: Options
    ) -> Tuple[str, Optional[Exception]]:
        """
        Get calculated cell value. This feature is currently in working
        processing. Iterative calculation, implicit intersection, explicit
        intersection, array formula, table formula and some other formulas are
        not supported currently.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            *opts (Options): Optional parameters for get cell value

        Returns:
            Tuple[str, Optional[Exception]]: A tuple containing the calculation
            result as a string and an exception if an error occurred, otherwise
            None.
        """
        lib.CalcCellValue.restype = types_go._StringErrorResult
        options = (
            byref(py_value_to_c(opts[0], types_go._Options()))
            if opts
            else POINTER(types_go._Options)()
        )
        res = lib.CalcCellValue(
            self.file_index, sheet.encode(ENCODE), cell.encode(ENCODE), options
        )
        err = res.err.decode(ENCODE)
        return res.val.decode(ENCODE), None if err == "" else Exception(err)

    def close(self) -> Optional[Exception]:
        """
        Closes and cleanup the open temporary file for the spreadsheet.

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.Close.restype = None, c_char_p
        err = lib.Close(self.file_index).decode(ENCODE)
        return None if err == "" else Exception(err)

    def copy_sheet(self, src: int, to: int) -> Optional[Exception]:
        """
        Duplicate a worksheet by gave source and target worksheet index. Note
        that currently doesn't support duplicate workbooks that contain tables,
        charts or pictures.

        Args:
            src (int): Source sheet index
            to (int): Target sheet index

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.CopySheet.restype = None, c_char_p
        err = lib.CopySheet(self.file_index, src, to).decode(ENCODE)
        return None if err == "" else Exception(err)

    def delete_chart(self, sheet: str, cell: str) -> Optional[Exception]:
        """
        Delete chart in spreadsheet by given worksheet name and cell reference.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.DeleteChart.restype = None, c_char_p
        err = lib.DeleteChart(
            self.file_index, sheet.encode(ENCODE), cell.encode(ENCODE)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def delete_comment(self, sheet: str, cell: str) -> Optional[Exception]:
        """
        Delete comment in a worksheet by given worksheet name and cell reference.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.DeleteComment.restype = None, c_char_p
        err = lib.DeleteComment(
            self.file_index, sheet.encode(ENCODE), cell.encode(ENCODE)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def delete_defined_name(self, defined_name: DefinedName) -> Optional[Exception]:
        """
        Delete the defined names of the workbook or worksheet. If not specified
        scope, the default scope is workbook.

        Args:
            defined_name (DefinedName): The defined name options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example:

            .. code-block:: python

            err = f.delete_defined_name(excelize.DefinedName(
                name="Amount",
                scope="Sheet2",
            ))
        """
        lib.DeleteDefinedName.restype = c_char_p
        options = py_value_to_c(defined_name, types_go._DefinedName())
        err = lib.DeleteDefinedName(self.file_index, byref(options)).decode(ENCODE)
        return None if err == "" else Exception(err)

    def delete_picture(self, sheet: str, cell: str) -> Optional[Exception]:
        """
        Delete all pictures in a cell by given worksheet name and cell reference.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.DeletePicture.restype = None, c_char_p
        err = lib.DeletePicture(
            self.file_index, sheet.encode(ENCODE), cell.encode(ENCODE)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def delete_sheet(self, sheet: str) -> Optional[Exception]:
        """
        Delete worksheet in a workbook by given worksheet name. Use this method
        with caution, which will affect changes in references such as formulas,
        charts, and so on. If there is any referenced value of the deleted
        worksheet, it will cause a file error when you open it. This function
        will be invalid when only one worksheet is left.

        Args:
            sheet (str): The worksheet name

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.DeleteSheet.restype = None, c_char_p
        err = lib.DeleteSheet(self.file_index, sheet.encode(ENCODE)).decode(ENCODE)
        return None if err == "" else Exception(err)

    def delete_slicer(self, name: str) -> Optional[Exception]:
        """
        Delete a slicer by a given slicer name.

        Args:
            name (str): The slicer name

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.DeleteSlicer.restype = None, c_char_p
        err = lib.DeleteSlicer(self.file_index, name.encode(ENCODE)).decode(ENCODE)
        return None if err == "" else Exception(err)

    def duplicate_row(self, sheet: str, row: int) -> Optional[Exception]:
        """
        Inserts a copy of specified row (by its Excel row number) below. Use
        this method with caution, which will affect changes in references such
        as formulas, charts, and so on. If there is any referenced value of the
        worksheet, it will cause a file error when you open it. The excelize
        only partially updates these references currently.

        Args:
            sheet (str): The worksheet name
            row (int): The row number

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.DuplicateRow.restype = None, c_char_p
        err = lib.DuplicateRow(self.file_index, sheet.encode(ENCODE), row).decode(
            ENCODE
        )
        return None if err == "" else Exception(err)

    def duplicate_row_to(self, sheet: str, row: int, row2: int) -> Optional[Exception]:
        """
        Inserts a copy of specified row by it Excel number to specified row
        position moving down exists rows after target position. Use this method
        with caution, which will affect changes in references such as formulas,
        charts, and so on. If there is any referenced value of the worksheet, it
        will cause a file error when you open it. The excelize only partially
        updates these references currently.

        Args:
            sheet (str): The worksheet name
            row (int): The row number
            row2 (int): The row number

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.DuplicateRowTo.restype = None, c_char_p
        err = lib.DuplicateRowTo(
            self.file_index, sheet.encode(ENCODE), row, row2
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def get_active_sheet_index(self) -> int:
        """
        Get active sheet index of the spreadsheet. If not found the active sheet
        will be return integer 0.

        Returns:
            int: The active sheet index
        """
        lib.GetActiveSheetIndex.restype = c_int
        res = lib.GetActiveSheetIndex(self.file_index)
        return res

    def get_app_props(
        self,
    ) -> Tuple[Optional[AppProperties], Optional[Exception]]:
        """
        Get document application properties.

        Returns:
            Tuple[Optional[AppProperties], Optional[Exception]]: A tuple
            containing the app properties if found, otherwise None, and an
            Exception object if an error occurred, otherwise None.
        """
        lib.GetAppProps.restype = types_go._GetAppPropsResult
        res = lib.GetAppProps(self.file_index)
        err = res.err.decode(ENCODE)
        return (c_value_to_py(res.opts, AppProperties()) if err == "" else None), (
            None if err == "" else Exception(err)
        )

    def get_cell_formula(
        self, sheet: str, cell: str
    ) -> Tuple[str, Optional[Exception]]:
        """
        Get formula from cell by given worksheet name and cell reference in
        spreadsheet.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference

        Returns:
            Tuple[str, Optional[Exception]]: A tuple containing the cell formula
            string and an exception if an error occurred, otherwise None.
        """
        lib.GetCellFormula.restype = types_go._StringErrorResult
        res = lib.GetCellFormula(
            self.file_index, sheet.encode(ENCODE), cell.encode(ENCODE)
        )
        err = res.err.decode(ENCODE)
        return res.val.decode(ENCODE), None if err == "" else Exception(err)

    def get_cell_hyperlink(
        self, sheet: str, cell: str
    ) -> Tuple[bool, str, Optional[Exception]]:
        """
        Gets a cell hyperlink based on the given worksheet name and cell
        reference. If the cell has a hyperlink, it will return `True` and the
        link address, otherwise it will return `False` and an empty link address.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference

        Returns:
            Tuple[bool, str, Optional[Exception]]: A tuple containing if the
            cell has a hyperlink, the link address, and an exception if an error
            occurred, otherwise None.

        Example:
            For example, get a hyperlink to a `H6` cell on a worksheet named
            `Sheet1`:

            .. code-block:: python

            link, target, err = f.get_cell_hyperlink("Sheet1", "H6")
        """
        lib.GetCellHyperLink.restype = types_go._GetCellHyperLinkResult
        res = lib.GetCellHyperLink(
            self.file_index, sheet.encode(ENCODE), cell.encode(ENCODE)
        )
        err = res.err.decode(ENCODE)
        return (
            res.link,
            res.target.decode(ENCODE),
            None if err == "" else Exception(err),
        )

    def get_cell_style(self, sheet: str, cell: str) -> Tuple[int, Optional[Exception]]:
        """
        Get cell style index by given worksheet name and cell reference.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference

        Returns:
            Tuple[int, Optional[Exception]]: A tuple containing the cell style,
            and an Exception object if an error occurred, otherwise None.
        """
        lib.GetCellStyle.restype = types_go._IntErrorResult
        res = lib.GetCellStyle(
            self.file_index, sheet.encode(ENCODE), cell.encode(ENCODE)
        )
        err = res.err.decode(ENCODE)
        return res.val, None if err == "" else Exception(err)

    def get_cell_value(
        self, sheet: str, cell: str, *opts: Options
    ) -> Tuple[str, Optional[Exception]]:
        """
        Get formatted value from cell by given worksheet name and cell reference
        in spreadsheet. The return value is converted to the 'string' data type.
        This function is concurrency safe. If the cell format can be applied to
        the value of a cell, the applied value will be returned, otherwise the
        original value will be returned. All cells' values will be the same in a
        merged range.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            *opts (Options): Optional parameters for get cell value

        Returns:
            Tuple[str, Optional[Exception]]: A tuple containing the cell value
            as a string and an exception if an error occurred, otherwise None.
        """
        lib.GetCellValue.restype = types_go._StringErrorResult
        options = (
            byref(py_value_to_c(opts[0], types_go._Options()))
            if opts
            else POINTER(types_go._Options)()
        )
        res = lib.GetCellValue(
            self.file_index, sheet.encode(ENCODE), cell.encode(ENCODE), options
        )
        err = res.err.decode(ENCODE)
        return res.val.decode(ENCODE), None if err == "" else Exception(err)

    def get_rows(
        self, sheet: str, *opts: Options
    ) -> Tuple[List[List[str]], Optional[Exception]]:
        """
        Return all the rows in a sheet by given worksheet name, returned as a
        two-dimensional array, where the value of the cell is converted to the
        string type. If the cell format can be applied to the value of the cell,
        the applied value will be used, otherwise the original value will be
        used. GetRows fetched the rows with value or formula cells, the
        continually blank cells in the tail of each row will be skipped, so the
        length of each row may be inconsistent.

        Args:
            sheet (str): The worksheet name
            *opts (Options): Optional parameters for get rows

        Returns:
            Tuple[List[List[str]], Optional[Exception]]: A tuple containing the
            cell value as a string and an exception if an error occurred,
            otherwise None.
        """
        lib.GetRows.restype = types_go._GetRowsResult
        rows = []
        options = (
            byref(py_value_to_c(opts[0], types_go._Options()))
            if opts
            else POINTER(types_go._Options)()
        )
        res = lib.GetRows(self.file_index, sheet.encode(ENCODE), options)
        err = res.err.decode(ENCODE)
        result = c_value_to_py(res, GetRowsResult()).row

        if result:
            for row in result:
                if row.cell:
                    rows.append([cell for cell in row.cell])

        return rows, None if err == "" else Exception(err)

    def get_sheet_dimension(self, sheet: str) -> Tuple[str, Optional[Exception]]:
        """
        Get style definition by given style index.

        Args:
            sheet (str): The worksheet name

        Returns:
            Tuple[str, Optional[Exception]]: A tuple containing the sheet
            dimension, and an Exception object if an error occurred, otherwise
            None.
        """
        lib.GetSheetDimension.restype = types_go._StringErrorResult
        res = lib.GetSheetDimension(self.file_index, sheet.encode(ENCODE))
        err = res.err.decode(ENCODE)
        return res.val.decode(ENCODE), None if err == "" else Exception(err)

    def get_sheet_index(self, sheet: str) -> Tuple[int, Optional[Exception]]:
        """
        Get a sheet index of the workbook by the given sheet name. If the given
        sheet name is invalid or sheet doesn't exist, it will return an integer
        type value -1.

        Args:
            sheet (str): The worksheet name

        Returns:
            Tuple[int, Optional[Exception]]: A tuple containing the sheet index,
            and an Exception object if an error occurred, otherwise None.
        """
        lib.GetSheetIndex.restype = types_go._IntErrorResult
        res = lib.GetSheetIndex(self.file_index, sheet.encode(ENCODE))
        err = res.err.decode(ENCODE)
        return res.val, None if err == "" else Exception(err)

    def get_style(self, style_id: int) -> Tuple[Optional[Style], Optional[Exception]]:
        """
        Get style definition by given style index.

        Args:
            style_id (int): The style ID

        Returns:
            Tuple[Optional[Style], Optional[Exception]]: A tuple containing the
            Style object if found, otherwise None, and an Exception object if an
            error occurred, otherwise None.
        """
        lib.GetStyle.restype = types_go._GetStyleResult
        res = lib.GetStyle(self.file_index, c_int(style_id))
        err = res.err.decode(ENCODE)
        if err == "":
            return c_value_to_py(res.style, Style()), None
        return None, Exception(err)

    def get_tables(self, sheet: str) -> Tuple[List[Table], Optional[Exception]]:
        """
        Get all tables in a worksheet by given worksheet name.

        Args:
            sheet (str): The worksheet name

        Returns:
            Tuple[List[Table], Optional[Exception]]: A tuple containing the
            tables and an exception if an error occurred, otherwise None.
        """
        lib.GetTables.restype = types_go._GetTablesResult
        res = lib.GetTables(self.file_index, sheet.encode(ENCODE))
        tables = c_value_to_py(res, GetTablesResult()).tables
        err = res.Err.decode(ENCODE)
        return tables, None if err == "" else Exception(err)

    def insert_cols(self, sheet: str, col: str, n: int) -> Optional[Exception]:
        """
        Insert new columns before the given column name and number of columns.
        Use this method with caution, which will affect changes in references
        such as formulas, charts, and so on. If there is any referenced value of
        the worksheet, it will cause a file error when you open it. The excelize
        only partially updates these references currently.

        Args:
            sheet (str): The worksheet name
            col (str): The column name
            n (int): The columns

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, create two columns before column C in Sheet1:

            .. code-block:: python

            err = f.insert_cols("Sheet1", "C", 2)
        """
        lib.InsertCols.restype = c_char_p
        err = lib.InsertCols(
            self.file_index,
            sheet.encode(ENCODE),
            col.encode(ENCODE),
            c_int(n),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def merge_cell(
        self, sheet: str, top_left_cell: str, bottom_right_cell: str
    ) -> Optional[Exception]:
        """
        Merge cells by given range reference and sheet name. Merging cells only
        keeps the upper-left cell value, and discards the other values.

        Args:
            sheet (str): The worksheet name
            top_left_cell (str): The top-left cell reference
            bottom_right_cell (str): The right-bottom cell reference

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.MergeCell.restype = c_char_p
        err = lib.MergeCell(
            self.file_index,
            sheet.encode(ENCODE),
            top_left_cell.encode(ENCODE),
            bottom_right_cell.encode(ENCODE),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def move_sheet(self, source: str, target: str) -> Optional[Exception]:
        """
        Moves a sheet to a specified position in the workbook. The function
        moves the source sheet before the target sheet. After moving, other
        sheets will be shifted to the left or right. If the sheet is already at
        the target position, the function will not perform any action. Not that
        this function will be ungroup all sheets after moving.

        Args:
            source (str): The source worksheet name
            target (str): The target worksheet name

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, move Sheet2 before Sheet1:

            .. code-block:: python

            err = f.move_sheet("Sheet2", "Sheet1")
        """
        lib.MoveSheet.restype = c_char_p
        err = lib.MoveSheet(
            self.file_index,
            source.encode(ENCODE),
            target.encode(ENCODE),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def new_conditional_style(self, style: Style) -> Tuple[int, Optional[Exception]]:
        """
        Create style for conditional format by given style format. The
        parameters are the same with the new_style function.

        Args:
            style (Style): The style options

        Returns:
            Tuple[int, Optional[Exception]]: A tuple containing the style index
            and an exception if any error occurs.
        """
        lib.NewConditionalStyle.restype = types_go._IntErrorResult
        options = py_value_to_c(style, types_go._Style())
        res = lib.NewConditionalStyle(self.file_index, byref(options))
        err = res.err.decode(ENCODE)
        return res.val, None if err == "" else Exception(err)

    def new_sheet(self, sheet: str) -> Tuple[int, Optional[Exception]]:
        """
        Create a new sheet by given a worksheet name and returns the index of
        the sheets in the workbook after it appended. Note that when creating a
        new workbook, the default worksheet named `Sheet1` will be created.

        Args:
            sheet (str): The worksheet name

        Returns:
            Tuple[int, Optional[Exception]]: A tuple containing the index of the
            new sheet and an Exception if an error occurred, otherwise None.
        """
        lib.NewSheet.restype = types_go._IntErrorResult
        res = lib.NewSheet(self.file_index, sheet.encode(ENCODE))
        err = res.err.decode(ENCODE)
        return res.val, None if err == "" else Exception(err)

    def new_style(self, style: Style) -> Tuple[int, Optional[Exception]]:
        """
        Create the style for cells by a given style options, and returns style
        index. The same style index can not be used across different workbook.
        This function is concurrency safe. Note that the 'Font.Color' field uses
        an RGB color represented in 'RRGGBB' hexadecimal notation.

        Args:
            style (Style): The style options

        Returns:
            Tuple[int, Optional[Exception]]: A tuple containing the style index
            and an exception if any error occurs.
        """
        lib.NewStyle.restype = types_go._IntErrorResult
        options = py_value_to_c(style, types_go._Style())
        res = lib.NewStyle(self.file_index, byref(options))
        err = res.err.decode(ENCODE)
        return res.val, None if err == "" else Exception(err)

    def protect_sheet(
        self, sheet: str, opts: SheetProtectionOptions
    ) -> Optional[Exception]:
        """
        Prevent other users from accidentally or deliberately changing, moving,
        or deleting data in a worksheet. The optional field AlgorithmName
        specified hash algorithm, support XOR, MD4, MD5, SHA-1, SHA2-56,
        SHA-384, and SHA-512 currently, if no hash algorithm specified, will be
        using the XOR algorithm as default.

        Args:
            sheet (str): The worksheet name
            opts (SheetProtectionOptions): The sheet protection options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, protect Sheet1 with protection settings:

            .. code-block:: python

            err = f.protect_sheet("Sheet1", excelize.SheetProtectionOptions(
                algorithm_name="SHA-512",
                password="password",
                select_locked_cells=True,
                select_unlocked_cells=True,
                edit_scenarios=True,
            ))
        """
        lib.ProtectSheet.restype = c_char_p
        options = py_value_to_c(opts, types_go._SheetProtectionOptions())
        err = lib.ProtectSheet(
            self.file_index, sheet.encode(ENCODE), byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def protect_workbook(self, opts: WorkbookProtectionOptions) -> Optional[Exception]:
        """
        Prevent other users from viewing hidden worksheets, adding, moving,
        deleting, or hiding worksheets, and renaming worksheets in a workbook.
        The optional field AlgorithmName specified hash algorithm, support XOR,
        MD4, MD5, SHA-1, SHA2-56, SHA-384, and SHA-512 currently, if no hash
        algorithm specified, will be using the XOR algorithm as default. The
        generated workbook only works on Microsoft Office 2007 and later.

        Args:
            opts (WorkbookProtectionOptions): The workbook protection options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, protect workbook with protection settings:

            .. code-block:: python

            err = f.protect_workbook(excelize.WorkbookProtectionOptions(
                password="password",
                lock_structure=True,
            ))
        """
        lib.ProtectWorkbook.restype = c_char_p
        options = py_value_to_c(opts, types_go._WorkbookProtectionOptions())
        err = lib.ProtectWorkbook(self.file_index, byref(options)).decode(ENCODE)
        return None if err == "" else Exception(err)

    def remove_col(self, sheet: str, col: str) -> Optional[Exception]:
        """
        Remove single column by given worksheet name and column index.
        Use this method with caution, which will affect changes in references
        such as formulas, charts, and so on. If there is any referenced value of
        the worksheet, it will cause a file error when you open it. The excelize
        only partially updates these references currently.

        Args:
            sheet (str): The worksheet name
            col (str): The column name

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, remove column C in Sheet1:

            .. code-block:: python

            err = f.remove_col("Sheet1", "C")
        """
        lib.RemoveCol.restype = c_char_p
        err = lib.RemoveCol(
            self.file_index, sheet.encode(ENCODE), col.encode(ENCODE)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def remove_page_break(self, sheet: str, cell: str) -> Optional[Exception]:
        """
        Remove a page break by given worksheet name and cell reference.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.RemovePageBreak.restype = c_char_p
        err = lib.RemovePageBreak(
            self.file_index, sheet.encode(ENCODE), cell.encode(ENCODE)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def remove_row(self, sheet: str, row: int) -> Optional[Exception]:
        """
        Remove single row by given worksheet name and Excel row number. Use this
        method with caution, which will affect changes in references such as
        formulas, charts, and so on. If there is any referenced value of the
        worksheet, it will cause a file error when you open it. The excelize
        only partially updates these references currently.

        Args:
            sheet (str): The worksheet name
            row (int): The row number

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, remove row 3 in Sheet1:

            .. code-block:: python

            err = f.remove_row("Sheet1", 3)
        """
        lib.RemoveRow.restype = c_char_p
        err = lib.RemoveRow(self.file_index, sheet.encode(ENCODE), c_int(row)).decode(
            ENCODE
        )
        return None if err == "" else Exception(err)

    def set_active_sheet(self, index: int) -> Optional[Exception]:
        """
        Set the default active sheet of the workbook by a given index. Note that
        the active index is different from the ID returned by function
        get_sheet_map. It should be greater than or equal to 0 and less than the
        total worksheet numbers.

        Args:
            index (int): The sheet index

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.SetActiveSheet.restype = None, c_char_p
        err = lib.SetActiveSheet(self.file_index, index).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_cell_bool(self, sheet: str, cell: str, value: bool) -> Optional[Exception]:
        """
        Set bool type value of a cell by given worksheet name, cell reference and
        cell value.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            value (bool): The cell value

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.SetCellBool.restype = None, c_char_p
        err = lib.SetCellBool(
            self.file_index, sheet.encode(ENCODE), cell.encode(ENCODE), value
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_cell_formula(
        self, sheet: str, cell: str, formula: str, *opts: FormulaOpts
    ) -> Optional[Exception]:
        """
        Set formula on the cell is taken according to the given worksheet name
        and cell formula settings. The result of the formula cell can be
        calculated when the worksheet is opened by the Office Excel application
        or can be using the "CalcCellValue" function also can get the calculated
        cell value. If the Excel application doesn't calculate the formula
        automatically when the workbook has been opened, please call
        "update_linked_value" after setting the cell formula functions.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            formula (str): The cell formula
            *opts (FormulaOpts): The formula options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        err, lib.SetCellFormula.restype = None, c_char_p
        options = (
            byref(py_value_to_c(opts[0], types_go._FormulaOpts()))
            if opts
            else POINTER(types_go._FormulaOpts)()
        )
        err = lib.SetCellFormula(
            self.file_index,
            sheet.encode(ENCODE),
            cell.encode(ENCODE),
            formula.encode(ENCODE),
            options,
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_cell_hyperlink(
        self,
        sheet: str,
        cell: str,
        link: str,
        link_type: str,
        *opts: HyperlinkOpts,
    ) -> Optional[Exception]:
        """
        Set cell hyperlink by given worksheet name and link URL address. The
        `link_type` defines three types of hyperlink "External" for website or
        "Location" for moving to one of cell in this workbook or "None" for
        remove hyperlink. Maximum limit hyperlinks in a worksheet is 65530.
        This function is only used to set the hyperlink of the cell and doesn't
        affect the value of the cell. If you need to set the value of the cell
        please use the other functions such as `set_cell_style` or
        `set_sheet_row`.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            link (str): The hyperlink
            link_type (str): The hyperlink type
            *opts (HyperlinkOpts): The hyperlink options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            The below is example for external link.

            .. code-block:: python

            display = "https://github.com/xuri/excelize"
            err = f.set_cell_hyperlink(
                "Sheet1",
                "A3",
                display,
                "External",
                excelize.HyperlinkOpts(display=display, tooltip="Excelize on GitHub"),
            )
            if err:
                print(err)
            # Set underline and font color style for the cell.
            style, err = f.new_style(
                excelize.Style(
                    font=excelize.Font(color="1265BE", underline="single")
                )
            )
            if err:
                print(err)
            err = f.set_cell_style("Sheet1", "A3", "A3", style)
        """
        err, lib.SetCellHyperLink.restype = None, c_char_p
        options = (
            byref(py_value_to_c(opts[0], types_go._HyperlinkOpts()))
            if opts
            else POINTER(types_go._HyperlinkOpts)()
        )
        err = lib.SetCellHyperLink(
            self.file_index,
            sheet.encode(ENCODE),
            cell.encode(ENCODE),
            link.encode(ENCODE),
            link_type.encode(ENCODE),
            options,
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_cell_int(
        self,
        sheet: str,
        cell: str,
        value: int,
    ) -> Optional[Exception]:
        """
        Set int type value of a cell by given worksheet name, cell reference and
        cell value.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            value (int): The cell value

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetCellInt.restype = c_char_p
        err = lib.SetCellInt(
            self.file_index,
            sheet.encode(ENCODE),
            cell.encode(ENCODE),
            value,
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_cell_rich_text(
        self,
        sheet: str,
        cell: str,
        runs: List[RichTextRun],
    ) -> Optional[Exception]:
        """
        Set cell with rich text by given worksheet name, cell reference and rich
        text runs.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            runs (List[RichTextRun]): The rich text runs

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.


        Example:
            For example, set rich text on the A1 cell of the worksheet named
            Sheet1:

            .. code-block:: python

            f = excelize.new_file()
            err = f.set_row_height("Sheet1", 1, 35)
            if err:
                print(err)
            err = f.set_col_width("Sheet1", "A", "A", 44)
            if err:
                print(err)
            err = f.set_cell_rich_text(
                "Sheet1",
                "A1",
                [
                    excelize.RichTextRun(
                        text="bold",
                        font=excelize.Font(
                            bold=True,
                            color="2354e8",
                            family="Times New Roman",
                        ),
                    ),
                    excelize.RichTextRun(
                        text=" and ",
                        font=excelize.Font(
                            family="Times New Roman",
                        ),
                    ),
                    excelize.RichTextRun(
                        text="italic ",
                        font=excelize.Font(
                            bold=True,
                            color="e83723",
                            italic=True,
                            family="Times New Roman",
                        ),
                    ),
                    excelize.RichTextRun(
                        text="text with color and font-family,",
                        font=excelize.Font(
                            bold=True,
                            color="2354e8",
                            family="Times New Roman",
                        ),
                    ),
                    excelize.RichTextRun(
                        text="\r\nlarge text with ",
                        font=excelize.Font(
                            size=14,
                            color="ad23e8",
                        ),
                    ),
                    excelize.RichTextRun(
                        text="strike",
                        font=excelize.Font(
                            color="e89923",
                            strike=True,
                        ),
                    ),
                    excelize.RichTextRun(
                        text=" superscript",
                        font=excelize.Font(
                            color="dbc21f",
                            vert_align="superscript",
                        ),
                    ),
                    excelize.RichTextRun(
                        text=" and ",
                        font=excelize.Font(
                            size=14,
                            color="ad23e8",
                            vert_align="baseline",
                        ),
                    ),
                    excelize.RichTextRun(
                        text="underline",
                        font=excelize.Font(
                            color="23e833",
                            vert_align="single",
                        ),
                    ),
                    excelize.RichTextRun(
                        text=" subscript.",
                        font=excelize.Font(
                            color="017505",
                            vert_align="subscript",
                        ),
                    ),
                ],
            )
            if err:
                print(err)
            style, err = f.new_style(
                excelize.Style(
                    alignment=excelize.Alignment(wrap_text=True),
                )
            )
            if err:
                print(err)
            err = f.set_cell_style("Sheet1", "A1", "A1", style)
            if err:
                print(err)
            err = f.save_as("Book1.xlsx")
            if err:
                print(err)
            err = f.close()
            if err:
                print(err)
        """
        lib.SetCellRichText.restype = c_char_p
        vals = (types_go._RichTextRun * len(runs))()
        for i, value in enumerate(runs):
            vals[i] = py_value_to_c(value, types_go._RichTextRun())
        err = lib.SetCellRichText(
            self.file_index,
            sheet.encode(ENCODE),
            cell.encode(ENCODE),
            byref(vals),
            len(vals),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_cell_str(
        self,
        sheet: str,
        cell: str,
        value: str,
    ) -> Optional[Exception]:
        """
        Set string type value of a cell. Total number of characters that a cell
        can contain 32767 characters.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            value (str): The cell value

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetCellStr.restype = c_char_p
        err = lib.SetCellStr(
            self.file_index,
            sheet.encode(ENCODE),
            cell.encode(ENCODE),
            value.encode(ENCODE),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_cell_style(
        self,
        sheet: str,
        top_left_cell: str,
        bottom_right_cell: str,
        style_id: int,
    ) -> Optional[Exception]:
        """
        Add style attribute for cells by given worksheet name, range reference
        and style ID. Note that diagonalDown and diagonalUp type border should
        be use same color in the same range. SetCellStyle will overwrite the
        existing styles for the cell, it won't append or merge style with
        existing styles.

        Args:
            sheet (str): The worksheet name
            top_left_cell (str): The top-left cell reference
            bottom_right_cell (str): The right-bottom cell reference
            style_id (int): The style ID

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetCellStyle.restype = c_char_p
        err = lib.SetCellStyle(
            self.file_index,
            sheet.encode(ENCODE),
            top_left_cell.encode(ENCODE),
            bottom_right_cell.encode(ENCODE),
            style_id,
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_cell_value(
        self,
        sheet: str,
        cell: str,
        value: Union[None, int, str, bool, datetime, date],
    ) -> Optional[Exception]:
        """
        Set the value of a cell. The specified coordinates should not be in the
        first row of the table, a complex number can be set with string text.

        Note that default date format is m/d/yy h:mm of time.Time type value.
        You can set numbers format by the SetCellStyle function. If you need to
        set the specialized date in Excel like January 0, 1900 or February 29,
        1900, these times can not representation in Go language time.Time data
        type. Please set the cell value as number 0 or 60, then create and bind
        the date-time number format style for the cell.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            value (Union[None, int, str, bool, datetime, date]): The cell value
            to be write

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetCellValue.restype = c_char_p
        err = lib.SetCellValue(
            self.file_index,
            sheet.encode(ENCODE),
            cell.encode(ENCODE),
            byref(py_value_to_c_interface(value)),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_col_outline_level(
        self, sheet: str, col: str, level: int
    ) -> Optional[Exception]:
        """
        Set outline level of a single column by given worksheet name and column
        name.

        Args:
            sheet (str): The worksheet name
            col (str): The column name
            level (int): The out level, acceptable value from 1 to 7

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, set outline level of column D in Sheet1 to 2:

            .. code-block:: python

            err = f.set_col_outline_level("Sheet1", "D", 2)
        """
        lib.SetColOutlineLevel.restype = c_char_p
        err = lib.SetColOutlineLevel(
            self.file_index, sheet.encode(ENCODE), col.encode(ENCODE), level
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_col_style(
        self, sheet: str, columns: str, style_id: int
    ) -> Optional[Exception]:
        """
        Set style of columns by given worksheet name, columns range and style
        ID. This function is concurrency safe. Note that this will overwrite the
        existing styles for the columns, it won't append or merge style with
        existing styles.

        Args:
            sheet (str): The worksheet name
            columns (str): The columns range
            style_id (int): The style ID

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example set style of column H on Sheet1:

            .. code-block:: python

            err = f.set_col_style("Sheet1", "H", style)
        """
        lib.SetColStyle.restype = c_char_p
        err = lib.SetColStyle(
            self.file_index, sheet.encode(ENCODE), columns.encode(ENCODE), style_id
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_col_visible(
        self, sheet: str, columns: str, visible: bool
    ) -> Optional[Exception]:
        """
        Set visible columns by given worksheet name, columns range and
        visibility.

        Args:
            sheet (str): The worksheet name
            columns (str): The columns range
            visible (bool): The column visible

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example hide column D on Sheet1:

            .. code-block:: python

            err = f.set_col_visible("Sheet1", "D", False)
        """
        lib.SetColVisible.restype = c_char_p
        err = lib.SetColVisible(
            self.file_index, sheet.encode(ENCODE), columns.encode(ENCODE), visible
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_col_width(
        self, sheet: str, start_col: str, end_col: str, width: float
    ) -> Optional[Exception]:
        """
        Set the width of a single column or multiple columns.

        Args:
            sheet (str): The worksheet name
            start_col (str): The start column name
            end_col (bool): The end column name
            width (float): The column width

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example set column width for column A to H on Sheet1:

            .. code-block:: python

            err = f.set_col_width("Sheet1", "A", "H", 20)
        """
        lib.SetColWidth.restype = c_char_p
        err = lib.SetColWidth(
            self.file_index,
            sheet.encode(ENCODE),
            start_col.encode(ENCODE),
            end_col.encode(ENCODE),
            c_double(width),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_conditional_format(
        self,
        sheet: str,
        range_ref: str,
        opts: List[ConditionalFormatOptions],
    ) -> Optional[Exception]:
        """
        Create conditional formatting rule for cell value. Conditional
        formatting is a feature of Excel which allows you to apply a format to a
        cell or a range of cells based on certain criteria.

        Args:
            sheet (str): The worksheet name
            range_ref (str): The top-left and right-bottom cell range reference
            opts (List[ConditionalFormatOptions]): The conditional format options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetConditionalFormat.restype = c_char_p
        vals = (types_go._ConditionalFormatOptions * len(opts))()
        for i, value in enumerate(opts):
            vals[i] = py_value_to_c(value, types_go._ConditionalFormatOptions())
        err = lib.SetConditionalFormat(
            self.file_index,
            sheet.encode(ENCODE),
            range_ref.encode(ENCODE),
            byref(vals),
            len(vals),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_default_font(self, font_name: str) -> Optional[Exception]:
        """
        Set the default font name in the workbook. The spreadsheet generated by
        excelize default font is Calibri.

        Args:
            font_name (str): The font name

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetDefaultFont.restype = c_char_p
        err = lib.SetDefaultFont(self.file_index, font_name.encode(ENCODE)).decode(
            ENCODE
        )
        return None if err == "" else Exception(err)

    def set_defined_name(self, defined_name: DefinedName) -> Optional[Exception]:
        """
        Set the defined names of the workbook or worksheet. If not specified
        scope, the default scope is workbook.

        Args:
            defined_name (DefinedName): The defined name options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, create a table of A1:D5 on Sheet1:

            .. code-block:: python

            err = f.set_defined_name(excelize.DefinedName(
                name="Amount",
                refers_to="Sheet1!$A$2:$D$5",
                comment="defined name comment",
                scope="Sheet2",
            ))
        """
        lib.SetDefinedName.restype = c_char_p
        options = py_value_to_c(defined_name, types_go._DefinedName())
        err = lib.SetDefinedName(self.file_index, byref(options)).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_header_footer(
        self, sheet: str, opts: HeaderFooterOptions
    ) -> Optional[Exception]:
        """
        Set headers and footers by given worksheet name and the control
        characters.

        Args:
            sheet (str): The worksheet name
            opts (HeaderFooterOptions): The header footer options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example:

            .. code-block:: python

            err = f.set_header_footer(
                "Sheet1",
                excelize.HeaderFooterOptions(
                    different_first=True,
                    different_odd_even=True,
                    odd_header="&R&P",
                    odd_footer="&C&F",
                    even_header="&L&P",
                    even_footer="&L&D&R&T",
                    first_header="&CCenter &\"-,Bold\"Bold&\"-,Regular\"HeaderU+000A&D",
                ),
            )
        """
        lib.SetHeaderFooter.restype = c_char_p
        options = py_value_to_c(opts, types_go._HeaderFooterOptions())
        err = lib.SetHeaderFooter(
            self.file_index, sheet.encode(ENCODE), byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_page_layout(
        self, sheet: str, opts: PageLayoutOptions
    ) -> Optional[Exception]:
        """
        Sets worksheet page layout.

        Args:
            sheet (str): The worksheet name
            opts (PageLayoutOptions): The page layout options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetPageLayout.restype = c_char_p
        options = py_value_to_c(opts, types_go._PageLayoutOptions())
        err = lib.SetPageLayout(
            self.file_index, sheet.encode(ENCODE), byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_page_margins(
        self, sheet: str, opts: PageLayoutMarginsOptions
    ) -> Optional[Exception]:
        """
        Set worksheet page margins.

        Args:
            sheet (str): The worksheet name
            opts (PageLayoutMarginsOptions): The page margins options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetPageMargins.restype = c_char_p
        options = py_value_to_c(opts, types_go._PageLayoutMarginsOptions())
        err = lib.SetPageMargins(
            self.file_index, sheet.encode(ENCODE), byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_panes(self, sheet: str, opts: Panes) -> Optional[Exception]:
        """
        Create and remove freeze panes and split panes by given worksheet name
        and panes options.

        Args:
            sheet (str): The worksheet name
            opts (Panes): The panes options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetPanes.restype = c_char_p
        options = py_value_to_c(opts, types_go._Panes())
        err = lib.SetPanes(
            self.file_index, sheet.encode(ENCODE), byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_row_height(
        self, sheet: str, row: int, height: float
    ) -> Optional[Exception]:
        """
        Set the height of a single row. If the value of height is 0, will hide
        the specified row, if the value of height is -1, will unset the custom
        row height.

        Args:
            sheet (str): The worksheet name
            row (int): The row number
            height (float): The row height

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, set the height of the first row in Sheet1:

            .. code-block:: python

            err = f.set_row_height("Sheet1", 1, 50)
        """
        lib.SetRowHeight.restype = c_char_p
        err = lib.SetRowHeight(
            self.file_index, sheet.encode(ENCODE), c_int(row), c_double(height)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_row_outline(self, sheet: str, row: int, level: int) -> Optional[Exception]:
        """
        Set outline level number of a single row by given worksheet name and
        Excel row number. The value of parameter 'level' is 1-7.

        Args:
            sheet (str): The worksheet name
            row (int): The row number
            level (int): The outline level

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, outline row 2 in Sheet1 to level 1:

            .. code-block:: python

            err = f.set_row_outline("Sheet1", 2, 1)
        """
        lib.SetRowOutlineLevel.restype = c_char_p
        err = lib.SetRowOutlineLevel(
            self.file_index, sheet.encode(ENCODE), c_int(row), c_int(level)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_row_style(
        self, sheet: str, start: int, end: int, style_id: int
    ) -> Optional[Exception]:
        """
        Set the style of rows by given worksheet name, row range, and style ID.
        Note that this will overwrite the existing styles for the rows, it won't
        append or merge style with existing styles.

        Args:
            sheet (str): The worksheet name
            start (int): The start row number
            end (int): The end row number
            style_id (int): The style ID

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example set style of row 1 on Sheet1:

            .. code-block:: python

            err = f.set_row_style("Sheet1", 1, 1, style_id)
        """
        lib.SetRowStyle.restype = c_char_p
        err = lib.SetRowStyle(
            self.file_index,
            sheet.encode(ENCODE),
            c_int(start),
            c_int(end),
            c_int(style_id),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_row_visible(
        self, sheet: str, row: int, visible: bool
    ) -> Optional[Exception]:
        """
        Set visible of a single row by given worksheet name and Excel row
        number.

        Args:
            sheet (str): The worksheet name
            row (int): The row number
            visible (bool): The row's visibility

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            For example, hide row 2 in Sheet1:

            .. code-block:: python

            err = f.set_row_visible("Sheet1", 2, False)
        """
        lib.SetRowVisible.restype = c_char_p
        err = lib.SetRowVisible(
            self.file_index,
            sheet.encode(ENCODE),
            c_int(row),
            c_bool(visible),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_sheet_background(self, sheet: str, picture: str) -> Optional[Exception]:
        """
        Set background picture by given worksheet name and file path. Supported
        image types: BMP, EMF, EMZ, GIF, JPEG, JPG, PNG, SVG, TIF, TIFF, WMF,
        and WMZ.

        Args:
            sheet (str): The worksheet name
            picture (str): The image file path

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetSheetBackground.restype = c_char_p
        err = lib.SetSheetBackground(
            self.file_index,
            sheet.encode(ENCODE),
            picture.encode(ENCODE),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_sheet_background_from_bytes(
        self, sheet: str, extension: str, picture: bytes
    ) -> Optional[Exception]:
        """
        Set background picture by given worksheet name, extension name and image
        data. Supported image types: BMP, EMF, EMZ, GIF, JPEG, JPG, PNG, SVG,
        TIF, TIFF, WMF, and WMZ.

        Args:
            sheet (str): The worksheet name
            extension (str): The image extension
            picture (bytes): The contents buffer of the file

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetSheetBackgroundFromBytes.restype = c_char_p
        err = lib.SetSheetBackgroundFromBytes(
            self.file_index,
            sheet.encode(ENCODE),
            extension.encode(ENCODE),
            cast(picture, POINTER(c_ubyte)),
            len(picture),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_sheet_col(
        self,
        sheet: str,
        cell: str,
        values: List[Union[None, int, str, bool, datetime, date]],
    ) -> Optional[Exception]:
        """
        Writes cells to column by given worksheet name, starting cell reference
        and cell values list.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            values (List[Union[None, int, str, bool, datetime, date]]): The cell
            values

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetSheetCol.restype = c_char_p
        vals = (types_go._Interface * len(values))()
        for i, value in enumerate(values):
            vals[i] = py_value_to_c_interface(value)
        err = lib.SetSheetCol(
            self.file_index,
            sheet.encode(ENCODE),
            cell.encode(ENCODE),
            byref(vals),
            len(vals),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_sheet_dimension(self, sheet: str, range_ref: str) -> Optional[Exception]:
        """
        Set or remove the used range of the worksheet by a given range
        reference. It specifies the row and column bounds of used cells in the
        worksheet. The range reference is set using the A1 reference style
        (e.g., "A1:D5"). Passing an empty range reference will remove the used
        range of the worksheet.

        Args:
            sheet (str): The worksheet name
            range_ref (str): The top-left and right-bottom cell range reference

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetSheetDimension.restype = c_char_p
        err = lib.SetSheetDimension(
            self.file_index,
            sheet.encode(ENCODE),
            range_ref.encode(ENCODE),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_sheet_name(self, source: str, target: str) -> Optional[Exception]:
        """
        Set the worksheet name by given source and target worksheet names.
        Maximum 31 characters are allowed in sheet title and this function only
        changes the name of the sheet and will not update the sheet name in the
        formula or reference associated with the cell. So there may be problem
        formula error or reference missing.

        Args:
            source (str): The source sheet name
            target (str): The target sheet name

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetSheetName.restype = c_char_p
        err = lib.SetSheetName(
            self.file_index,
            source.encode(ENCODE),
            target.encode(ENCODE),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_sheet_props(
        self, sheet: str, opts: SheetPropsOptions
    ) -> Optional[Exception]:
        """
        Set worksheet properties.

        Args:
            sheet (str): The worksheet name
            opts (SheetPropsOptions): The sheet properties options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetSheetProps.restype = c_char_p
        options = py_value_to_c(opts, types_go._SheetPropsOptions())
        err = lib.SetSheetProps(
            self.file_index, sheet.encode(ENCODE), byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_sheet_row(
        self,
        sheet: str,
        cell: str,
        values: List[Union[None, int, str, bool, datetime, date]],
    ) -> Optional[Exception]:
        """
        Writes cells to row by given worksheet name, starting cell reference and
        cell values list.

        Args:
            sheet (str): The worksheet name
            cell (str): The cell reference
            values (List[Union[None, int, str, bool, datetime, date]]): The cell
            values

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetSheetRow.restype = c_char_p
        vals = (types_go._Interface * len(values))()
        for i, value in enumerate(values):
            vals[i] = py_value_to_c_interface(value)
        err = lib.SetSheetRow(
            self.file_index,
            sheet.encode(ENCODE),
            cell.encode(ENCODE),
            byref(vals),
            len(vals),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_sheet_view(
        self, sheet: str, view_index: int, opts: ViewOptions
    ) -> Optional[Exception]:
        """
        Sets sheet view options. The viewIndex may be negative and if so is
        counted backward (-1 is the last view).

        Args:
            sheet (str): The worksheet name
            view_index (int): The sheet view index
            opts (ViewOptions): The sheet view options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetSheetView.restype = c_char_p
        options = py_value_to_c(opts, types_go._ViewOptions())
        err = lib.SetSheetView(
            self.file_index, sheet.encode(ENCODE), view_index, byref(options)
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_sheet_visible(
        self, sheet: str, visible: bool, *very_hidden: bool
    ) -> Optional[Exception]:
        """
        Set worksheet visible by given worksheet name. A workbook must contain
        at least one visible worksheet. If the given worksheet has been
        activated, this setting will be invalidated. The third optional
        very_hidden parameter only works when visible was false.

        Args:
            sheet (str): The worksheet name
            visible (bool): The worksheet visibility
            *very_hidden (bool): Optional boolean very hidden parameter

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetSheetVisible.restype = c_char_p
        vh = False
        if len(very_hidden) > 0:
            vh = very_hidden[0]
        err = lib.SetSheetVisible(
            self.file_index, sheet.encode(ENCODE), visible, vh
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def set_workbook_props(self, opts: WorkbookPropsOptions) -> Optional[Exception]:
        """
        Sets workbook properties.

        Args:
            opts (WorkbookPropsOptions): TThe workbook property options

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.SetWorkbookProps.restype = c_char_p
        options = py_value_to_c(opts, types_go._WorkbookPropsOptions())
        err = lib.SetWorkbookProps(self.file_index, byref(options)).decode(ENCODE)
        return None if err == "" else Exception(err)

    def ungroup_sheets(self) -> Optional[Exception]:
        """
        Ungroup worksheets.

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.UngroupSheets.restype = c_char_p
        err = lib.UngroupSheets(self.file_index).decode(ENCODE)
        return None if err == "" else Exception(err)

    def unmerge_cell(
        self, sheet: str, top_left_cell: str, bottom_right_cell: str
    ) -> Optional[Exception]:
        """
        Unmerge a given range reference.

        Args:
            sheet (str): The worksheet name
            top_left_cell (str): The top-left cell reference
            bottom_right_cell (str): The right-bottom cell reference

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.

        Example:
            Unmerge range reference D3:E9 on Sheet1:

            .. code-block:: python

            err = f.unmerge_cell("Sheet1", "D3", "E9")
        """
        lib.UnmergeCell.restype = c_char_p
        err = lib.UnmergeCell(
            self.file_index,
            sheet.encode(ENCODE),
            top_left_cell.encode(ENCODE),
            bottom_right_cell.encode(ENCODE),
        ).decode(ENCODE)
        return None if err == "" else Exception(err)

    def update_linked_value(self) -> Optional[Exception]:
        """
        Fix linked values within a spreadsheet are not updating in Office Excel
        application. This function will be remove value tag when met a cell have
        a linked value.

        Notice:
            After opening generated workbook, Excel will update the linked value
            and generate a new value and will prompt to save the file or not.

        Returns:
            Optional[Exception]: Returns None if no error occurred,
            otherwise returns an Exception with the message.
        """
        lib.UpdateLinkedValue.restype = c_char_p
        err = lib.UpdateLinkedValue(self.file_index).decode(ENCODE)
        return None if err == "" else Exception(err)


def cell_name_to_coordinates(cell: str) -> Tuple[int, int, Optional[Exception]]:
    """
    Converts alphanumeric cell name to [X, Y] coordinates or returns an error.

    Args:
        cell (str): The cell reference

    Returns:
        Tuple[int, int, Optional[Exception]]: A tuple containing the column
        number, row number, and an Exception if an error occurred, otherwise None.
    """
    lib.CellNameToCoordinates.restype = types_go._CellNameToCoordinatesResult
    res = lib.CellNameToCoordinates(cell.encode(ENCODE))
    err = res.err.decode(ENCODE)
    return res.col, res.row, None if err == "" else Exception(err)


def column_name_to_number(name: str) -> Tuple[int, Optional[Exception]]:
    """
    Convert Excel sheet column name (case-insensitive) to int. The function
    returns an error if column name incorrect.

    Args:
        name (str): The column name

    Returns:
        Tuple[int, Optional[Exception]]: A tuple containing the column number
        and an Exception if an error occurred, otherwise None.
    """
    lib.ColumnNameToNumber.restype = types_go._IntErrorResult
    res = lib.ColumnNameToNumber(name.encode(ENCODE))
    err = res.err.decode(ENCODE)
    return res.val, None if err == "" else Exception(err)


def column_number_to_name(num: int) -> Tuple[str, Optional[Exception]]:
    """
    Convert the integer to Excel sheet column title.

    Args:
        num (int): The column number

    Returns:
        Tuple[str, Optional[Exception]]: A tuple containing the column name and
        an Exception if an error occurred, otherwise None.
    """
    lib.ColumnNumberToName.restype = types_go._StringErrorResult
    res = lib.ColumnNumberToName(c_int(num))
    err = res.err.decode(ENCODE)
    return res.val.decode(ENCODE), None if err == "" else Exception(err)


def coordinates_to_cell_name(
    col: int, row: int, *abs: bool
) -> Tuple[str, Optional[Exception]]:
    """
    Converts [X, Y] coordinates to alpha-numeric cell name or returns an error.

    Args:
        col (int): The column number.
        row (int): The row number.
        *abs (bool): Optional boolean indicating whether to use absolute
        references. If provided and True, the cell name will use absolute
        references (e.g., $A$1).

    Returns:
        Tuple[str, Optional[Exception]]: A tuple containing the cell name as a
        string and an Exception if an error occurred, otherwise None.
    """
    lib.CoordinatesToCellName.restype = types_go._StringErrorResult
    options = False
    if len(abs) > 0:
        options = abs[0]
    res = lib.CoordinatesToCellName(col, row, options)
    err = res.err.decode(ENCODE)
    return res.val.decode(ENCODE), None if err == "" else Exception(err)


def new_file() -> File:
    """
    Create new file by default template.

    Returns:
        File: A populated spreadsheet file struct.
    """
    return File(lib.NewFile())


def open_file(
    filename: str, *opts: Options
) -> Tuple[Optional[File], Optional[Exception]]:
    """
    OpenFile take the name of a spreadsheet file and returns a populated
    spreadsheet file struct for it.

    Args:
        filename (str): The path to the Excel file to open.
        *opts (Options): Optional parameters for opening the file.

    Returns:
        Tuple[Optional[File], Optional[Exception]]: A tuple containing a File
        object if successful, or None and an Exception if an error occurred.
    """
    lib.OpenFile.restype, options = types_go._IntErrorResult, None
    if len(opts) > 0:
        options = byref(py_value_to_c(opts[0], types_go._Options()))
    res = lib.OpenFile(filename.encode(ENCODE), options)
    err = res.err.decode(ENCODE)
    if err == "":
        return File(res.val), None
    return None, Exception(err)


def open_reader(
    buffer: bytes, *opts: Options
) -> Tuple[Optional[File], Optional[Exception]]:
    """
    Read data stream from bytes and return a populated spreadsheet file.

    Args:
        buffer (bytes): The contents buffer of the file
        *opts (Options): Optional parameters for opening the file.

    Returns:
        Tuple[Optional[File], Optional[Exception]]: A tuple containing a File
        object if successful, or None and an Exception if an error occurred.
    """
    lib.OpenReader.restype, options = types_go._IntErrorResult, None
    if len(opts) > 0:
        options = byref(py_value_to_c(opts[0], types_go._Options()))
    res = lib.OpenReader(cast(buffer, POINTER(c_ubyte)), len(buffer), options)
    err = res.err.decode(ENCODE)
    if err == "":
        return File(res.val), None
    return None, Exception(err)