Kotlin / Kotlin/dataframe

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

Open
#564 0 comments 1 reaction 2 assignees Claimed by @zaleslaw View on GitHub
API
Dominant language
Kotlin
Stars
1.1k
Forks
83
Avg merge
4d 12h
Merged PRs (30d)
30

Description

### 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
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.