add Path overloads for io methods

AndreiKingsley · AndreiKingsley · commit 886af8b3be25 · 2025-11-12T00:00:08.000+04:00
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/guess.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/guess.kt
@@ -16,6 +16,7 @@ import java.io.File
 import java.io.FileNotFoundException
 import java.io.InputStream
 import java.net.URL
+import java.nio.file.Path
 import java.util.ServiceLoader
 import kotlin.reflect.KType
 
@@ -57,6 +58,13 @@ public interface SupportedDataFrameFormat : SupportedFormat {
     public fun readDataFrame(stream: InputStream, header: List<String> = emptyList()): DataFrame<*>
 
     public fun readDataFrame(file: File, header: List<String> = emptyList()): DataFrame<*>
+
+    /**
+     * Path overload for reading a DataFrame. Default implementation delegates to the [File] overload.
+     * Implementors are not required to override this method.
+     */
+    public fun readDataFrame(path: Path, header: List<String> = emptyList()): DataFrame<*> =
+        readDataFrame(path.toFile(), header)
 }
 
 /**
@@ -293,3 +301,16 @@ public fun URL.readDataRow(header: List<String> = emptyList()): AnyRow = DataRow
 public fun File.readDataFrame(header: List<String> = emptyList()): AnyFrame = DataFrame.read(this, header)
 
 public fun File.readDataRow(header: List<String> = emptyList()): AnyRow = DataRow.read(this, header)
+
+// Path-based overloads and extensions
+public fun DataFrame.Companion.read(path: Path, header: List<String> = emptyList()): AnyFrame =
+    read(path.toFile(), header)
+
+public fun DataRow.Companion.read(path: Path, header: List<String> = emptyList()): AnyRow =
+    DataFrame.read(path, header).single()
+
+public fun Path.readDataFrame(header: List<String> = emptyList()): AnyFrame =
+    DataFrame.read(this, header)
+
+public fun Path.readDataRow(header: List<String> = emptyList()): AnyRow =
+    DataRow.read(this, header)
diff --git a/dataframe-arrow/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/ArrowWriter.kt b/dataframe-arrow/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/ArrowWriter.kt
@@ -13,6 +13,8 @@ import java.io.FileOutputStream
 import java.io.OutputStream
 import java.nio.channels.Channels
 import java.nio.channels.WritableByteChannel
+import java.nio.file.Files
+import java.nio.file.Path
 
 public val ignoreMismatchMessage: (ConvertingMismatch) -> Unit = { message: ConvertingMismatch -> }
 public val writeMismatchMessage: (ConvertingMismatch) -> Unit = { message: ConvertingMismatch ->
@@ -96,6 +98,16 @@ public interface ArrowWriter : AutoCloseable {
         writeArrowIPC(FileOutputStream(file, append))
     }
 
+    /** Path overload for Arrow IPC writing. */
+    public fun writeArrowIPC(path: Path, append: Boolean = true) {
+        // For append=true use FileOutputStream on File to preserve semantics; otherwise use Files.newOutputStream
+        if (append) {
+            writeArrowIPC(FileOutputStream(path.toFile(), /* append = */ true))
+        } else {
+            Files.newOutputStream(path).use { os -> writeArrowIPC(os) }
+        }
+    }
+
     /**
      * Save data to [Arrow interprocess streaming format](https://arrow.apache.org/docs/java/ipc.html#writing-and-reading-streaming-format), write to new [ByteArray]
      */
@@ -133,6 +145,11 @@ public interface ArrowWriter : AutoCloseable {
         writeArrowFeather(FileOutputStream(file))
     }
 
+    /** Path overload for Arrow Feather writing. */
+    public fun writeArrowFeather(path: Path) {
+        Files.newOutputStream(path).use { os -> writeArrowFeather(os) }
+    }
+
     /**
      * Save data to [Arrow random access format](https://arrow.apache.org/docs/java/ipc.html#writing-and-reading-random-access-files), write to new [ByteArray]
      */
diff --git a/dataframe-arrow/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/arrowReading.kt b/dataframe-arrow/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/arrowReading.kt
@@ -77,6 +77,12 @@ public fun DataFrame.Companion.readArrowIPC(
     nullability: NullabilityOptions = NullabilityOptions.Infer,
 ): AnyFrame = Files.newByteChannel(file.toPath()).use { readArrowIPC(it, nullability = nullability) }
 
+/** Path overload for reading Arrow IPC from file path. */
+public fun DataFrame.Companion.readArrowIPC(
+    path: Path,
+    nullability: NullabilityOptions = NullabilityOptions.Infer,
+): AnyFrame = Files.newByteChannel(path).use { readArrowIPC(it, nullability = nullability) }
+
 /**
  * Read [Arrow interprocess streaming format](https://arrow.apache.org/docs/java/ipc.html#writing-and-reading-streaming-format) data from existing [byteArray]
  */
