Merging KeyValueProperty and NameValuePair

core/api/core.api

@@ -1948,6 +1948,8 @@ public final class org/jetbrains/kotlinx/dataframe/api/DataFrameGetKt {
 }
 
 public final class org/jetbrains/kotlinx/dataframe/api/DataRowApiKt {
+	public static final fun NameValuePairAny_key (Lorg/jetbrains/kotlinx/dataframe/ColumnsContainer;)Lorg/jetbrains/kotlinx/dataframe/DataColumn;
+	public static final fun NameValuePairAny_key (Lorg/jetbrains/kotlinx/dataframe/DataRow;)Ljava/lang/String;
 	public static final fun NameValuePairAny_name (Lorg/jetbrains/kotlinx/dataframe/ColumnsContainer;)Lorg/jetbrains/kotlinx/dataframe/DataColumn;
 	public static final fun NameValuePairAny_name (Lorg/jetbrains/kotlinx/dataframe/DataRow;)Ljava/lang/String;
 	public static final fun NameValuePairAny_value (Lorg/jetbrains/kotlinx/dataframe/ColumnsContainer;)Lorg/jetbrains/kotlinx/dataframe/DataColumn;
@@ -1960,6 +1962,8 @@ public final class org/jetbrains/kotlinx/dataframe/api/DataRowApiKt {
 	public static final fun containsKey (Lorg/jetbrains/kotlinx/dataframe/DataRow;Ljava/lang/String;)Z
 	public static final fun containsKey (Lorg/jetbrains/kotlinx/dataframe/DataRow;Lkotlin/reflect/KProperty;)Z
 	public static final fun containsKey (Lorg/jetbrains/kotlinx/dataframe/DataRow;Lorg/jetbrains/kotlinx/dataframe/columns/ColumnReference;)Z
+	public static final fun copy (Lorg/jetbrains/kotlinx/dataframe/api/NameValuePair;Ljava/lang/String;Ljava/lang/Object;)Lorg/jetbrains/kotlinx/dataframe/api/NameValuePair;
+	public static synthetic fun copy$default (Lorg/jetbrains/kotlinx/dataframe/api/NameValuePair;Ljava/lang/String;Ljava/lang/Object;ILjava/lang/Object;)Lorg/jetbrains/kotlinx/dataframe/api/NameValuePair;
 	public static final fun diff (Lorg/jetbrains/kotlinx/dataframe/DataRow;DLkotlin/jvm/functions/Function2;)D
 	public static final fun diff (Lorg/jetbrains/kotlinx/dataframe/DataRow;FLkotlin/jvm/functions/Function2;)F
 	public static final fun diff (Lorg/jetbrains/kotlinx/dataframe/DataRow;ILkotlin/jvm/functions/Function2;)I
@@ -1968,6 +1972,7 @@ public final class org/jetbrains/kotlinx/dataframe/api/DataRowApiKt {
 	public static final fun diffOrNull (Lorg/jetbrains/kotlinx/dataframe/DataRow;Lkotlin/jvm/functions/Function2;)Ljava/lang/Float;
 	public static final fun diffOrNull (Lorg/jetbrains/kotlinx/dataframe/DataRow;Lkotlin/jvm/functions/Function2;)Ljava/lang/Integer;
 	public static final fun diffOrNull (Lorg/jetbrains/kotlinx/dataframe/DataRow;Lkotlin/jvm/functions/Function2;)Ljava/lang/Long;
+	public static final fun getName (Lorg/jetbrains/kotlinx/dataframe/api/NameValuePair;)Ljava/lang/String;
 	public static final fun getRow (Lorg/jetbrains/kotlinx/dataframe/DataRow;I)Lorg/jetbrains/kotlinx/dataframe/DataRow;
 	public static final fun getRowOrNull (Lorg/jetbrains/kotlinx/dataframe/DataRow;I)Lorg/jetbrains/kotlinx/dataframe/DataRow;
 	public static final fun getRows (Lorg/jetbrains/kotlinx/dataframe/DataRow;Ljava/lang/Iterable;)Lorg/jetbrains/kotlinx/dataframe/DataFrame;
@@ -3466,26 +3471,31 @@ public final class org/jetbrains/kotlinx/dataframe/api/MoveKt {
 	public static final fun under (Lorg/jetbrains/kotlinx/dataframe/api/MoveClause;Lorg/jetbrains/kotlinx/dataframe/columns/ColumnAccessor;)Lorg/jetbrains/kotlinx/dataframe/DataFrame;
 }
 
-public final class org/jetbrains/kotlinx/dataframe/api/NameValuePair {
+public final class org/jetbrains/kotlinx/dataframe/api/NameValuePair : org/jetbrains/kotlinx/dataframe/api/KeyValueProperty {
+	public static final field Companion Lorg/jetbrains/kotlinx/dataframe/api/NameValuePair$Companion;
 	public fun <init> (Ljava/lang/String;Ljava/lang/Object;)V
 	public final fun component1 ()Ljava/lang/String;
 	public final fun component2 ()Ljava/lang/Object;
 	public final fun copy (Ljava/lang/String;Ljava/lang/Object;)Lorg/jetbrains/kotlinx/dataframe/api/NameValuePair;
 	public static synthetic fun copy$default (Lorg/jetbrains/kotlinx/dataframe/api/NameValuePair;Ljava/lang/String;Ljava/lang/Object;ILjava/lang/Object;)Lorg/jetbrains/kotlinx/dataframe/api/NameValuePair;
 	public fun equals (Ljava/lang/Object;)Z
-	public final fun getName ()Ljava/lang/String;
-	public final fun getValue ()Ljava/lang/Object;
+	public fun getKey ()Ljava/lang/String;
+	public fun getValue ()Ljava/lang/Object;
 	public fun hashCode ()I
 	public fun toString ()Ljava/lang/String;
 }
 
+public final class org/jetbrains/kotlinx/dataframe/api/NameValuePair$Companion {
+	public final fun invoke (Ljava/lang/String;Ljava/lang/Object;)Lorg/jetbrains/kotlinx/dataframe/api/NameValuePair;
+}
+
 public final class org/jetbrains/kotlinx/dataframe/api/NameValuePair_ExtensionsKt {
-	public static final fun NameValuePair_name (Lorg/jetbrains/kotlinx/dataframe/ColumnsScope;)Lorg/jetbrains/kotlinx/dataframe/DataColumn;
-	public static final fun NameValuePair_name (Lorg/jetbrains/kotlinx/dataframe/DataRow;)Ljava/lang/String;
+	public static final fun NameValuePair_key (Lorg/jetbrains/kotlinx/dataframe/ColumnsScope;)Lorg/jetbrains/kotlinx/dataframe/DataColumn;
+	public static final fun NameValuePair_key (Lorg/jetbrains/kotlinx/dataframe/DataRow;)Ljava/lang/String;
 	public static final fun NameValuePair_value (Lorg/jetbrains/kotlinx/dataframe/ColumnsScope;)Lorg/jetbrains/kotlinx/dataframe/DataColumn;
 	public static final fun NameValuePair_value (Lorg/jetbrains/kotlinx/dataframe/DataRow;)Ljava/lang/Object;
-	public static final fun NullableNameValuePair_name (Lorg/jetbrains/kotlinx/dataframe/ColumnsScope;)Lorg/jetbrains/kotlinx/dataframe/DataColumn;
-	public static final fun NullableNameValuePair_name (Lorg/jetbrains/kotlinx/dataframe/DataRow;)Ljava/lang/String;
+	public static final fun NullableNameValuePair_key (Lorg/jetbrains/kotlinx/dataframe/ColumnsScope;)Lorg/jetbrains/kotlinx/dataframe/DataColumn;
+	public static final fun NullableNameValuePair_key (Lorg/jetbrains/kotlinx/dataframe/DataRow;)Ljava/lang/String;
 	public static final fun NullableNameValuePair_value (Lorg/jetbrains/kotlinx/dataframe/ColumnsScope;)Lorg/jetbrains/kotlinx/dataframe/DataColumn;
 	public static final fun NullableNameValuePair_value (Lorg/jetbrains/kotlinx/dataframe/DataRow;)Ljava/lang/Object;
 }

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/DataRowApi.kt

@@ -25,6 +25,7 @@ import org.jetbrains.kotlinx.dataframe.util.GET_ROW_REPLACE
 import org.jetbrains.kotlinx.dataframe.util.IS_EMPTY_REPLACE
 import org.jetbrains.kotlinx.dataframe.util.IS_NOT_EMPTY_REPLACE
 import org.jetbrains.kotlinx.dataframe.util.MESSAGE_SHORTCUT
+import org.jetbrains.kotlinx.dataframe.util.NAME_VALUE_PAIR
 import kotlin.experimental.ExperimentalTypeInference
 import kotlin.reflect.KProperty
 import kotlin.reflect.KType
@@ -39,18 +40,52 @@ public fun AnyRow.isNotEmpty(): Boolean = !isEmpty()
 public inline fun <reified R> AnyRow.valuesOf(): List<R> = values().filterIsInstance<R>()
 
 // region DataSchema
+
+/**
+ * Instantiatable [KeyValueProperty] representing a key-value pair [DataSchema] for a [DataFrame].
+ *
+ * [NameValuePair] may be deprecated in favor of an instantiatable [KeyValueProperty] class in the future.
+ *
+ * @param V type of the value
+ * @param key the name of the key column (previously called `name`)
+ * @param value the name of the value column
+ */
 @DataSchema
 @RequiredByIntellijPlugin
-public data class NameValuePair<V>(val name: String, val value: V)
+public data class NameValuePair<V>(override val key: String, override val value: V) : KeyValueProperty<V> {
+    public companion object {
+        @Deprecated(NAME_VALUE_PAIR, level = DeprecationLevel.WARNING)
+        public operator fun <V> invoke(name: String, value: V): NameValuePair<V> = NameValuePair(name, value)
+    }
+}
+
+@Deprecated(NAME_VALUE_PAIR, ReplaceWith("key"), level = DeprecationLevel.WARNING)
+public val NameValuePair<*>.name: String
+    get() = key
+
+@Deprecated(NAME_VALUE_PAIR, ReplaceWith("this.copy(name, value)"), level = DeprecationLevel.WARNING)
+public fun <V> NameValuePair<V>.copy(name: String = this.key, value: V = this.value): NameValuePair<V> =
+    NameValuePair(key = name, value = value)
 
 // Without these overloads row.transpose().name or row.map { name } won't resolve
+
+@Deprecated(NAME_VALUE_PAIR, ReplaceWith("this.key"), level = DeprecationLevel.WARNING)
 public val ColumnsContainer<NameValuePair<*>>.name: DataColumn<String>
     @JvmName("NameValuePairAny_name")
-    get() = this["name"] as DataColumn<String>
+    get() = this["key"] as DataColumn<String>
 
+@Deprecated(NAME_VALUE_PAIR, ReplaceWith("this.key"), level = DeprecationLevel.WARNING)
 public val DataRow<NameValuePair<*>>.name: String
     @JvmName("NameValuePairAny_name")
-    get() = this["name"] as String
+    get() = this["key"] as String
+
+public val ColumnsContainer<NameValuePair<*>>.key: DataColumn<String>
+    @JvmName("NameValuePairAny_key")
+    get() = this["key"] as DataColumn<String>
+
+public val DataRow<NameValuePair<*>>.key: String
+    @JvmName("NameValuePairAny_key")
+    get() = this["key"] as String
 
 public val ColumnsContainer<NameValuePair<*>>.value: DataColumn<*>
     @JvmName("NameValuePairAny_value")

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/KeyValueProperty.kt

@@ -3,7 +3,10 @@ package org.jetbrains.kotlinx.dataframe.api
 import org.jetbrains.kotlinx.dataframe.annotations.ColumnName
 import org.jetbrains.kotlinx.dataframe.annotations.DataSchema
 
-/** A [DataSchema] interface / class can implement this if it represents a map-like data schema (so key: value). */
+/**
+ * A [DataSchema] interface / class can implement this if it represents a map-like data schema (so key: value).
+ * @see [NameValuePair]
+ */
 @DataSchema
 public interface KeyValueProperty<T> {
     // needs to be explicitly overridden in @DataSchema interface, otherwise extension functions won't generate (TODO)

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/transpose.kt

@@ -14,8 +14,8 @@ import kotlin.reflect.typeOf
 // region DataRow
 
 public fun <T> DataRow<T>.transpose(): DataFrame<NameValuePair<*>> {
-    val valueColumn = DataColumn.createByInference(NameValuePair<*>::value.columnName, values)
-    val nameColumn = owner.columnNames().toValueColumn(NameValuePair<*>::name.name)
+    val valueColumn = DataColumn.createByInference(KeyValueProperty<*>::value.columnName, values)
+    val nameColumn = owner.columnNames().toValueColumn(KeyValueProperty<*>::key.name)
     return dataFrameOf(nameColumn, valueColumn).cast()
 }
 
@@ -24,8 +24,8 @@ public inline fun <reified T> AnyRow.transposeTo(): DataFrame<NameValuePair<T>>
 @PublishedApi
 internal fun <T> AnyRow.transposeTo(type: KType): DataFrame<NameValuePair<T>> {
     val convertedValues = values.map { it?.convertTo(type) as T? }
-    val valueColumn = DataColumn.createByInference(NameValuePair<T>::value.columnName, convertedValues)
-    val nameColumn = owner.columnNames().toValueColumn(NameValuePair<T>::name.name)
+    val valueColumn = DataColumn.createByInference(KeyValueProperty<T>::value.columnName, convertedValues)
+    val nameColumn = owner.columnNames().toValueColumn(KeyValueProperty<T>::key.name)
     return dataFrameOf(nameColumn, valueColumn).cast()
 }
 

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt

@@ -263,6 +263,9 @@ internal const val COPY_REPLACE = "columns().toDataFrame().cast()"
 internal const val LISTS_TO_DATAFRAME_MIGRATION =
     "Function moved from io to api package, and a new `header` parameter is introduced. $MESSAGE_1_1"
 
+internal const val NAME_VALUE_PAIR =
+    "'name' of NameValuePair will be renamed to 'key' to align with KeyValueProperty, Issue #659. $MESSAGE_1_1"
+
 // endregion
 
 // region keep across releases

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/puzzles/MediumTests.kt

@@ -12,6 +12,7 @@ import org.jetbrains.kotlinx.dataframe.api.diffOrNull
 import org.jetbrains.kotlinx.dataframe.api.filter
 import org.jetbrains.kotlinx.dataframe.api.groupBy
 import org.jetbrains.kotlinx.dataframe.api.isNaN
+import org.jetbrains.kotlinx.dataframe.api.key
 import org.jetbrains.kotlinx.dataframe.api.map
 import org.jetbrains.kotlinx.dataframe.api.mapToColumn
 import org.jetbrains.kotlinx.dataframe.api.minBy
@@ -78,8 +79,8 @@ class MediumTests {
             .sum()
             .transposeTo<Double>()
             .minBy { value }
-            .name shouldBe "b"
-        df.sum().transpose().minBy("value")["name"] shouldBe "b"
+            .key shouldBe "b"
+        df.sum().transpose().minBy("value")["key"] shouldBe "b"
     }
 
     @Test

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/animals/AnimalsTests.kt

@@ -4,6 +4,7 @@ import io.kotest.matchers.doubles.shouldBeNaN
 import io.kotest.matchers.shouldBe
 import org.jetbrains.kotlinx.dataframe.api.columnOf
 import org.jetbrains.kotlinx.dataframe.api.dataFrameOf
+import org.jetbrains.kotlinx.dataframe.api.key
 import org.jetbrains.kotlinx.dataframe.api.mean
 import org.jetbrains.kotlinx.dataframe.api.name
 import org.jetbrains.kotlinx.dataframe.api.transpose
@@ -33,7 +34,7 @@ class AnimalsTests {
         val mean = df.mean().transpose()
         mean.columnsCount() shouldBe 2
         mean.rowsCount() shouldBe 2
-        mean.name.values() shouldBe listOf("age", "visits")
+        mean.key.values() shouldBe listOf("age", "visits")
         mean.value.type() shouldBe typeOf<Double>()
     }
 

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTests.kt

@@ -85,6 +85,7 @@ import org.jetbrains.kotlinx.dataframe.api.isEmpty
 import org.jetbrains.kotlinx.dataframe.api.isFrameColumn
 import org.jetbrains.kotlinx.dataframe.api.isNA
 import org.jetbrains.kotlinx.dataframe.api.isNumber
+import org.jetbrains.kotlinx.dataframe.api.key
 import org.jetbrains.kotlinx.dataframe.api.keysInto
 import org.jetbrains.kotlinx.dataframe.api.last
 import org.jetbrains.kotlinx.dataframe.api.leftJoin
@@ -2601,7 +2602,7 @@ class DataFrameTests : BaseTest() {
         typed[2]
             .transpose()
             .dropNulls { value }
-            .name
+            .key
             .toList() shouldBe listOf("name", "age", "city")
     }
 

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataRowTests.kt

@@ -10,6 +10,7 @@ import org.jetbrains.kotlinx.dataframe.api.drop
 import org.jetbrains.kotlinx.dataframe.api.dropLast
 import org.jetbrains.kotlinx.dataframe.api.first
 import org.jetbrains.kotlinx.dataframe.api.intoList
+import org.jetbrains.kotlinx.dataframe.api.key
 import org.jetbrains.kotlinx.dataframe.api.mapToColumn
 import org.jetbrains.kotlinx.dataframe.api.merge
 import org.jetbrains.kotlinx.dataframe.api.name
@@ -109,7 +110,7 @@ class DataRowTests : BaseTest() {
     @Test
     fun transposeTo() {
         val df = dataFrameOf("a", "b")(1, 2).first().transposeTo<Int>()
-        df.name.toList() shouldBe listOf("a", "b")
+        df.key.toList() shouldBe listOf("a", "b")
         df.value.toList() shouldBe listOf(1, 2)
     }