Skip to content

Commit

Permalink
Merge pull request #1022 from Kotlin/remove_docs
Browse files Browse the repository at this point in the history 
`remove` docs and deprecating `df - cols`
  • Loading branch information
@Jolanrensen
Jolanrensen authored Jan 27, 2025
2 parents 33b5855 + e2c0cf7 commit 34bc798
Show file tree
Hide file tree
Showing 12 changed files with 231 additions and 53 deletions.
130 changes: 130 additions & 0 deletions core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,38 +6,168 @@ import org.jetbrains.kotlinx.dataframe.DataFrame
import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload
import org.jetbrains.kotlinx.dataframe.annotations.Interpretable
import org.jetbrains.kotlinx.dataframe.annotations.Refine
import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
import org.jetbrains.kotlinx.dataframe.columns.toColumnSet
import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls.Select
import org.jetbrains.kotlinx.dataframe.impl.api.removeImpl
import org.jetbrains.kotlinx.dataframe.util.MINUS
import org.jetbrains.kotlinx.dataframe.util.MINUS_REPLACE
import kotlin.reflect.KProperty

// region DataFrame

// region remove

/**
* ## The Remove Operation
*
* Removes the specified [columns] from the original [DataFrame] and returns a new [DataFrame] without them.
*
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
*
* See [Selecting Columns][Select.SelectSelectingOptions].
*
* For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
*/
internal interface Remove

/**
* ## The Remove Operation
*
* Removes the specified [columns][org.jetbrains.kotlinx.dataframe.columns] from the original [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] and returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] without them.
*
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
*
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
*
* For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
* ### This Remove Overload
* Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl].
* (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]).
*
* This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda,
* which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and
* expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]).
* This is an entity formed by calling any (combination) of the functions
* in the DSL that is or can be resolved into one or more columns.
*
* #### NOTE:
* While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]
* in this DSL directly with any function, they are NOT valid return types for the
* [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance
* with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col].
*
* ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar]
*
*     
*
* [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html)
*
* #### For example:
*
* `df.`[remove][org.jetbrains.kotlinx.dataframe.api.remove]` { length `[and][org.jetbrains.kotlinx.dataframe.api.AndColumnsSelectionDsl.and]` age }`
*
* `df.`[remove][org.jetbrains.kotlinx.dataframe.api.remove]` { `[cols][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.cols]`(1..5) }`
*
* `df.`[remove][org.jetbrains.kotlinx.dataframe.api.remove]` { `[colsOf][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>() }`
*
*
* @param [columns] The [Columns Selector][ColumnsSelector] used to remove the columns of this [DataFrame].
*/
@Refine
@Interpretable("Remove0")
public fun <T> DataFrame<T>.remove(columns: ColumnsSelector<T, *>): DataFrame<T> =
removeImpl(allowMissingColumns = true, columns = columns).df

/**
* ## The Remove Operation
*
* Removes the specified [columns][org.jetbrains.kotlinx.dataframe.columns] from the original [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] and returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] without them.
*
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
*
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
*
* For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
* ### This Remove Overload
* Select columns using their [column names][String]
* ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]).
*
* #### For example:
*
* `df.`[remove][org.jetbrains.kotlinx.dataframe.api.remove]`("length", "age")`
*
* @param [columns] The [Column Names][String] used to remove the columns of this [DataFrame].
*/
public fun <T> DataFrame<T>.remove(vararg columns: String): DataFrame<T> = remove { columns.toColumnSet() }

/**
* ## The Remove Operation
*
* Removes the specified [columns][org.jetbrains.kotlinx.dataframe.columns] from the original [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] and returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] without them.
*
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
*
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
*
* For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
* ### This Remove Overload
* Select columns using [column accessors][org.jetbrains.kotlinx.dataframe.columns.ColumnReference]
* ([Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]).
*
* #### For example:
*
* `val length by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()`
*
* `val age by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()`
*
* `df.`[remove][org.jetbrains.kotlinx.dataframe.api.remove]`(length, age)`
*
* @param [columns] The [Column Accessors][ColumnReference] used to remove the columns of this [DataFrame].
*/
@AccessApiOverload
public fun <T> DataFrame<T>.remove(vararg columns: AnyColumnReference): DataFrame<T> = remove { columns.toColumnSet() }

