Skip to content

remove docs and deprecating df - cols #1022

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jan 27, 2025
Merged

remove docs and deprecating df - cols #1022

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
c2ef84f
add remove KDocs
AndreiKingsley Jan 21, 2025
e97e986
Merge branch 'master' into remove_docs
AndreiKingsley Jan 21, 2025
fda8adf
deprecate `minus`
AndreiKingsley Jan 21, 2025
ade2d4e
add generated sources
AndreiKingsley Jan 22, 2025
3a9faa2
made DataFrame.minus ERROR to speed up the deprecation cycle. Fixed @…
Jolanrensen Jan 27, 2025
1682813
added @ExcludeFromSources in SelectingColumns.kt
Jolanrensen Jan 27, 2025
4e6753e
fixup! deprecate `minus`
Jolanrensen Jan 27, 2025
e2c0cf7
removed usage of minus in tests
Jolanrensen Jan 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 130 additions & 0 deletions core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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]}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We will probably move this to a @see tag later, but for now it looks good

*/
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
Loading