to_datetime answers a Series where pandas answers a DatetimeIndex
- 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
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