[enc] Expose the categories container to C.

include/xgboost/c_api.h

@@ -45,10 +45,16 @@ typedef uint64_t bst_ulong;  // NOLINT(*)
  * @{
  */
 
-/** @brief handle to DMatrix */
+/** @brief Handle to the DMatrix */
 typedef void *DMatrixHandle;  // NOLINT(*)
-/** @brief handle to Booster */
+/** @brief Handle to the Booster */
 typedef void *BoosterHandle;  // NOLINT(*)
+/**
+ * @brief Handle to the categories container.
+ *
+ * @since 3.2.0
+ */
+typedef void *CategoriesHandle;  // NOLINT(*)
 
 /**
  * @brief Return the version of the XGBoost library.
@@ -801,6 +807,70 @@ XGB_DLL int XGDMatrixGetStrFeatureInfo(DMatrixHandle handle, const char *field,
                                        bst_ulong *size,
                                        const char ***out_features);
 
+/**
+ * @brief Create an opaque handle to the internal category container.
+ *
+ * @since 3.2.0
+ *
+ * @note Experimental API, subject to change in the future.
+ *
+ * The container should be freed by @ref XGBCategoriesFree
+ *
+ * @param handle An instance of the data matrix.
+ * @param config Unused, reserved for the future.
+ * @param out    Created handle to the category container. Set to NULL if there's no category.
+ *
+ * @return 0 when success, -1 when failure happens.
+ *
+ * @code{c}
+ *    DMatrixHandle fmat;
+ *    // Create a DMatrix from categorical data
+ *    // ...
+ *    CategoriesHandle cats;
+ *    int err = XGBoosterGetCategories(fmat, NULL, &cats)
+ *    if (err != 0) {
+ *        exit(-1);
+ *    }
+ *    err = XGBCategoriesFree(cats);
+ *    if (err != 0) {
+ *        exit(-1);
+ *    }
+ * @endcode
+ */
+XGB_DLL int XGDMatrixGetCategories(DMatrixHandle handle, char const *config, CategoriesHandle *out);
+
+/**
+ * @brief Create an opaque handle to the internal container and export it to arrow.
+ *
+ * @since 3.2.0
+ *
+ * @note Experimental API, subject to change in the future.
+ *
+ * The container should be freed by @ref XGBCategoriesFree
+ *
+ * @param handle     An instance of the data matrix.
+ * @param config     Unused, reserved for the future.
+ * @param out        Created handle to the category container
+ * @param export_out JSON encoded array of categories, with length equal to the number of features.
+ *
+ * @return 0 when success, -1 when failure happens.
+ */
+XGB_DLL int XGDMatrixGetCategoriesExportToArrow(DMatrixHandle handle, char const *config,
+                                                CategoriesHandle *out, char const **export_out);
+
+/**
+ * @brief Free the opaque handle.
+ *
+ * @since 3.2.0
+ *
+ * @note Experimental API, subject to change in the future.
+ *
+ * @param handle An instance of the category container.
+ *
+ * @return 0 when success, -1 when failure happens.
+ */
+XGB_DLL int XGBCategoriesFree(CategoriesHandle handle);
+
 /**
  * @deprecated since 2.1.0
  *
@@ -1503,6 +1573,25 @@ XGB_DLL int XGBoosterDumpModelExWithFeatures(BoosterHandle handle,
                                              bst_ulong *out_len,
                                              const char ***out_models);
 
+/**
+ * See @ref XGDMatrixGetCategories
+ *
+ * @since 3.2.0
+ *
+ * @note Experimental API, subject to change in the future.
+ */
+XGB_DLL int XGBoosterGetCategories(BoosterHandle handle, char const *config, CategoriesHandle *out);
+
+/**
+ * See @ref XGDMatrixGetCategoriesExportToArrow
+ *
+ * @since 3.2.0
+ *
+ * @note Experimental API, subject to change in the future.
+ */
+XGB_DLL int XGBoosterGetCategoriesExportToArrow(BoosterHandle handle, char const *config,
+                                                CategoriesHandle *out, char const **export_out);
+
 /**
  * @brief Get string attribute from Booster.
  * @param handle handle

python-package/xgboost/_data_utils.py

@@ -643,10 +643,10 @@ def __init__(
         arrow_arrays: Optional[ArrowCatList],
     ) -> None:
         # The handle type is a bundle of the handle and the free call. Otherwise, we
-        # will have to import the lib and checkcall inside the __del__ method from the
-        # core module to avoid cyclic model dependency. Importing modules in __del__ can
-        # result in Python abort if __del__ is called during exception handling
-        # (interpreter is shutting down).
+        # will have to import the `_lib` and the `_check_call` from the core module
+        # inside the __del__ method to avoid cyclic model dependency.
+        # Importing modules in __del__ can result in Python abort if __del__ is called
+        # during exception handling (interpreter is shutting down).
         self._handle, self._free = handle
         self._arrow_arrays = arrow_arrays
 

src/c_api/c_api.cc

@@ -752,23 +752,11 @@ CatContainer *CopyCatContainer(Context const *ctx, CatContainer const *cats,
 }
 }  // anonymous namespace
 
-typedef  void * CategoriesHandle;  // NOLINT
-
 /**
- * Fetching categories is experimental (3.1), C functions are hidden at the moment.
- *
  * No actual container method is exposed through the C API. It's just an opaque handle at
  * the moment. This way we get to reuse the methods and the context from the DMatrix and
  * Booster.
  */
-/**
- * @brief Create an opaque handle to the internal container.
- *
- * @param handle An instance of the data matrix.
- * @param out    Created handle to the category container. Set to NULL if there's no category.
- *
- * @return 0 when success, -1 when failure happens.
- */
 XGB_DLL int XGDMatrixGetCategories(DMatrixHandle handle, char const * /*config*/,
                                    CategoriesHandle *out) {
   API_BEGIN()
@@ -786,15 +774,7 @@ XGB_DLL int XGDMatrixGetCategories(DMatrixHandle handle, char const * /*config*/
 
   API_END()
 }
-/**
- * @brief Create an opaque handle to the internal container and export it to arrow.
- *
- * @param handle     An instance of the data matrix.
- * @param out        Created handle to the category container
- * @param export_out JSON encoded array of categories, with length equal to the number of features.
- *
- * @return 0 when success, -1 when failure happens.
- */
+
 XGB_DLL int XGDMatrixGetCategoriesExportToArrow(DMatrixHandle handle, char const * /*config*/,
                                                 CategoriesHandle *out, char const **export_out) {
   API_BEGIN();
@@ -821,13 +801,7 @@ XGB_DLL int XGDMatrixGetCategoriesExportToArrow(DMatrixHandle handle, char const
 
   API_END();
 }
-/**
- * @brief Free the opaque handle.
- *
- * @param handle An instance of the category container.
- *
- * @return 0 when success, -1 when failure happens.
- */
+
 XGB_DLL int XGBCategoriesFree(CategoriesHandle handle) {
   API_BEGIN();
   xgboost_CHECK_C_ARG_PTR(handle);
@@ -1763,13 +1737,7 @@ XGB_DLL int XGBoosterDumpModelExWithFeatures(BoosterHandle handle,
   API_END();
 }
 
-/**
- * Experimental (3.1), hidden.
- */
-/**
- * See @ref XGDMatrixGetCategories
- */
-XGB_DLL int XGBoosterGetCategories(DMatrixHandle handle, char const * /*config*/,
+XGB_DLL int XGBoosterGetCategories(BoosterHandle handle, char const * /*config*/,
                                    CategoriesHandle *out) {
   API_BEGIN()
   CHECK_HANDLE()
@@ -1786,9 +1754,7 @@ XGB_DLL int XGBoosterGetCategories(DMatrixHandle handle, char const * /*config*/
 
   API_END()
 }
-/**
- * See @ref XGDMatrixGetCategoriesExportToArrow
- */
+
 XGB_DLL int XGBoosterGetCategoriesExportToArrow(BoosterHandle handle, char const * /*config*/,
                                                 CategoriesHandle *out, char const **export_out) {
   API_BEGIN()