@@ -130,6 +136,12 @@ public fun DataFrame.Companion.readArrowFeather(
     nullability: NullabilityOptions = NullabilityOptions.Infer,
 ): AnyFrame = Files.newByteChannel(file.toPath()).use { readArrowFeather(it, nullability = nullability) }
 
+/** Path overload for reading Arrow Feather from file path. */
+public fun DataFrame.Companion.readArrowFeather(
+    path: Path,
+    nullability: NullabilityOptions = NullabilityOptions.Infer,
+): AnyFrame = Files.newByteChannel(path).use { readArrowFeather(it, nullability = nullability) }
+
 /**
  * Read [Arrow random access format](https://arrow.apache.org/docs/java/ipc.html#writing-and-reading-random-access-files) data from existing [byteArray]
  */
diff --git a/dataframe-arrow/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/arrowWriting.kt b/dataframe-arrow/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/arrowWriting.kt
@@ -5,6 +5,7 @@ import org.jetbrains.kotlinx.dataframe.AnyFrame
 import java.io.File
 import java.io.OutputStream
 import java.nio.channels.WritableByteChannel
+import java.nio.file.Path
 
 /**
  * Create [ArrowWriter] for [this] DataFrame with target schema matching actual data
@@ -51,6 +52,13 @@ public fun AnyFrame.writeArrowIPC(file: File, append: Boolean = true) {
     }
 }
 
+/** Path overload for IPC writing. */
+public fun AnyFrame.writeArrowIPC(path: Path, append: Boolean = true) {
+    this.arrowWriter().use { writer ->
+        writer.writeArrowIPC(path, append)
+    }
+}
+
 /**
  * Save data to [Arrow interprocess streaming format](https://arrow.apache.org/docs/java/ipc.html#writing-and-reading-streaming-format), write to new [ByteArray]
  */
@@ -89,6 +97,13 @@ public fun AnyFrame.writeArrowFeather(file: File) {
     }
 }
 
+/** Path overload for Feather writing. */
+public fun AnyFrame.writeArrowFeather(path: Path) {
+    this.arrowWriter().use { writer ->
+        writer.writeArrowFeather(path)
+    }
+}
+
 /**
  * Save data to [Arrow random access format](https://arrow.apache.org/docs/java/ipc.html#writing-and-reading-random-access-files), write to new [ByteArray]
  */
diff --git a/dataframe-excel/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/xlsx.kt b/dataframe-excel/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/xlsx.kt
@@ -39,6 +39,9 @@ import java.io.InputStream
 import java.io.OutputStream
 import java.net.URL
 import java.nio.file.Files
+import java.nio.file.Path
+import kotlin.io.path.outputStream
+import kotlin.io.path.inputStream
 import java.util.Calendar
 import java.time.LocalDate as JavaLocalDate
 import java.time.LocalDateTime as JavaLocalDateTime
