tamnd / tamnd/firepanda

to_datetime answers a Series where pandas answers a DatetimeIndex

Open Beginner friendly
#354 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Mojo
Stars
1
Forks
0
Avg merge
1h 31m
Merged PRs (30d)
640

Description

`pandas.to_datetime` hands back a `DatetimeIndex` when it is given a list and a `Series` when it is given a `Series`. `firepanda.to_datetime` hands back a `Series` for both. This is the first difference a caller meets, on the first line they write, so it is worth being explicit about why it is that way and what would have to be true to change it.

## Why a Series

firepanda's `Index` is a labels object. It has `get_loc`, `get_indexer`, `is_monotonic_increasing`, `take`, `equals` and the set operations, and none of the calendar members. Answering an `Index` here would give a caller a name that resolves and then has nothing on it, which is worse than a name that resolves to something honest, and it would take `s.dt` away from them since that lives on the series.

Nearly every use of `to_datetime` reaches for `.dt` next, or puts the answer in a frame, and both of those work on a `Series`. The one thing a `DatetimeIndex` is for that a `Series` is not is being an index, and firepanda has no datetime index.

## What it costs

Three things a caller can see.

`type(pd.to_datetime([...]))` is `DatetimeIndex` and `type(fp.to_datetime([...]))` is `Series`. Any code that checks the type sees the difference, and so does any code that calls a `DatetimeIndex` method on the answer.

`pd.to_datetime([...])[0]` is a `Timestamp` and the firepanda answer indexes as a series does, which today is a separate gap since `Series.__getitem__` is not there yet.

`df.index = pd.to_datetime(df["when"])` is the thing this shape exists for in pandas programs, and it needs both a datetime index and an assignable `index`, neither of which exists here. That is issue #256 for the assignment half.

## What would change it

A `DatetimeIndex` type with the calendar surface on it, which is a real amount of work and is only worth doing once there is a reason to hold instants as an index rather than as a column. Nothing on the conformance board asks for one yet. When something does, the change is compatible in the direction that matters: a caller who wrote `to_datetime(...)` and used it as a column would have to be given the column back, so this would be a break rather than an addition, and it should be decided before the surface is wide enough that the break is expensive.

Filed so the decision is on the record rather than discovered. It is asserted as a decision in `python/tests/test_to_datetime.py` so that a future change to it fails a test rather than passes quietly.

Contributor guide

Open the contributing guide

Research direction

Start with python/tests/test_to_datetime.py, where the Series return decision is asserted. Read the surrounding to_datetime tests and the issue rationale, then ensure the documented behavior and regression assertion remain aligned; done means the chosen Series behavior is explicit and protected from silent change.

Written by the indexing model from the issue text.

Assessment

Tech stack
pandas
Domain
data
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.