/**
* ## The Remove Operation
*
* Removes the specified [columns][org.jetbrains.kotlinx.dataframe.columns] from the original [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] and returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] without them.
*
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
*
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
*
* For more information: [See `remove` on the documentation website.](https://kotlin.github.io/dataframe/remove.html)
* ### This Remove Overload
* Select columns using [KProperties][KProperty] ([KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]).
*
* #### For example:
* ```kotlin
* data class Person(val length: Double, val age: Double)
* ```
*
* `df.`[remove][org.jetbrains.kotlinx.dataframe.api.remove]`(Person::length, Person::age)`
*
* @param [columns] The [KProperties][KProperty] used to remove the columns of this [DataFrame].
*/
@AccessApiOverload
public fun <T> DataFrame<T>.remove(vararg columns: KProperty<*>): DataFrame<T> = remove { columns.toColumnSet() }

// endregion

// region minus

@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
public infix operator fun <T> DataFrame<T>.minus(columns: ColumnsSelector<T, *>): DataFrame<T> = remove(columns)

@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
public infix operator fun <T> DataFrame<T>.minus(column: String): DataFrame<T> = remove(column)

@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
@AccessApiOverload
public infix operator fun <T> DataFrame<T>.minus(column: AnyColumnReference): DataFrame<T> = remove(column)

@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
@AccessApiOverload
public infix operator fun <T> DataFrame<T>.minus(columns: KProperty<*>): DataFrame<T> = remove(columns)

