Skip to content

Unify column accessor APIs (column vs col DSL) before 1.0 #564

Description

@Jolanrensen

Problem

There are multiple ways to create column accessors:

  • constructors: column(), columnGroup()
  • DSL: col(), colGroup(), ""<>, ""[]

These APIs overlap in functionality but differ in syntax and behavior.

As a result:

  • API is inconsistent
  • users have multiple ways to do the same thing
  • discoverability and learning are harder

Design question

How should column accessor APIs be unified?

Options:

  • keep one approach and deprecate the other
  • keep both but make them behave identically
  • standardize naming and usage across all variants

Expected

Define a single, consistent model for column accessors.

Acceptance criteria

  • Decision made on supported accessor APIs
  • Redundant or inconsistent variants are:
    • removed, or
    • aligned to identical behavior
  • Naming and usage are consistent across API
  • Examples and documentation use the same approach

Motivation

Column access is a core part of the DSL.

Having multiple overlapping APIs creates confusion and increases long-term maintenance cost.

This should be resolved before 1.0 to avoid breaking changes later.

initial comment from @Jolanrensen

Especially in the [Columns Selection DSL](https://github.com/Kotlin/dataframe/pull/372) the library allows the user to create column accessors using either the constructors `column()`, `columnGroup()`, etc. from [constructors.kt](https://github.com/Kotlin/dataframe/blob/master/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/constructors.kt) as well as `col()`, `colGroup()`, ""<>(), ""[""], etc. (now with runtime checks) from the selection DSL [ColumnSelectionDsl.kt](https://github.com/Kotlin/dataframe/blob/continued-columnsselectiondsl/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnSelectionDsl.kt), [col.kt](https://github.com/Kotlin/dataframe/blob/continued-columnsselectiondsl/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/col.kt), and [colGroup.kt](https://github.com/Kotlin/dataframe/blob/continued-columnsselectiondsl/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/colGroup.kt).

Having both is confusing. We should keep one of the two variants, or have them be exactly the same. Column shortcuts like `""<>()` should be available library-wide too I think, as it's common enough.

Can be handled after https://github.com/Kotlin/dataframe/pull/372

Metadata

Metadata

Labels

APIIf it touches our API

Type

No type

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions