Add safety checks for column accessors dataframe

altavir · altavir · commit a40a74ec4e0d · 2026-01-25T14:41:18.000+03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## Unreleased
 
 ### Added
+- Documentation and safety for Tables-kt-dataframe
 - Ability to unwrap NamedData
 
 ### Changed
diff --git a/README.md b/README.md
@@ -130,12 +130,23 @@ In this section, we will try to cover DataForge main ideas in the form of questi
 > **Maturity**: EXPERIMENTAL
 
 ### [tables-kt/tables-kt-dataframe](tables-kt/tables-kt-dataframe)
+> An integration to convert DataForg tables to DataFrame and back.
 >
-> **Maturity**: PROTOTYPE
+> **Maturity**: EXPERIMENTAL
+>
+> **Features:**
+> - [asDataFrame](tables-kt/tables-kt-dataframe/src/main/kotlin/space/kscience/dataforge/dataframe/TableAsDataFrame.kt) : Conversion from DataForge Table to DataFrame via `asDataFrame()` extension function.
+> - [asTable](tables-kt/tables-kt-dataframe/src/main/kotlin/space/kscience/dataforge/dataframe/DataFrameAsTable.kt) : Conversion from DataFrame to DataForge Table via `asTable()` extension function.
+
 
 ### [tables-kt/tables-kt-exposed](tables-kt/tables-kt-exposed)
+> An integration to represent SQL tables as DataForg table via Exposed-JDBC
 >
 > **Maturity**: EXPERIMENTAL
+>
+> **Features:**
+> - [ExposedTable](tables-kt/tables-kt-exposed/src/main/kotlin/space/kscience/dataforge/exposed/ExposedTable.kt) : Create a table from JDBC database with `ExposedTable`.
+
 
 ### [tables-kt/tables-kt-jupyter](tables-kt/tables-kt-jupyter)
 >
diff --git a/dataforge-context/README.md b/dataforge-context/README.md
@@ -6,7 +6,7 @@ Context and provider definitions
 
 ## Artifact:
 
-The Maven coordinates of this project are `space.kscience:dataforge-context:0.10.3`.
+The Maven coordinates of this project are `space.kscience:dataforge-context:0.11.0-dev-1`.
 
 **Gradle Kotlin DSL:**
 ```kotlin
@@ -16,6 +16,6 @@ repositories {
 }
 
 dependencies {
-    implementation("space.kscience:dataforge-context:0.10.3")
+    implementation("space.kscience:dataforge-context:0.11.0-dev-1")
 }
 ```
diff --git a/dataforge-data/README.md b/dataforge-data/README.md
@@ -6,7 +6,7 @@
 
 ## Artifact:
 
-The Maven coordinates of this project are `space.kscience:dataforge-data:0.10.3`.
+The Maven coordinates of this project are `space.kscience:dataforge-data:0.11.0-dev-1`.
 
 **Gradle Kotlin DSL:**
 ```kotlin
@@ -16,6 +16,6 @@ repositories {
 }
 
 dependencies {
-    implementation("space.kscience:dataforge-data:0.10.3")
+    implementation("space.kscience:dataforge-data:0.11.0-dev-1")
 }
 ```
diff --git a/dataforge-io/README.md b/dataforge-io/README.md
@@ -15,7 +15,7 @@ IO module
 
 ## Artifact:
 
-The Maven coordinates of this project are `space.kscience:dataforge-io:0.10.3`.
+The Maven coordinates of this project are `space.kscience:dataforge-io:0.11.0-dev-1`.
 
 **Gradle Kotlin DSL:**
 ```kotlin
@@ -25,6 +25,6 @@ repositories {
 }
 
 dependencies {
-    implementation("space.kscience:dataforge-io:0.10.3")
+    implementation("space.kscience:dataforge-io:0.11.0-dev-1")
 }
 ```
diff --git a/dataforge-io/dataforge-io-proto/README.md b/dataforge-io/dataforge-io-proto/README.md
@@ -6,7 +6,7 @@ ProtoBuf meta IO
 
 ## Artifact:
 
