Add 2 new functions: get_cell_rich_text and set_doc_props (#9)

- Simplify code for the c_value_to_py function
- Set zero value for C NULL pointer to void garbage memory address value
- Update unit tests
- Update example in README
- Upgrade the dependencies package version

Author: Arpelicy

README.md

@@ -129,7 +129,9 @@ chart = excelize.Chart(
     ],
     title=[excelize.RichTextRun(text="Fruit 3D Clustered Column Chart")],
 )
-f.add_chart("Sheet1", "E1", chart)
+err = f.add_chart("Sheet1", "E1", chart)
+if err:
+    print(err)
 # Save spreadsheet by the given path.
 err = f.save_as("Book1.xlsx")
 if err:

README_zh.md

@@ -129,7 +129,9 @@ chart = excelize.Chart(
     ],
     title=[excelize.RichTextRun(text="Fruit 3D Clustered Column Chart")],
 )
-f.add_chart("Sheet1", "E1", chart)
+err = f.add_chart("Sheet1", "E1", chart)
+if err:
+    print(err)
 # 根据指定路径保存文件
 err = f.save_as("Book1.xlsx")
 if err:

excelize.py

@@ -179,7 +179,6 @@ def c_value_to_py(ctypes_instance, py_instance):
                 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,
@@ -1482,6 +1481,29 @@ def get_cell_style(self, sheet: str, cell: str) -> Tuple[int, Optional[Exception
         err = res.err.decode(ENCODE)
         return res.val, None if err == "" else Exception(err)
 
+    def get_cell_rich_text(
+        self, sheet: str, cell: str
+    ) -> Tuple[List[RichTextRun], Optional[Exception]]:
+        """
+        Get rich text of cell by given worksheet and cell reference.
+
+        Args:
+            sheet (str): The worksheet name
+            cell (str): The cell reference
+
+        Returns:
+            Tuple[List[RichTextRun], Optional[Exception]]: A tuple containing
+            the rich text runs and an exception if an error occurred, otherwise
+            None.
+        """
+        lib.GetCellRichText.restype = types_go._GetCellRichTextResult
+        res = lib.GetCellRichText(
+            self.file_index, sheet.encode(ENCODE), cell.encode(ENCODE)
+        )
+        runs = c_value_to_py(res, GetCellRichTextResult()).runs
+        err = res.Err.decode(ENCODE)
+        return runs if runs else [], None if err == "" else Exception(err)
+
     def get_cell_value(
         self, sheet: str, cell: str, *opts: Options
     ) -> Tuple[str, Optional[Exception]]:
@@ -1703,7 +1725,7 @@ def get_tables(self, sheet: str) -> Tuple[List[Table], Optional[Exception]]:
         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)
+        return tables if tables else [], None if err == "" else Exception(err)
 
     def insert_cols(self, sheet: str, col: str, n: int) -> Optional[Exception]:
         """
@@ -2119,8 +2141,8 @@ def set_active_sheet(self, index: int) -> Optional[Exception]:
 
     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.
+        Set bool type value of a cell by given worksheet name, cell reference
+        and cell value.
 
         Args:
             sheet (str): The worksheet name
@@ -2717,6 +2739,46 @@ def set_defined_name(self, defined_name: DefinedName) -> Optional[Exception]:
         err = lib.SetDefinedName(self.file_index, byref(options)).decode(ENCODE)
         return None if err == "" else Exception(err)
 
+    def set_doc_props(self, doc_properties: DocProperties) -> Optional[Exception]:
+        """
+        Set document core properties.
+
+        Args:
+            doc_properties (DocProperties): The doc properties
+
+        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_doc_props(
+                excelize.DocProperties(
+                    category="category",
+                    content_status="Draft",
+                    created="2019-06-04T22:00:10Z",
+                    creator="Go Excelize",
+                    description="This file created by Go Excelize",
+                    identifier="xlsx",
+                    keywords="Spreadsheet",
+                    last_modified_by="Go Author",
+                    modified="2019-06-04T22:00:10Z",
+                    revision="0",
+                    subject="Test Subject",
+                    title="Test Title",
+                    language="en-US",
+                    version="1.0.0",
+                )
+            )
+        """
+        lib.SetDocProps.restype = c_char_p
+        options = py_value_to_c(doc_properties, types_go._DocProperties())
+        err = lib.SetDocProps(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]:

go.mod

@@ -3,17 +3,17 @@ module github.com/xuri/excelize-py
 go 1.20
 
 require (
-	github.com/xuri/excelize/v2 v2.9.1-0.20250105013731-af422e17009b
+	github.com/xuri/excelize/v2 v2.9.1-0.20250207010127-05ed940040c1
 	golang.org/x/image v0.23.0
 )
 
 require (
 	github.com/richardlehane/mscfb v1.0.4 // indirect
 	github.com/richardlehane/msoleps v1.0.4 // indirect
-	github.com/tiendc/go-deepcopy v1.2.0 // indirect
+	github.com/tiendc/go-deepcopy v1.2.2 // indirect
 	github.com/xuri/efp v0.0.0-20241211021726-c4e992084aa6 // indirect
-	github.com/xuri/nfp v0.0.0-20240318013403-ab9948c2c4a7 // indirect
-	golang.org/x/crypto v0.31.0 // indirect
-	golang.org/x/net v0.33.0 // indirect
-	golang.org/x/text v0.21.0 // indirect
+	github.com/xuri/nfp v0.0.0-20250111060730-82a408b9aa71 // indirect
+	golang.org/x/crypto v0.32.0 // indirect
+	golang.org/x/net v0.34.0 // indirect
+	golang.org/x/text v0.22.0 // indirect
 )

go.sum

@@ -8,18 +8,24 @@ github.com/richardlehane/msoleps v1.0.4/go.mod h1:BWev5JBpU9Ko2WAgmZEuiz4/u3ZYTK
 github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
 github.com/tiendc/go-deepcopy v1.2.0 h1:6vCCs+qdLQHzFqY1fcPirsAWOmrLbuccilfp8UzD1Qo=
 github.com/tiendc/go-deepcopy v1.2.0/go.mod h1:toXoeQoUqXOOS/X4sKuiAoSk6elIdqc0pN7MTgOOo2I=
+github.com/tiendc/go-deepcopy v1.2.2 h1:UxMUNHTh2lWbnfic8asYI3YtE5e85XGZYUgl2pZKsVY=
+github.com/tiendc/go-deepcopy v1.2.2/go.mod h1:toXoeQoUqXOOS/X4sKuiAoSk6elIdqc0pN7MTgOOo2I=
 github.com/xuri/efp v0.0.0-20241211021726-c4e992084aa6 h1:8m6DWBG+dlFNbx5ynvrE7NgI+Y7OlZVMVTpayoW+rCc=
 github.com/xuri/efp v0.0.0-20241211021726-c4e992084aa6/go.mod h1:ybY/Jr0T0GTCnYjKqmdwxyxn2BQf2RcQIIvex5QldPI=
-github.com/xuri/excelize/v2 v2.9.1-0.20250105013731-af422e17009b h1:IgzLFLfCA10Lu5Ac9XgC8wBvPAVqHe2ilgIA8nouiPc=
-github.com/xuri/excelize/v2 v2.9.1-0.20250105013731-af422e17009b/go.mod h1:NBRx6e5FHFx4mHLiYG1QBONNvNNSs/wrtzS+h56/A6k=
-github.com/xuri/nfp v0.0.0-20240318013403-ab9948c2c4a7 h1:hPVCafDV85blFTabnqKgNhDCkJX25eik94Si9cTER4A=
-github.com/xuri/nfp v0.0.0-20240318013403-ab9948c2c4a7/go.mod h1:WwHg+CVyzlv/TX9xqBFXEZAuxOPxn2k1GNHwG41IIUQ=
-golang.org/x/crypto v0.31.0 h1:ihbySMvVjLAeSH1IbfcRTkD/iNscyz8rGzjF/E5hV6U=
-golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
+github.com/xuri/excelize/v2 v2.9.1-0.20250125020127-b19e5940b84e h1:5V9lcKkqTSO66lJhwYeANB9GJkSEGosawlR5cMpvmQY=
+github.com/xuri/excelize/v2 v2.9.1-0.20250125020127-b19e5940b84e/go.mod h1:QPDLfWgowGnzIqBhd8g4iNoymgms2UL7Ok/Qm/NSPsg=
+github.com/xuri/excelize/v2 v2.9.1-0.20250207010127-05ed940040c1 h1:K+zyRkNaXhO7LeXDSG/v1QtKZvc/wa+Q944zjSDFfRs=
+github.com/xuri/excelize/v2 v2.9.1-0.20250207010127-05ed940040c1/go.mod h1:QPDLfWgowGnzIqBhd8g4iNoymgms2UL7Ok/Qm/NSPsg=
+github.com/xuri/nfp v0.0.0-20250111060730-82a408b9aa71 h1:hOh7aVDrvGJRxzXrQbDY8E+02oaI//5cHL+97oYpEPw=
+github.com/xuri/nfp v0.0.0-20250111060730-82a408b9aa71/go.mod h1:WwHg+CVyzlv/TX9xqBFXEZAuxOPxn2k1GNHwG41IIUQ=
+golang.org/x/crypto v0.32.0 h1:euUpcYgM8WcP71gNpTqQCn6rC2t6ULUPiOzfWaXVVfc=
+golang.org/x/crypto v0.32.0/go.mod h1:ZnnJkOaASj8g0AjIduWNlq2NRxL0PlBrbKVyZ6V/Ugc=
 golang.org/x/image v0.23.0 h1:HseQ7c2OpPKTPVzNjG5fwJsOTCiiwS4QdsYi5XU6H68=
 golang.org/x/image v0.23.0/go.mod h1:wJJBTdLfCCf3tiHa1fNxpZmUI4mmoZvwMCPP0ddoNKY=
-golang.org/x/net v0.33.0 h1:74SYHlV8BIgHIFC/LrYkOGIwL19eTYXQ5wc6TBuO36I=
-golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4=
+golang.org/x/net v0.34.0 h1:Mb7Mrk043xzHgnRM88suvJFwzVrRfHEHJEl5/71CKw0=
+golang.org/x/net v0.34.0/go.mod h1:di0qlW3YNM5oh6GqDGQr92MyTozJPmybPK4Ev/Gm31k=
 golang.org/x/text v0.21.0 h1:zyQAAkrwaneQ066sspRyJaG9VNi/YJ1NfzcGB3hZ/qo=
 golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
+golang.org/x/text v0.22.0 h1:bofq7m3/HAFvbF51jz3Q9wLg3jkvSPuiZu/pD1XwgtM=
+golang.org/x/text v0.22.0/go.mod h1:YRoo4H8PVmsu+E3Ou7cqLVH8oXWIHVoX0jqUWALQhfY=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

main.go

@@ -368,6 +368,8 @@ func goValueToC(goVal, cVal reflect.Value) (reflect.Value, error) {
 					ptrVal := reflect.NewAt(v.Type(), cValPtr).Elem()
 					ptrVal.Set(v)
 					c.FieldByName(field.Name).Set(ptrVal.Addr())
+				} else {
+					c.FieldByName(field.Name).Set(reflect.Zero(cField.Type))
 				}
 			}
 		case reflect.Struct:
@@ -1055,6 +1057,31 @@ func GetCellHyperLink(idx int, sheet, cell *C.char) C.struct_GetCellHyperLinkRes
 	return C.struct_GetCellHyperLinkResult{link: C._Bool(link), target: C.CString(target), err: C.CString(emptyString)}
 }
 
+// GetCellRichText provides a function to get rich text of cell by given
+// worksheet and cell reference.
+//
+//export GetCellRichText
+func GetCellRichText(idx int, sheet, cell *C.char) C.struct_GetCellRichTextResult {
+	f, ok := files.Load(idx)
+	if !ok {
+		return C.struct_GetCellRichTextResult{Err: C.CString(errFilePtr)}
+	}
+	runs, err := f.(*excelize.File).GetCellRichText(C.GoString(sheet), C.GoString(cell))
+	if err != nil {
+		return C.struct_GetCellRichTextResult{Err: C.CString(err.Error())}
+	}
+	cArray := C.malloc(C.size_t(len(runs)) * C.size_t(unsafe.Sizeof(C.struct_RichTextRun{})))
+	cStructArray := (*[1 << 30]C.struct_RichTextRun)(cArray)[:len(runs):len(runs)]
+	for i, r := range runs {
+		cVal, err := goValueToC(reflect.ValueOf(r), reflect.ValueOf(&C.struct_RichTextRun{}))
+		if err != nil {
+			return C.struct_GetCellRichTextResult{Err: C.CString(err.Error())}
+		}
+		cStructArray[i] = cVal.Elem().Interface().(C.struct_RichTextRun)
+	}
+	return C.struct_GetCellRichTextResult{RunsLen: C.int(len(runs)), Runs: (*C.struct_RichTextRun)(cArray), Err: C.CString(emptyString)}
+}
+
 // GetCellStyle provides a function to get cell style index by given worksheet
 // name and cell reference. This function is concurrency safe.
 //
@@ -1897,7 +1924,7 @@ func SetCellHyperLink(idx int, sheet, cell, link, linkType *C.char, opts *C.stru
 // worksheet name, cell reference and cell value.
 //
 //export SetCellInt
-func SetCellInt(idx int, sheet, cell *C.char, value int) *C.char {
+func SetCellInt(idx int, sheet, cell *C.char, value int64) *C.char {
 	f, ok := files.Load(idx)
 	if !ok {
 		return C.CString(errFilePtr)
@@ -2109,6 +2136,26 @@ func SetDefinedName(idx int, definedName *C.struct_DefinedName) *C.char {
 	return C.CString(emptyString)
 }
 
+// SetDocProps provides a function to set document core properties.
+//
+//export SetDocProps
+func SetDocProps(idx int, docProperties *C.struct_DocProperties) *C.char {
+	var options excelize.DocProperties
+	goVal, err := cValueToGo(reflect.ValueOf(*docProperties), reflect.TypeOf(excelize.DocProperties{}))
+	if err != nil {
+		return C.CString(err.Error())
+	}
+	options = goVal.Elem().Interface().(excelize.DocProperties)
+	f, ok := files.Load(idx)
+	if !ok {
+		return C.CString(errFilePtr)
+	}
+	if err := f.(*excelize.File).SetDocProps(&options); err != nil {
+		return C.CString(err.Error())
+	}
+	return C.CString(emptyString)
+}
+
 // SetHeaderFooter provides a function to set headers and footers by given
 // worksheet name and the control characters.
 //