Don't mention an import function > Use python-dwca-reader instead

[peterdesmet]

The documentation currently mentions a download_import function at https://github.com/sckott/pygbif/blob/beb3a42c837c71cafb1e2d5808f968fe0d44c5ee/pygbif/occurrences/download.py#L363. That function does not exist for the moment.

I assume this function would be able to open and read a GBIF download file? As was already suggested in the GBIF api-users email thread, I would also strongly suggest to use @niconoe's https://github.com/BelgianBiodiversityPlatform/python-dwca-reader, which has the very specific scope to read DwC-A (source ones and GBIF downloads). In fact, I would not even include the functionality to read such files in pygbif, but keep the scope of this package to “interact with GBIF services”.

So, I have updated the documentation to reference the python-dwca-reader instead of the non-existing download_import function. I’ve also rephrased some of the documentation, e.g. it no longer mentions a download speed, which really depends on your network connection.

[coveralls]

Coverage remained the same at 71.279% when pulling dd899d8 on stijnvanhoey:no-import into ec2a7af on sckott:master.

[niconoe]

It might also be interesting to produce some tutorial/cookbook that shows a complete example of:

• searching data and triggering a download (using pygbif)
• downloading the resulting file, once ready (using something like requests, maybe?)
• accessing the data using python-dwca-reader

So we keep the advantage of having well separated packages (each do one thing, but do it well), but a new user also as a complete, working example he/she can start from.

I'm also willing to help for that, if there's interest (after July 1st)

[peterdesmet]

@niconoe, that would be great. FYI, the second step (download resulting file), can be done with pygbif.

[stijnvanhoey]

I like the idea of providing some cookbook as suggested by @niconoe. A jupyter notebook would be a perfect environment to create such a cookbook. All three listed steps are already provided by either pygbif or dwca-reader:

• searching data -> exploration using different pygbif functions
• triggering a download: pygbif download function or with the GbifDownload class
• downloading the file: pygbif download_get function
• accessing the file: python-dwca-reader

[niconoe]

Thanks @peterdesmet, I wasn't sure about this second step!

[peterdesmet]

Such notebooks could actually be added to https://github.com/sckott/pygbif/tree/master/demos, with one for each module:

• occurrences
• registry
• species

[sckott]

Thanks!

The documentation currently mentions a download_import function ...

Right, sorry, mentioned it before creating it :)

I assume this function would be able to open and read a GBIF download file?

right, that was the plan, but sounds good to not include that functionality in this library

So, I have updated the documentation

great, thanks!

[sckott]

open a new issue for the cookbook(s)?