Expand Down
10 changes: 10 additions & 0 deletions core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/select.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ import kotlin.reflect.KProperty
*
* Returns a new [DataFrame] with only the columns selected by [columns].
*
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
*
* See [Selecting Columns][SelectSelectingOptions].
*
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
Expand Down Expand Up @@ -108,6 +110,8 @@ internal interface Select {
*
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns].
*
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
*
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
*
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
Expand Down Expand Up @@ -153,6 +157,8 @@ public fun <T> DataFrame<T>.select(columns: ColumnsSelector<T, *>): DataFrame<T>
*
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns].
*
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
*
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
*
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
Expand All @@ -176,6 +182,8 @@ public fun <T> DataFrame<T>.select(vararg columns: KProperty<*>): DataFrame<T> =
*
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns].
*
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
*
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
*
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
Expand All @@ -196,6 +204,8 @@ public fun <T> DataFrame<T>.select(vararg columns: String): DataFrame<T> = selec
*
* Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with only the columns selected by [columns].
*
* This operation can also be used on [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
*
* See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions].
*
* For more information: [See `select` on the documentation website.](https://kotlin.github.io/dataframe/select.html)
Expand Down
26 changes: 0 additions & 26 deletions ...sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,6 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver
import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
import kotlin.reflect.KProperty

/** [Selecting Columns][SelectingColumns] */
internal interface SelectingColumnsLink

/**
* ## Selecting Columns
* Selecting columns for various operations (including but not limited to
Expand Down Expand Up @@ -89,16 +86,8 @@ internal interface SelectingColumnsLink
*/
internal interface SelectingColumns {

/*
* The key for a @set that will define the operation name for the examples below.
* Make sure to [alias][your examples].
*/
interface OPERATION

// Using <code>` notation to not create double `` when including

interface SetDefaultOperationArg

/**
* Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl].
* (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]).
Expand Down Expand Up @@ -158,9 +147,6 @@ internal interface SelectingColumns {
interface WithExample
}

/** [Columns Selection DSL][Dsl.WithExample] */
interface DslLink

/**
* Select or express a single column using the Column Selection DSL.
* (Any [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]).
Expand Down Expand Up @@ -217,9 +203,6 @@ internal interface SelectingColumns {
interface WithExample
}

/** [Column Selection DSL][DslSingle.WithExample] */
interface DslSingleLink

/**
* Select columns using their [column names][String]
* ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]).
Expand All @@ -238,9 +221,6 @@ internal interface SelectingColumns {
interface WithExample
}

/** [Column names][ColumnNames.WithExample] */
interface ColumnNamesLink

/**
* Select columns using [column accessors][ColumnReference]
* ([Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]).
Expand All @@ -263,9 +243,6 @@ internal interface SelectingColumns {
interface WithExample
}

/** [Column references][ColumnAccessors.WithExample] */
interface ColumnAccessorsLink

/** Select columns using [KProperties][KProperty] ([KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]). */
interface KProperties {

Expand All @@ -282,7 +259,4 @@ internal interface SelectingColumns {
*/
interface WithExample
}

/** [KProperties][KProperties.WithExample] */
interface KPropertiesLink
}
3 changes: 3 additions & 0 deletions ...rated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,9 @@ internal const val IS_URL = "This function is replaced by `isUrl()`. $MESSAGE_0_
internal const val IS_URL_REPLACE = "isUrl(path)"
internal const val IS_URL_IMPORT = "org.jetbrains.kotlinx.dataframe.io.isUrl"

internal const val MINUS = "This minus overload will be removed in favor of `remove`. $MESSAGE_0_16"
internal const val MINUS_REPLACE = "this.remove(columns)"

// endregion

// region WARNING in 0.16, ERROR in 0.17
Expand Down
55 changes: 55 additions & 0 deletions core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,38 +6,93 @@ import org.jetbrains.kotlinx.dataframe.DataFrame
import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload
import org.jetbrains.kotlinx.dataframe.annotations.Interpretable
import org.jetbrains.kotlinx.dataframe.annotations.Refine
import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
import org.jetbrains.kotlinx.dataframe.columns.toColumnSet
import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls
import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls.Select
import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources
import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns
import org.jetbrains.kotlinx.dataframe.impl.api.removeImpl
import org.jetbrains.kotlinx.dataframe.util.MINUS
import org.jetbrains.kotlinx.dataframe.util.MINUS_REPLACE
import kotlin.reflect.KProperty

// region DataFrame

// region remove

/**
* ## The Remove Operation
*
* Removes the specified [columns] from the original [DataFrame] and returns a new [DataFrame] without them.
*
* @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]
*
* See [Selecting Columns][Select.SelectSelectingOptions].
*
* For more information: {@include [DocumentationUrls.Remove]}
*/
internal interface Remove

/** {@set [SelectingColumns.OPERATION] [remove][remove]} */
@ExcludeFromSources
private interface SetRemoveOperationArg

/**
* {@include [Remove]}
* ### This Remove Overload
*/
@ExcludeFromSources
private interface CommonRemoveDocs

/**
* @include [CommonRemoveDocs]
* @include [SelectingColumns.Dsl.WithExample] {@include [SetRemoveOperationArg]}
* @param [columns] The [Columns Selector][ColumnsSelector] used to remove the columns of this [DataFrame].
*/
@Refine
@Interpretable("Remove0")
public fun <T> DataFrame<T>.remove(columns: ColumnsSelector<T, *>): DataFrame<T> =
removeImpl(allowMissingColumns = true, columns = columns).df

/**
* @include [CommonRemoveDocs]
* @include [SelectingColumns.ColumnNames.WithExample] {@include [SetRemoveOperationArg]}
* @param [columns] The [Column Names][String] used to remove the columns of this [DataFrame].
*/
public fun <T> DataFrame<T>.remove(vararg columns: String): DataFrame<T> = remove { columns.toColumnSet() }

/**
* @include [CommonRemoveDocs]
* @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetRemoveOperationArg]}
* @param [columns] The [Column Accessors][ColumnReference] used to remove the columns of this [DataFrame].
*/
@AccessApiOverload
public fun <T> DataFrame<T>.remove(vararg columns: AnyColumnReference): DataFrame<T> = remove { columns.toColumnSet() }

/**
* @include [CommonRemoveDocs]
* @include [SelectingColumns.KProperties.WithExample] {@include [SetRemoveOperationArg]}
* @param [columns] The [KProperties][KProperty] used to remove the columns of this [DataFrame].
*/
@AccessApiOverload
public fun <T> DataFrame<T>.remove(vararg columns: KProperty<*>): DataFrame<T> = remove { columns.toColumnSet() }

// endregion

// region minus

@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
public infix operator fun <T> DataFrame<T>.minus(columns: ColumnsSelector<T, *>): DataFrame<T> = remove(columns)

@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
public infix operator fun <T> DataFrame<T>.minus(column: String): DataFrame<T> = remove(column)

@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
@AccessApiOverload
public infix operator fun <T> DataFrame<T>.minus(column: AnyColumnReference): DataFrame<T> = remove(column)

@Deprecated(MINUS, ReplaceWith(MINUS_REPLACE), DeprecationLevel.ERROR)
@AccessApiOverload
public infix operator fun <T> DataFrame<T>.minus(columns: KProperty<*>): DataFrame<T> = remove(columns)

Expand Down
Loading

0 comments on commit 34bc798

Please sign in to comment.