Define a client/session object

[chuckwondo]

There have been discussions in various issues about problems that might very well be solved by defining/exposing some sort of "client" or "session" object in the earthaccess API:

• Most recently, in regard to configuring progress bars displayed during downloading: Allow users to disable progress bars #612
• A while ago: Option to use UAT environment #421, however, this helps only for a call to login, not with things that can be done without having to login, such as just searching.

At a minimum, I think we have these requirements:

• Maintain backward compatibility: this would mean that existing code would still work, but under the covers would likely make use of a default client/session object (this would be akin to other libraries, such as requests or boto3, which make use of a default session instance, if no explicit session is created and used)
• Provide client/session-specific configuration: this would allow for configuring various things for the specific client/session, such as showing/hiding progress bars (among other pqdm configs) for downloading, as well as which endpoint we want to use (UAT or PROD/Ops), which would also allow us to simultaneously hit both UAT and Prod with 2 client/session objects (which also came up quite a while back, but I can't find the issue).

What might this look like?

I imagine we could easily do something very similar to what other libraries do, such as requests and boto3, where we would automatically create and use a default client/session object, which would be used automatically by the current top-level API functions.

For users who want to override defaults, we would add a new top-level function for creating a customized client/session instance, and then call methods on the instance rather than calling functions from the top-level. The methods on the instance would be the same names as the top-level functions (and the top-level functions would be modified to simply call the corresponding methods on the default client/session instance).

For example (I'm using the name Client to avoid confusion with Session, which both requests and boto3 use, but of course, the class name is open to "voting", if there's agreement that this work should take place):

class Client:
    def __init__(self, system: System = PROD, *, pqdm_kwargs: PqdmOptions | None = None):
        self.system = system
        self.pqdm_kwargs = {**DEFAULT_PQDM_KWARGS, **{pqdm_kwargs or {}}}
        ...

    def search_data(...): ...

    def search_datasets(...): ...

    def login(...): ...

    def download(...): ...

    ...

DEFAULT_CLIENT: Client | None = None

def get_default_client():
    ...

def search_data(...):
    return get_default_client().search_data(...)

...

Existing user code would not need to change, but if a user wants to configure/customize differently, they can do so:

# existing usage
results = earthaccess.search_data(...)

# plus, newly supported usage
client = earthaccess.Client(pqdm_kwargs={"disable": True})
results = client.search_data(...)

Additionally, if a user wants to hit both UAT and PROD:

prod = earthaccess.Client(PROD)
uat = earthaccess.Client(UAT)

# search both prod and uat and compare different results, for example

[chuckwondo]

@itcarroll, I got an email notification that you replied to this discussion, but for some reason I don't see your reply on github itself, so I'm copying your reply from the email I received (forgive me if anybody sees a duplicate reply):

Nice idea and design!

Would you consider wrapping client creation in with authentication, so that the earthaccess.login output gets the features of your client? Users already know about calling login and there currently isn't any use for its output that I know of, beyond checking its authenticated attribute.

Yes, I would see this as an opportunity to combine/simplify/tidy-up the auth logic as well. There is at least 1 issue that is related, which I believe could be addressed by the use of a client/session object as well: #945

I believe this might help make it all a bit more clear/explicit, which might also help reduce confusion around it all.

[itcarroll]

Sorry for the confusion. Right after I made that post, I remembered you don't need to authenticate to search (and then realized you had pointed that out)! So I added a NVM edit and then deleted. It is a nice idea and design as proposed!

[jhkennedy]

I really like this idea, and I've suggested something similar in the results class discussion #847 (comment) so happy to see it gaining traction!