-The Maven coordinates of this project are `space.kscience:dataforge-io-proto:0.10.3`.
+The Maven coordinates of this project are `space.kscience:dataforge-io-proto:0.11.0-dev-1`.
 
 **Gradle Kotlin DSL:**
 ```kotlin
@@ -16,6 +16,6 @@ repositories {
 }
 
 dependencies {
-    implementation("space.kscience:dataforge-io-proto:0.10.3")
+    implementation("space.kscience:dataforge-io-proto:0.11.0-dev-1")
 }
 ```
diff --git a/dataforge-io/dataforge-io-yaml/README.md b/dataforge-io/dataforge-io-yaml/README.md
@@ -6,7 +6,7 @@ YAML meta IO
 
 ## Artifact:
 
-The Maven coordinates of this project are `space.kscience:dataforge-io-yaml:0.10.3`.
+The Maven coordinates of this project are `space.kscience:dataforge-io-yaml:0.11.0-dev-1`.
 
 **Gradle Kotlin DSL:**
 ```kotlin
@@ -16,6 +16,6 @@ repositories {
 }
 
 dependencies {
-    implementation("space.kscience:dataforge-io-yaml:0.10.3")
+    implementation("space.kscience:dataforge-io-yaml:0.11.0-dev-1")
 }
 ```
diff --git a/dataforge-meta/README.md b/dataforge-meta/README.md
@@ -13,7 +13,7 @@ Meta definition and basic operations on meta
 
 ## Artifact:
 
-The Maven coordinates of this project are `space.kscience:dataforge-meta:0.10.3`.
+The Maven coordinates of this project are `space.kscience:dataforge-meta:0.11.0-dev-1`.
 
 **Gradle Kotlin DSL:**
 ```kotlin
@@ -23,6 +23,6 @@ repositories {
 }
 
 dependencies {
-    implementation("space.kscience:dataforge-meta:0.10.3")
+    implementation("space.kscience:dataforge-meta:0.11.0-dev-1")
 }
 ```
diff --git a/dataforge-scripting/README.md b/dataforge-scripting/README.md
@@ -6,7 +6,7 @@ Scripting definition fow workspace generation
 
 ## Artifact:
 
-The Maven coordinates of this project are `space.kscience:dataforge-scripting:0.10.3`.
+The Maven coordinates of this project are `space.kscience:dataforge-scripting:0.11.0-dev-1`.
 
 **Gradle Kotlin DSL:**
 ```kotlin
@@ -16,6 +16,6 @@ repositories {
 }
 
 dependencies {
-    implementation("space.kscience:dataforge-scripting:0.10.3")
+    implementation("space.kscience:dataforge-scripting:0.11.0-dev-1")
 }
 ```
diff --git a/dataforge-workspace/README.md b/dataforge-workspace/README.md
@@ -6,7 +6,7 @@ A framework for pull-based data processing
 
 ## Artifact:
 
-The Maven coordinates of this project are `space.kscience:dataforge-workspace:0.10.3`.
+The Maven coordinates of this project are `space.kscience:dataforge-workspace:0.11.0-dev-1`.
 
 **Gradle Kotlin DSL:**
 ```kotlin
@@ -16,6 +16,6 @@ repositories {
 }
 
 dependencies {
-    implementation("space.kscience:dataforge-workspace:0.10.3")
+    implementation("space.kscience:dataforge-workspace:0.11.0-dev-1")
 }
 ```
diff --git a/tables-kt/README.md b/tables-kt/README.md
@@ -14,7 +14,7 @@ The library is intended as multiplatform. It supports JVM, JS-IR and Native targ
 
 ## Artifact:
 
-The Maven coordinates of this project are `space.kscience:tables-kt:0.10.3`.
+The Maven coordinates of this project are `space.kscience:tables-kt:0.11.0-dev-1`.
 
 **Gradle Kotlin DSL:**
 ```kotlin
@@ -24,7 +24,7 @@ repositories {
 }
 
 dependencies {
-    implementation("space.kscience:tables-kt:0.10.3")
+    implementation("space.kscience:tables-kt:0.11.0-dev-1")
 }
 ```
 
