Return a Results class from search and query methods

[mfisher87]

Description

Left to do:

• Make the Results class iterable
• Remove demo notebooks
• Convert TODO comments to issues, clean up those comments
• Add a unit test (no actual query) for to_gdf

---

"Ready for review" checklist

• Place this Pull Request (PR) in draft until it is ready for review (see below)
• Please review our Pull Request Guide
• Mark "ready for review" after following instructions in the guide

Merge checklist

• PR title is descriptive
• PR body contains links to related and resolved issues (e.g. closes #1)
• If needed, CHANGELOG.md updated
• If needed, docs and/or README.md updated
• If needed, unit tests added (unsure how? see below!)
• All checks passing (tip: comment pre-commit.ci autofix if pre-commit is failing)
• At least one approval

Need help? We welcome contributions at every experience level. You don't have to
write tests alone — open your PR and ask for help. It's also fine to let GitHub run tests
for you, via Continuous Integration (CI),
instead of running them locally. If anything fails and you're not sure why, just
mention @earthaccess-dev/maintainers in a comment and we'll work with you!

---

📚 Documentation preview 📚: https://earthaccess--1298.org.readthedocs.build/en/1298/

[github-actions]

👈 Launch a binder notebook on this branch for commit 75fadd9

I will automatically update this comment whenever this PR is modified

👈 Launch a binder notebook on this branch for commit eb932d5

👈 Launch a binder notebook on this branch for commit 78dcc49

👈 Launch a binder notebook on this branch for commit 6b3f8cc

👈 Launch a binder notebook on this branch for commit b4a7089

👈 Launch a binder notebook on this branch for commit 9c4e96c

👈 Launch a binder notebook on this branch for commit f3d3c2d

👈 Launch a binder notebook on this branch for commit 5e8e7ed

👈 Launch a binder notebook on this branch for commit b7b231f

👈 Launch a binder notebook on this branch for commit dff6214

👈 Launch a binder notebook on this branch for commit 2cde854

👈 Launch a binder notebook on this branch for commit 4f26870

👈 Launch a binder notebook on this branch for commit 34e3ca2

👈 Launch a binder notebook on this branch for commit 06b3544

👈 Launch a binder notebook on this branch for commit 52a142d

[trey-stafford]

Discussed during earthaccess community call today:

• Subclassing list isn't a great idea. It provides opportunities for mutating the granule/collections in the list without updates to the corresponding query class.
• We agreed that we should create a base Results class that GranuleResults and CollectionResults can subclass. Making two separate containers for the different results types allows for e.g., isinstance checks against specific collection types.
• The results should be immutable
• We would like to support lazy loading of results, but this is also in conflict with our desire to provide e.g., to_gdf, which would require materializing the results. Materializing the results on one iteration can "wipe out" the results, preventing subsequent iterations. How do we present results to users in a way that they can easily iterate over multiple times lazily? Should we support methods that force materialization?
• We discussed how to_gdf should work. Ideally we don't have column names that are the full CMR representation, but instead show readable column names.

[jhkennedy]

Sorry I couldn't make it to this breakout discussion today -- got totally engrossed in the plugin discussion.

We would like to support lazy loading of results, but this is also in conflict with our desire to provide e.g., to_gdf, which would require materializing the results. Materializing the results on one iteration can "wipe out" the results, preventing subsequent iterations. How do we present results to users in a way that they can easily iterate over multiple times lazily? Should we support methods that force materialization?

We started this with the intention of moving towards a more object-oriented API (#1250 and described in the "what's next" section of demo_new.ipynb). So, I don't think the results class should be "lazy" or directly invoke any searches -- that should be the responsibility of the search client. The client can yield results lazily or return the full set of results, but each materialization should be different results objects. That does imply some additional methods (e.g., equality, combining, etc.) that come with the list class.

Note: we included the query parameters and options for provenance, but the expectation is that they'd be used by the client when doing searches. That part, I think, is a bit clunky still; we kicked around a full provenance type object but didn't settle on anything.

Subclassing list isn't a great idea. It provides opportunities for mutating the granule/collections in the list without updates to the corresponding query class.

This is addressed by my comments above. The benefit of sub-classing list is that it's the least breaking change for eathaccess (it already just returns a list).

The results should be immutable

I could be convinced of this, but I'm not sure it's necessary. Generally, I want user's to be able to use the results -- inculding combining multiple searches into one, etc. That all can be done with an imutable object, so I don't think they are contradictory, but I'd need to think more about the tradeoffs between the two.

We agreed that we should create a base Results class that GranuleResults and CollectionResults can subclass

makes sense to me.

We discussed how to_gdf should work. Ideally we don't have column names that are the full CMR representation, but instead show readable column names.

Yes, human-readable column names would be ideal, but maybe not necessary for a MVP.

---

@mfisher87 what do you think?