Merge branch 'master' into website_docs_landing

# Conflicts:
#	docs/StardustDocs/topics/DataColumn.md

Author: AndreiKingsley

README.md

@@ -22,10 +22,6 @@ Kotlin DataFrame aims to reconcile Kotlin's static typing with the dynamic natur
 
 Integrates with [Kotlin kernel for Jupyter](https://github.com/Kotlin/kotlin-jupyter). Inspired by [krangl](https://github.com/holgerbrandl/krangl), Kotlin Collections and [pandas](https://pandas.pydata.org/)
 
-## Do you use Kotlin DataFrame or have you used it in the past?
-Join us for a one-hour interview and get a USD 100 Amazon Gift Card or a one-year JetBrains All Products Pack subscription.
-Simply [fill out a form](https://surveys.jetbrains.com/s3/kdf) and schedule a session if your profile matches our study criteria.
-
 ## Documentation
 
 Explore [**documentation**](https://kotlin.github.io/dataframe/overview.html) for details.

build.gradle.kts

@@ -50,10 +50,13 @@ configurations {
 
 dependencies {
     api(projects.core)
+
+    // expose all optional IO dependencies by default
     api(projects.dataframeArrow)
     api(projects.dataframeExcel)
     api(projects.dataframeJdbc)
     api(projects.dataframeCsv)
+    api(projects.dataframeJson)
 
     // experimental, so not included by default:
     // api(projects.dataframeOpenapi)
@@ -64,6 +67,7 @@ dependencies {
     kover(projects.dataframeOpenapi)
     kover(projects.dataframeJdbc)
     kover(projects.dataframeCsv)
+    kover(projects.dataframeJson)
     kover(projects.plugins.kotlinDataframe)
     kover(projects.dataframeJupyter)
 }

core/api/core.api

@@ -66,8 +66,6 @@ dependencies {
     api(libs.commonsCsv)
 
     implementation(libs.commonsIo)
-    implementation(libs.serialization.core)
-    implementation(libs.serialization.json)
     implementation(libs.fastDoubleParser)
 
     api(libs.kotlin.datetimeJvm)
@@ -82,6 +80,9 @@ dependencies {
     testImplementation(libs.kotlin.scriptingJvm)
     testImplementation(libs.jsoup)
     testImplementation(libs.sl4jsimple)
+    testImplementation(projects.dataframeJson)
+    testImplementation(libs.serialization.core)
+    testImplementation(libs.serialization.json)
 
     // for checking results
     testImplementation(libs.commonsStatisticsDescriptive)
@@ -315,9 +316,6 @@ korro {
         funSuffix("_properties") {
             replaceText("NAME", "Properties")
         }
-        funSuffix("_accessors") {
-            replaceText("NAME", "Accessors")
-        }
         funSuffix("_strings") {
             replaceText("NAME", "Strings")
         }

core/build.gradle.kts

@@ -43,9 +43,15 @@ public interface ColumnsContainer<out T> : ColumnsScope<T> {
 
     public fun getColumnOrNull(index: Int): AnyCol?
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public fun <R> getColumnOrNull(column: ColumnReference<R>): DataColumn<R>?
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public fun <R> getColumnOrNull(column: KProperty<R>): DataColumn<R>?
 
@@ -61,31 +67,58 @@ public interface ColumnsContainer<out T> : ColumnsScope<T> {
 
     public operator fun get(columnPath: ColumnPath): AnyCol = getColumn(columnPath)
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> get(column: DataColumn<R>): DataColumn<R> = getColumn(column.name()).cast()
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> get(column: DataColumn<DataRow<R>>): ColumnGroup<R> = getColumn(column)
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> get(column: DataColumn<DataFrame<R>>): FrameColumn<R> = getColumn(column)
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> get(column: ColumnReference<R>): DataColumn<R> = getColumn(column)
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> get(column: ColumnReference<DataRow<R>>): ColumnGroup<R> = getColumn(column)
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> get(column: ColumnReference<DataFrame<R>>): FrameColumn<R> = getColumn(column)
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> get(column: KProperty<R>): DataColumn<R> = get(column.columnName).cast()
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> get(column: KProperty<DataRow<R>>): ColumnGroup<R> =
         get(column.columnName).asColumnGroup().cast()
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> get(column: KProperty<DataFrame<R>>): FrameColumn<R> =
         get(column.columnName).asAnyFrameColumn().castFrameColumn()

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/ColumnsContainer.kt

@@ -121,6 +121,9 @@ public interface DataFrame<out T> :
  */
 public operator fun <T, C> DataFrame<T>.get(columns: ColumnsSelector<T, C>): List<DataColumn<C>> = this.get(columns)
 
+@Deprecated(
+    "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+)
 @AccessApiOverload
 public operator fun <T> DataFrame<T>.get(first: AnyColumnReference, vararg other: AnyColumnReference): DataFrame<T> =
     select { (listOf(first) + other).toColumnSet() }

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/DataFrame.kt

@@ -28,15 +28,27 @@ public interface DataRow<out T> {
 
     public operator fun <R> get(expression: RowExpression<T, R>): R = expression(this, this)
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> get(column: ColumnReference<R>): R
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> get(columns: List<ColumnReference<R>>): List<R> = columns.map { get(it) }
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> get(property: KProperty<R>): R = get(property.columnName) as R
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun get(first: AnyColumnReference, vararg other: AnyColumnReference): DataRow<T> =
         owner.get(first, *other)[index]
@@ -71,6 +83,9 @@ public interface DataRow<out T> {
 
     public fun getOrNull(name: String): Any?
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public fun <R> getValueOrNull(column: ColumnReference<R>): R?
 
@@ -80,6 +95,9 @@ public interface DataRow<out T> {
 
     public operator fun String.get(vararg path: String): ColumnPath = ColumnPath(listOf(this) + path)
 
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <R> ColumnReference<R>.invoke(): R = get(this)
 

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/DataRow.kt

@@ -5,7 +5,6 @@ import org.jetbrains.kotlinx.dataframe.api.KeyValueProperty
 import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup
 import org.jetbrains.kotlinx.dataframe.columns.FrameColumn
 import org.jetbrains.kotlinx.dataframe.documentation.UnifyingNumbers
-import org.jetbrains.kotlinx.dataframe.io.JSON
 
 /**
  * Annotation preprocessing will generate a DataSchema interface from the data at `path`.
@@ -73,8 +72,11 @@ public annotation class JdbcOptions(
 )
 
 public annotation class JsonOptions(
-    /** Allows the choice of how to handle type clashes when reading a JSON file. */
-    public val typeClashTactic: JSON.TypeClashTactic = JSON.TypeClashTactic.ARRAY_AND_VALUE_COLUMNS,
+    /**
+     * Allows the choice of how to handle type clashes when reading a JSON file.
+     * Must be either [JsonOptions.TypeClashTactics.ARRAY_AND_VALUE_COLUMNS] or [JsonOptions.TypeClashTactics.ANY_COLUMNS]
+     * */
+    public val typeClashTactic: String = TypeClashTactics.ARRAY_AND_VALUE_COLUMNS,
     /**
      * List of [JsonPath]s where instead of a [ColumnGroup], a [FrameColumn]<[KeyValueProperty]>
      *     will be created.
@@ -85,4 +87,9 @@ public annotation class JsonOptions(
     public val keyValuePaths: Array<String> = [],
     /** Whether to [unify the numbers that are read][UnifyingNumbers]. `true` by default. */
     public val unifyNumbers: Boolean = true,
-)
+) {
+    public object TypeClashTactics {
+        public const val ARRAY_AND_VALUE_COLUMNS: String = "ARRAY_AND_VALUE_COLUMNS"
+        public const val ANY_COLUMNS: String = "ANY_COLUMNS"
+    }
+}

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/annotations/ImportDataSchema.kt

@@ -86,6 +86,9 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * @throws [IllegalArgumentException] if the column is not found.
      * @return The [DataColumn] this [KProperty Accessor][KProperty] points to.
      */
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <T> KProperty<T>.invoke(): DataColumn<T> = this@ColumnSelectionDsl[this]
 
@@ -96,6 +99,9 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * @throws [IllegalArgumentException] if the column is not found.
      * @return The [ColumnGroup] this [KProperty Accessor][KProperty] points to.
      */
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <T> KProperty<DataRow<T>>.invoke(): ColumnGroup<T> = this@ColumnSelectionDsl[this]
 
@@ -106,6 +112,9 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * @throws [IllegalArgumentException] if the column is not found.
      * @return The [FrameColumn] this [KProperty Accessor][KProperty] points to.
      */
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <T> KProperty<DataFrame<T>>.invoke(): FrameColumn<T> = this@ColumnSelectionDsl[this]
 
@@ -140,6 +149,9 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      */
     @Suppress("INAPPLICABLE_JVM_NAME")
     @JvmName("KPropertyDataRowGet")
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <T, R> KProperty<DataRow<T>>.get(column: KProperty<R>): DataColumn<R> = invoke()[column]
 
@@ -159,6 +171,9 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      */
     @Suppress("INAPPLICABLE_JVM_NAME")
     @JvmName("KPropertyDataRowGet")
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <T, R> KProperty<DataRow<T>>.get(column: KProperty<DataRow<R>>): ColumnGroup<R> =
         invoke()[column]
@@ -179,6 +194,9 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      */
     @Suppress("INAPPLICABLE_JVM_NAME")
     @JvmName("KPropertyDataRowGet")
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <T, R> KProperty<DataRow<T>>.get(column: KProperty<DataFrame<R>>): FrameColumn<R> =
         invoke()[column]
@@ -197,6 +215,9 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * @throws [IllegalArgumentException] if the column is not found.
      * @return The [DataColumn] these [KProperty Accessors][KProperty] point to.
      */
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <T, R> KProperty<T>.get(column: KProperty<R>): DataColumn<R> = invoke().asColumnGroup()[column]
 
@@ -214,6 +235,9 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * @throws [IllegalArgumentException] if the column is not found.
      * @return The [ColumnGroup] these [KProperty Accessors][KProperty] point to.
      */
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <T, R> KProperty<T>.get(column: KProperty<DataRow<R>>): ColumnGroup<R> =
         invoke().asColumnGroup()[column]
@@ -232,6 +256,9 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * @throws [IllegalArgumentException] if the column is not found.
      * @return The [FrameColumn] these [KProperty Accessors][KProperty] point to.
      */
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <T, R> KProperty<T>.get(column: KProperty<DataFrame<R>>): FrameColumn<R> =
         invoke().asColumnGroup()[column]

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnSelectionDsl.kt

@@ -492,6 +492,9 @@ public interface ColumnsSelectionDsl<out T> : // SingleColumn<DataRow<T>>
      * @return A [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] containing the columns selected by [selector].
      * @see [SingleColumn.except]
      */
+    @Deprecated(
+        "Recommended to migrate to use String or Extension properties API https://kotlin.github.io/dataframe/apilevels.html",
+    )
     @AccessApiOverload
     public operator fun <C, R> KProperty<C>.invoke(selector: ColumnsSelector<C, R>): ColumnSet<R> =
         columnGroup(this).select(selector)