add convenience functions for common operations

[7yl4r]

To maximize usability, I have suggested before [ref] that we wrap the (minor) complexity of query-building in some "convenience" functions. To this end I suggest we create and document the following:

1. pyobis.occurrences.search() : search for taxa using geometry, datetimes, and taxa names.

Are there other very common operations that should be promoted for use by non-technical users?

[ayushanand18]

I agree with your opinion to minimize the complexity in use especially for the most used functions. Should we mimic something like this to make it easier?

Returning an object as a response and with all its properties seems very much natural to me since the end user would want to access everything about a query from a single object. We can uniformize this approach across the whole package.

[7yl4r]

Even just the concept of "objects" and attributes can be confusing for beginners. I think many come to coding by imagining calling a function is like clicking a button in a GUI. One line function gets the data, or one line creates a plot. Although, perhaps data = taxa.search(scientificname="mola mola").execute() would be simple enough?

@MathewBiddle and I were chatting about this earlier. I am curious to hear perspectives from non-coders on this.

[ayushanand18]

Although, perhaps data = taxa.search(scientificname="mola mola").execute() would be simple enough?

I think this is simple, good and easy to follow.

[MathewBiddle]

just my 2 cents. I would expect taxa.search(scientificname="mola mola") to actually do the searching. From what I understand at this point is .search() just builds what the search will be, then you need to execute it. That's confusing to me.

[ayushanand18]

just my 2 cents. I would expect taxa.search(scientificname="mola mola") to actually do the searching. From what I understand at this point is .search() just builds what the search will be, then you need to execute it. That's confusing to me.

We tried to separate query building from query execution for some reasons. One of them being the high turn-around time of execution. While we implemented methods like get_api_url() or get_mapper_url() to improve cross-platform functionality, this high turn-around time could be a hiccup. I strongly agree with your opinion that it increases complexity, but it was a trade-off between simplicity and time. And we chose the latter. Now, I'm putting efforts to reduce this high turn-around time.

But we are eager to adopt changes. Please suggest.

[ayushanand18]

Since we could see a significant improvement in time from this thread, I think we can add a query parameter - nofetch. If nofetch is True then we just build the query, or else if nofetch is False we execute the query simultaneously as we build it. How does that sound?

Eg.

# Method 1:
q1 = taxa.search(scientificname="Mola mola", nofetch = True) # does not return data and needs to be executed
# data can be accessed as 
data = q1.execute() # returns the data
# data can also be accessed as, (once executed, it gets stored as a property of the object)
q1.data

# Method 2: or we can do simply
q2 = taxa.search(scientificname="Mola mola", nofetch = False) # fetches the data and also returns the whole object
q2.data # data can be accessed from this