Make the API a little more pythonic, more friendly

[ewjoachim]

Hello,

I was invited by Steeve Marx to create issues for my remarks on the API, so here it is.

This is not a "bug" per se, but a sum of different remarkes that make me not completely convinced by the SDK's API as of today. It's nothing more than my own personnal 2 cents and I don't claim to represent anyone's opinion except my own.

For now, there are still things that are really unnatural when working with the dropbox API with python. The profusion of "everything being made into a class inheriting object" and in the same time, the fact it's not-using lots of classical python constructs really feels as if the whole API was ported from another language...

All the things I've seen so far:

• The APIError that has a reason property which is an *Error class that inherits object : why wouldn't the error class BE the exception itself ? it forces the user to make a complicated construct of:

if isinstance(exc.reason, SomethingError):
    # blabla
elif isinstance(exc.reason, SomethingElseError):
   # blabla

Where the simpler try/except would do it.

• ListFolderResult inherits object and is not iterable. This feels strange. Plus, its entries are not easily sortable. if you want just the Files of just the Folders, you have, again, to filter everything using isinstance. It's not encouraging readable code on our side. A suggestion : why not providing a "walk" method similar to os.walk (but with metadata elements instead of strings ?)
• The fact that, in metadata, you only have the choice between "path_lower" and "name" makes it really a pain to get a properly cased path (e.g. to show the user. We don't want to show them a lowercase path). The fact that there's no easy way to get the "parent" MetaData or the children metadata for a folder makes it all the more complicated. What would be really useful is that when I do a files_list_folder(recursive=True), the SDK would organize the result so that if I find an interesting folder, I can get its (metadata) content. Another thing that would be great : if files_list_folder could provide a generator that would automatically call "continue" when everything has been yielded without having to do it by ourselves.
• When looking at the code, it seems there are a lots of copy/pasted constructs (all the properties for instance, with the something_present attribute being set manually. Some are completely copy-pasted (id for FileMetaData and FolderMetaData). This makes reading the code not an easy task.
• I didn't get into much details and I'm probably wrong but it feels like some constructs could be greatly simplified using **kwargs more often and inheritance/mixin between classes providing similar functionalities. Today, for example, ListSharedFolderResults and ListResults are not related.

[ewjoachim]

(BTW, it's always easy to criticize, and I almost forgot to say that all in all, it's great to have a Python 3 compatible Python SDK, that is also opensource with a permissive license and accepting issues from everyone, and thank you for that.) :+1:

[tomkinsc]

Thank you for explicating what are also my frustrations with the library. It feels java-esque, in an unfortunate way. I am grateful for the work the authors have put into the library, and that it is freely available, but it falls a bit short. The library could really shine if the authors tailor it a bit more to the patterns of Python (and improve the docs!). It is open though, so I suppose improvements are just a pull request away...

[braincore]

Sorry for the delay. We're meaning to address these comments, but we've been in a bit of a rush leading up to our Nov. 4th launch. While our API is now considered "ready for production", the Python SDK (all of them, in fact) is still in beta.

Truthfully, the goal of the first release of the v2 SDK is to set the foundation for an SDK that is always comprehensive and up-to-date with our API. Much of it is auto-generated from a specification language, which was a response to our v1 SDK which was always behind in functionality and had many inconsistencies. Even if the interface isn't the most convenient (though we will strive to make it so), we think that functionality is king.

Re: lower-cased path: Because of complications deep in our system, we actually haven't been able to provide a reliably-cased path even in v1. It was always a "best effort" which threw off apps that really needed it to be the exact case.

Re: list_folder as a generator: This is a good suggestion and something we can implement a helper function for.

Re: errors: Right now, the primary exception to catch is ApiError. The idea is that you look at the docstring for a route like get_metadata, and see that the error type is GetMetadataError. The documentation is a tad broken here, but a path error will be an instance of LookupError. The idea is that there may be a large number of errors and sub-errors, and it would be just as cumbersome to have 10+ exceptions. You can see an example of error handling in our backup-and-restore example.

[rogebrd]

This issue is stale and the SDK has changed numerous times since this post to become more 'Pythonic'