pydata / pydata/xarray

Clarify difference between `.load()` and `.compute()`

Open
#6,837 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

topic-documentation
Dominant language
Python
Stars
4.2k
Forks
1.4k
Avg merge
2d 15h
Merged PRs (30d)
14

Description

What is your issue?

I just realized that the difference between .load() and .compute() is that .load() operates inplace and .compute() returns a new xarray object.I have 2 suggestions for how this could be clearer:

  1. Docs: the API docs for each method could reference the other.
  2. Code: this might be too big a change, but maybe .load() should not return anything. Consider this example from pandas:
    import pandas as pd
    
    df = pd.DataFrame({"air": []})
    df.rename({"air": "foo"}, axis=1, inplace=True)
    # returns None since df is renamed inplace
    
    this matches the behavior of inplace actions in Python itself like list.append or dict.update. This would be a major breaking change though, and it might be easier to just remove .load() entirely.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the API documentation for .load() and .compute() and compare their documented in-place and return-value behavior. Done means the two method docs cross-reference each other and clearly state the distinction; the proposed breaking API change is separate and needs a maintainer decision.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.