@@ -40,12 +40,23 @@ dependencies {
 > **Maturity**: EXPERIMENTAL
 
 ### [tables-kt/tables-kt-dataframe](tables-kt/tables-kt-dataframe)
+> An integration to convert DataForg tables to DataFrame and back.
 >
-> **Maturity**: PROTOTYPE
+> **Maturity**: EXPERIMENTAL
+>
+> **Features:**
+> - [asDataFrame](tables-kt/tables-kt-dataframe/src/main/kotlin/space/kscience/dataforge/dataframe/TableAsDataFrame.kt) : Conversion from DataForge Table to DataFrame via `asDataFrame()` extension function.
+> - [asTable](tables-kt/tables-kt-dataframe/src/main/kotlin/space/kscience/dataforge/dataframe/DataFrameAsTable.kt) : Conversion from DataFrame to DataForge Table via `asTable()` extension function.
+
 
 ### [tables-kt/tables-kt-exposed](tables-kt/tables-kt-exposed)
+> An integration to represent SQL tables as DataForg table via Exposed-JDBC
 >
 > **Maturity**: EXPERIMENTAL
+>
+> **Features:**
+> - [ExposedTable](tables-kt/tables-kt-exposed/src/main/kotlin/space/kscience/dataforge/exposed/ExposedTable.kt) : Create a table from JDBC database with `ExposedTable`.
+
 
 ### [tables-kt/tables-kt-jupyter](tables-kt/tables-kt-jupyter)
 >
diff --git a/tables-kt/tables-kt-csv/README.md b/tables-kt/tables-kt-csv/README.md
@@ -6,7 +6,7 @@
 
 ## Artifact:
 
-The Maven coordinates of this project are `space.kscience:tables-kt-csv:0.10.3`.
+The Maven coordinates of this project are `space.kscience:tables-kt-csv:0.11.0-dev-1`.
 
 **Gradle Kotlin DSL:**
 ```kotlin
@@ -16,6 +16,6 @@ repositories {
 }
 
 dependencies {
-    implementation("space.kscience:tables-kt-csv:0.10.3")
+    implementation("space.kscience:tables-kt-csv:0.11.0-dev-1")
 }
 ```
diff --git a/tables-kt/tables-kt-dataframe/README.md b/tables-kt/tables-kt-dataframe/README.md
@@ -1,12 +1,18 @@
 # Module tables-kt-dataframe
 
+An integration to convert DataForg tables to DataFrame and back.
+
+## Features
+
+ - [asDataFrame](src/main/kotlin/space/kscience/dataforge/dataframe/TableAsDataFrame.kt) : Conversion from DataForge Table to DataFrame via `asDataFrame()` extension function.
+ - [asTable](src/main/kotlin/space/kscience/dataforge/dataframe/DataFrameAsTable.kt) : Conversion from DataFrame to DataForge Table via `asTable()` extension function.
 
 
 ## Usage
 
 ## Artifact:
 
-The Maven coordinates of this project are `space.kscience:tables-kt-dataframe:0.10.3`.
+The Maven coordinates of this project are `space.kscience:tables-kt-dataframe:0.11.0-dev-1`.
 
 **Gradle Kotlin DSL:**
 ```kotlin
@@ -16,6 +22,6 @@ repositories {
 }
 
 dependencies {
-    implementation("space.kscience:tables-kt-dataframe:0.10.3")
+    implementation("space.kscience:tables-kt-dataframe:0.11.0-dev-1")
 }
 ```
diff --git a/tables-kt/tables-kt-dataframe/build.gradle.kts b/tables-kt/tables-kt-dataframe/build.gradle.kts
@@ -3,11 +3,21 @@ plugins {
     `maven-publish`
 }
 
+description = "An integration to convert DataForg tables to DataFrame and back."
+
 dependencies {
     api(libs.kotlinx.dataframe)
     api(projects.tablesKt)
 }
 
 readme {
-    maturity = space.kscience.gradle.Maturity.PROTOTYPE
+    maturity = space.kscience.gradle.Maturity.EXPERIMENTAL
+    
+    feature("asDataFrame", "src/main/kotlin/space/kscience/dataforge/dataframe/TableAsDataFrame.kt"){
+        "Conversion from DataForge Table to DataFrame via `asDataFrame()` extension function."
+    }
+
+    feature("asTable", "src/main/kotlin/space/kscience/dataforge/dataframe/DataFrameAsTable.kt"){
+        "Conversion from DataFrame to DataForge Table via `asTable()` extension function."
+    }
 }
diff --git a/tables-kt/tables-kt-dataframe/src/main/kotlin/space/kscience/dataforge/dataframe/DataFrameAsTable.kt b/tables-kt/tables-kt-dataframe/src/main/kotlin/space/kscience/dataforge/dataframe/DataFrameAsTable.kt
@@ -1,16 +1,14 @@
 package space.kscience.dataforge.dataframe
 
 import org.jetbrains.kotlinx.dataframe.*
-import org.jetbrains.kotlinx.dataframe.api.cast
-import org.jetbrains.kotlinx.dataframe.api.column
-import org.jetbrains.kotlinx.dataframe.api.getColumn
-import org.jetbrains.kotlinx.dataframe.api.rows
+import org.jetbrains.kotlinx.dataframe.api.*
 import space.kscience.dataforge.meta.Meta
 import space.kscience.tables.Column
 import space.kscience.tables.ColumnHeader
 import space.kscience.tables.Row
 import space.kscience.tables.Table
 import kotlin.reflect.KType
+import kotlin.reflect.full.isSupertypeOf
 
 @JvmInline
 internal value class DataColumnAsColumn<T>(val column: DataColumn<T>) : Column<T> {
@@ -52,12 +50,51 @@ internal value class DataFrameAsTable<T>(private val dataFrame: DataFrame<T>) :
  */
 public fun <T> DataFrame<T>.asTable(): Table<T> = DataFrameAsTable(this)
 
+/**
+ * Retrieves a column from the current [DataFrame] based on the specified [ColumnHeader].
+ *
+ * This function looks up the column in the [DataFrame] using the name provided
+ * in the given [ColumnHeader]. The resulting column is returned as a [DataColumn].
+ *
+ * @param R The type of the column's values, inferred from the [ColumnHeader].
+ * @param header The [ColumnHeader] defining the name and type of the column to retrieve.
+ * @return The [DataColumn] corresponding to the specified [ColumnHeader].
+ */
 public operator fun <R> DataFrame<*>.get(header: ColumnHeader<R>): DataColumn<R> {
-    val reference = column<R>(header.name)
-    return get(reference)
+    val index = columnNames().indexOf(header.name)
+
+    if (index == -1) throw NoSuchElementException("Column ${header.name} not found in row")
+
+    val columnType = columnTypes()[index]
+
+    if (header.type.isSupertypeOf(columnType)) {
+        @Suppress("UNCHECKED_CAST")
+        return getColumn(index).cast<R>()
+    } else {
+        error("Column type mismatch for ${header.name}. Expected ${header.type}, but found ${columnType}")
+    }
 }
 
+/**
+ * Retrieves the value of the specified column from the current data row.
+ * The column is identified by its header, which includes the column name and type.
+ *
+ * @param header The header of the column to retrieve. Includes the column's name and type information.
+ * @return The value of the specified column from the current row, cast to the type specified in the header.
+ * @throws NoSuchElementException If the column with the specified name does not exist in the row.
+ * @throws IllegalStateException If the type of the column in the row does not match the type specified in the header.
+ */
 public operator fun <R> DataRow<*>.get(header: ColumnHeader<R>): R {
-    val reference = column<R>(header.name)
-    return get(reference)
+    val index = columnNames().indexOf(header.name)
+
+    if (index == -1) throw NoSuchElementException("Column ${header.name} not found in row")
+
+    val columnType = columnTypes()[index]
+
+    if (header.type.isSupertypeOf(columnType)) {
+        @Suppress("UNCHECKED_CAST")
+        return get(index) as R
+    } else {
+        error("Column type mismatch for ${header.name}. Expected ${header.type}, but found ${columnType}")
+    }
 }
diff --git a/tables-kt/tables-kt-dataframe/src/main/kotlin/space/kscience/dataforge/dataframe/TableAsDataFrame.kt b/tables-kt/tables-kt-dataframe/src/main/kotlin/space/kscience/dataforge/dataframe/TableAsDataFrame.kt
@@ -68,6 +68,16 @@ internal fun <T> TableColumn<T>.asDataColumn(): AnyCol = if (this is DataColumnA
 
 //TODO convert typed value columns to primitive columns
 
+/**
+ * Converts the current [Table] instance into a [DataFrame].
+ *
+ * This function maps the table's columns to data frame columns and constructs
+ * a new [DataFrame] from the mapped columns. The resulting [DataFrame] provides
+ * a tabular data structure with additional capabilities for data manipulation
+ * and analysis.
+ *
+ * @return A [DataFrame] created from the contents of the [Table].
+ */
 @Suppress("UNCHECKED_CAST")
 public fun <T> Table<T>.toDataFrame(): DataFrame<T> =
     dataFrameOf(columns.map { it.asDataColumn() }) as DataFrame<T>
diff --git a/tables-kt/tables-kt-dataframe/src/test/kotlin/space/kscience/dataforge/dataframe/DataFrameTableTest.kt b/tables-kt/tables-kt-dataframe/src/test/kotlin/space/kscience/dataforge/dataframe/DataFrameTableTest.kt
diff --git a/tables-kt/tables-kt-exposed/README.md b/tables-kt/tables-kt-exposed/README.md
diff --git a/tables-kt/tables-kt-exposed/build.gradle.kts b/tables-kt/tables-kt-exposed/build.gradle.kts
diff --git a/tables-kt/tables-kt-jupyter/README.md b/tables-kt/tables-kt-jupyter/README.md

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ Context and provider definitions`
`6`	`6`
`7`	`7`	`## Artifact:`
`8`	`8`
`9`		-The Maven coordinates of this project are `space.kscience:dataforge-context:0.10.3`.
	`9`	+The Maven coordinates of this project are `space.kscience:dataforge-context:0.11.0-dev-1`.
`10`	`10`
`11`	`11`	`Gradle Kotlin DSL:`
`12`	`12`	```kotlin
`@@ -16,6 +16,6 @@ repositories {`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`dependencies {`
`19`		`- implementation("space.kscience:dataforge-context:0.10.3")`
	`19`	`+ implementation("space.kscience:dataforge-context:0.11.0-dev-1")`
`20`	`20`	`}`
`21`	`21`	```
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@`
`6`	`6`
`7`	`7`	`## Artifact:`
`8`	`8`
`9`		-The Maven coordinates of this project are `space.kscience:dataforge-data:0.10.3`.
	`9`	+The Maven coordinates of this project are `space.kscience:dataforge-data:0.11.0-dev-1`.
`10`	`10`
`11`	`11`	`Gradle Kotlin DSL:`
`12`	`12`	```kotlin
`@@ -16,6 +16,6 @@ repositories {`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`dependencies {`
`19`		`- implementation("space.kscience:dataforge-data:0.10.3")`
	`19`	`+ implementation("space.kscience:dataforge-data:0.11.0-dev-1")`
`20`	`20`	`}`
`21`	`21`	```
Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,7 @@ IO module`
`15`	`15`
`16`	`16`	`## Artifact:`
`17`	`17`
`18`		-The Maven coordinates of this project are `space.kscience:dataforge-io:0.10.3`.
	`18`	+The Maven coordinates of this project are `space.kscience:dataforge-io:0.11.0-dev-1`.
`19`	`19`
`20`	`20`	`Gradle Kotlin DSL:`
`21`	`21`	```kotlin
`@@ -25,6 +25,6 @@ repositories {`
`25`	`25`	`}`
`26`	`26`
`27`	`27`	`dependencies {`
`28`		`- implementation("space.kscience:dataforge-io:0.10.3")`
	`28`	`+ implementation("space.kscience:dataforge-io:0.11.0-dev-1")`
`29`	`29`	`}`
`30`	`30`	```
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ ProtoBuf meta IO`
`6`	`6`
`7`	`7`	`## Artifact:`
`8`	`8`
`9`		-The Maven coordinates of this project are `space.kscience:dataforge-io-proto:0.10.3`.
	`9`	+The Maven coordinates of this project are `space.kscience:dataforge-io-proto:0.11.0-dev-1`.
`10`	`10`
`11`	`11`	`Gradle Kotlin DSL:`
`12`	`12`	```kotlin
`@@ -16,6 +16,6 @@ repositories {`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`dependencies {`
`19`		`- implementation("space.kscience:dataforge-io-proto:0.10.3")`
	`19`	`+ implementation("space.kscience:dataforge-io-proto:0.11.0-dev-1")`
`20`	`20`	`}`
`21`	`21`	```
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ YAML meta IO`
`6`	`6`
`7`	`7`	`## Artifact:`
`8`	`8`
`9`		-The Maven coordinates of this project are `space.kscience:dataforge-io-yaml:0.10.3`.
	`9`	+The Maven coordinates of this project are `space.kscience:dataforge-io-yaml:0.11.0-dev-1`.
`10`	`10`
`11`	`11`	`Gradle Kotlin DSL:`
`12`	`12`	```kotlin
`@@ -16,6 +16,6 @@ repositories {`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`dependencies {`
`19`		`- implementation("space.kscience:dataforge-io-yaml:0.10.3")`
	`19`	`+ implementation("space.kscience:dataforge-io-yaml:0.11.0-dev-1")`
`20`	`20`	`}`
`21`	`21`	```
Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,7 @@ Meta definition and basic operations on meta`
`13`	`13`
`14`	`14`	`## Artifact:`
`15`	`15`
`16`		-The Maven coordinates of this project are `space.kscience:dataforge-meta:0.10.3`.
	`16`	+The Maven coordinates of this project are `space.kscience:dataforge-meta:0.11.0-dev-1`.
`17`	`17`
`18`	`18`	`Gradle Kotlin DSL:`
`19`	`19`	```kotlin
`@@ -23,6 +23,6 @@ repositories {`
`23`	`23`	`}`
`24`	`24`
`25`	`25`	`dependencies {`
`26`		`- implementation("space.kscience:dataforge-meta:0.10.3")`
	`26`	`+ implementation("space.kscience:dataforge-meta:0.11.0-dev-1")`
`27`	`27`	`}`
`28`	`28`	```
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ Scripting definition fow workspace generation`
`6`	`6`
`7`	`7`	`## Artifact:`
`8`	`8`
`9`		-The Maven coordinates of this project are `space.kscience:dataforge-scripting:0.10.3`.
	`9`	+The Maven coordinates of this project are `space.kscience:dataforge-scripting:0.11.0-dev-1`.
`10`	`10`
`11`	`11`	`Gradle Kotlin DSL:`
`12`	`12`	```kotlin
`@@ -16,6 +16,6 @@ repositories {`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`dependencies {`
`19`		`- implementation("space.kscience:dataforge-scripting:0.10.3")`
	`19`	`+ implementation("space.kscience:dataforge-scripting:0.11.0-dev-1")`
`20`	`20`	`}`
`21`	`21`	```
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ A framework for pull-based data processing`
`6`	`6`
`7`	`7`	`## Artifact:`
`8`	`8`
`9`		-The Maven coordinates of this project are `space.kscience:dataforge-workspace:0.10.3`.
	`9`	+The Maven coordinates of this project are `space.kscience:dataforge-workspace:0.11.0-dev-1`.
`10`	`10`
`11`	`11`	`Gradle Kotlin DSL:`
`12`	`12`	```kotlin
`@@ -16,6 +16,6 @@ repositories {`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`dependencies {`
`19`		`- implementation("space.kscience:dataforge-workspace:0.10.3")`
	`19`	`+ implementation("space.kscience:dataforge-workspace:0.11.0-dev-1")`
`20`	`20`	`}`
`21`	`21`	```