@@ -627,24 +630,38 @@ public fun <T> DataFrame<T>.writeExcel(
     writeHeader: Boolean = true,
     workBookType: WorkBookType = WorkBookType.XLSX,
     keepFile: Boolean = false,
+): Unit = writeExcel(
+    path = file.toPath(),
+    columnsSelector = columnsSelector,
+    sheetName = sheetName,
+    writeHeader = writeHeader,
+    workBookType = workBookType,
+    keepFile = keepFile,
+)
+
+/** Path overload for writing this DataFrame to an Excel file. */
+public fun <T> DataFrame<T>.writeExcel(
+    path: Path,
+    columnsSelector: ColumnsSelector<T, *> = { all() },
+    sheetName: String? = null,
+    writeHeader: Boolean = true,
+    workBookType: WorkBookType = WorkBookType.XLSX,
+    keepFile: Boolean = false,
 ) {
     val factory =
-        // Write to an existing file with `keepFile` flag
-        if (keepFile && file.exists() && file.length() > 0L) {
-            val fis = file.inputStream()
+        if (keepFile && Files.exists(path) && Files.size(path) > 0L) {
+            val fis = path.inputStream()
             when (workBookType) {
                 WorkBookType.XLS -> HSSFWorkbook(fis)
                 WorkBookType.XLSX -> XSSFWorkbook(fis)
             }
         } else {
             when (workBookType) {
                 WorkBookType.XLS -> HSSFWorkbook()
-
-                // Use streaming mode for a new XLSX file
                 WorkBookType.XLSX -> SXSSFWorkbook()
             }
         }
-    return file.outputStream().use {
+    return path.outputStream().use {
         writeExcel(it, columnsSelector, sheetName, writeHeader, factory)
     }
 }
diff --git a/dataframe-geo/src/main/kotlin/org/jetbrains/kotlinx/dataframe/geo/io/write.kt b/dataframe-geo/src/main/kotlin/org/jetbrains/kotlinx/dataframe/geo/io/write.kt
@@ -8,9 +8,19 @@ import org.geotools.geojson.feature.FeatureJSON
 import org.jetbrains.kotlinx.dataframe.geo.GeoDataFrame
 import org.jetbrains.kotlinx.dataframe.geo.geotools.toSimpleFeatureCollection
 import java.io.File
+import java.nio.file.Files
+import java.nio.file.Path
 
 fun GeoDataFrame<*>.writeGeoJson(path: String): Unit = writeGeoJson(File(path))
 
+/** Path overload for writing GeoJSON */
+fun GeoDataFrame<*>.writeGeoJson(path: Path) {
+    val featureJSON = FeatureJSON()
+    Files.newOutputStream(path).use { outputStream ->
+        featureJSON.writeFeatureCollection(toSimpleFeatureCollection(), outputStream)
+    }
+}
+
 fun GeoDataFrame<*>.writeGeoJson(file: File) {
     // TODO: adds ids that breaks order of reading
     val featureJSON = FeatureJSON()
@@ -21,6 +31,11 @@ fun GeoDataFrame<*>.writeGeoJson(file: File) {
 
 fun GeoDataFrame<*>.writeShapefile(directoryPath: String): Unit = writeShapefile(File(directoryPath))
 
+/** Path overload for writing Shapefile to a directory */
+fun GeoDataFrame<*>.writeShapefile(directory: Path) {
+    writeShapefile(directory.toFile())
+}
+
 fun GeoDataFrame<*>.writeShapefile(directory: File) {
     if (!directory.exists()) {
         directory.mkdirs()
diff --git a/dataframe-json/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/json.kt b/dataframe-json/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/json.kt
@@ -29,6 +29,8 @@ import org.jetbrains.kotlinx.dataframe.io.JSON.TypeClashTactic.ARRAY_AND_VALUE_C
 import java.io.File
 import java.io.InputStream
 import java.net.URL
+import java.nio.file.Path
+import kotlin.io.path.writeText
 import kotlin.reflect.typeOf
 
 public class JSON(
@@ -147,6 +149,15 @@ public fun DataFrame.Companion.readJson(
     unifyNumbers: Boolean = true,
 ): AnyFrame = DataFrame.readJson(file.toURI().toURL(), header, keyValuePaths, typeClashTactic, unifyNumbers)
 
+/** Path overload for reading JSON into DataFrame. */
+public fun DataFrame.Companion.readJson(
+    path: Path,
+    header: List<String> = emptyList(),
+    keyValuePaths: List<JsonPath> = emptyList(),
+    typeClashTactic: TypeClashTactic = ARRAY_AND_VALUE_COLUMNS,
+    unifyNumbers: Boolean = true,
+): AnyFrame = DataFrame.readJson(path.toUri().toURL(), header, keyValuePaths, typeClashTactic, unifyNumbers)
+
 /**
  * @param file Where to fetch the Json as [InputStream] to be converted to a [DataRow].
  * @param keyValuePaths List of [JsonPath]s where instead of a [ColumnGroup], a [FrameColumn]<[NameValueProperty]>
@@ -164,6 +175,15 @@ public fun DataRow.Companion.readJson(
     unifyNumbers: Boolean = true,
 ): AnyRow = DataFrame.readJson(file, header, keyValuePaths, typeClashTactic, unifyNumbers).single()
 
+/** Path overload for reading JSON into DataRow. */
+public fun DataRow.Companion.readJson(
+    path: Path,
+    header: List<String> = emptyList(),
+    keyValuePaths: List<JsonPath> = emptyList(),
+    typeClashTactic: TypeClashTactic = ARRAY_AND_VALUE_COLUMNS,
+    unifyNumbers: Boolean = true,
+): AnyRow = DataFrame.readJson(path, header, keyValuePaths, typeClashTactic, unifyNumbers).single()
+
 /**
  * @param path URL or file path from where to fetch the Json as [InputStream] to be converted to a [DataFrame].
  * @param keyValuePaths List of [JsonPath]s where instead of a [ColumnGroup], a [FrameColumn]<[NameValueProperty]>
@@ -412,6 +432,10 @@ public fun AnyFrame.writeJson(file: File, prettyPrint: Boolean = false) {
     file.writeText(toJson(prettyPrint))
 }
 
+public fun AnyFrame.writeJson(path: Path, prettyPrint: Boolean = false) {
+    path.writeText(toJson(prettyPrint))
+}
+
 public fun AnyFrame.writeJson(path: String, prettyPrint: Boolean = false): Unit = writeJson(File(path), prettyPrint)
 
 public fun AnyFrame.writeJson(writer: Appendable, prettyPrint: Boolean = false) {
@@ -422,6 +446,10 @@ public fun AnyRow.writeJson(file: File, prettyPrint: Boolean = false) {
     file.writeText(toJson(prettyPrint))
 }
 
+public fun AnyRow.writeJson(path: Path, prettyPrint: Boolean = false) {
+    path.writeText(toJson(prettyPrint))
+}
+
 public fun AnyRow.writeJson(path: String, prettyPrint: Boolean = false) {
     writeJson(File(path), prettyPrint)
 }
