further clean-up / refactoring thoughts + discussion

[NickleDave]

following up on #1

@nilomr please do comment if I am not capturing your input well

low-level clean-up stuff

• [ ] refactor xenacanto.py into modules?
  • definitely would make sense to put cli into a module, esp. if we plan to modify / extend later
  • get even more granular, e.g. move download function into download module (which gives us the classic Python download.download :joy:
• [ ] remove TODOs from top of xenocanto.py
  • [ ] convert into issues here if we agree they should be actual to-dos
• [ ] add more examples in documentation
• [ ] rename the tqdmm function
  • the name seems to be a way to avoid clobbering the tqdm package but I would suggest a verb like get_pbar or something?
• [ ] use rich for progress bar, like pip?
  • this is definitely not a priority, I just like the pip toolbar

longer-term higher-level re-factoring

each of these can definitely end up being separate issues, but collecting them here. Roughly in order of complexity, from least to most

• [ ] need a simple docs page -- probably a one-pager?

• [ ] represent queries as a dataclass? (or attrs or fastapi)

• [ ] make sure we study stuff that exists in other packages to understand use cases better

  • good examples in warbleR docs: https://cran.r-project.org/web/packages/warbleR/warbleR.pdf#Rfn.query.Rul.xc.1
  • some functionality similar to what's discussed below (query clean-ups) in the scikit-maad module: https://github.com/scikit-maad/scikit-maad/blob/production/maad/util/xeno_canto.py (looks like it was adapted from earlier script according to comments?)
  • scikit-maad docstrings actually look informative; I would do function naming differently though
  • original script that scikit-maad adapts in part from: https://github.com/davipatti/birdbrain/blob/master/bin/search_xeno_canto.py -- some of this is for v1.0 of xeno-canto API though I think? (e.g. "can't specify species")

• [ ] what would a good cli look like?

  • should there be different commands?

    $ xenocanto query
    $ xenocanto query > query.json
    $ xenocanto download --query
    $ xenocanto download -f query.json

• [ ] should we have a class with methods that map directly to API calls?

  • this would allow programmatic use in addition the CLI, e.g. if someone wants to write a script

  >>> xc = xenocanto.XenoCanto()
  >>> query = xc.query('red-winged blackbird')
  >>> xc.download(query=query[:50], dst='./red-winged-blackbird-data')
  ...

• [ ] are there specific queries people want that we could provide?

  • e.g., @nilomr gave the example of "all the songs in a region"
  • lots of noise in .json, could filter for a user basically

[nilomr]

That all sounds good to me - haven't found time to give it any thought or get started with the lower-level stuff yet. I just came across this, I haven't looked at it yet but will leave for future reference:

• scikit-maad // xeno-canto example, source code

[NickleDave]

That all sounds good to me - haven't found time to give it any thought or get started with the lower-level stuff yet. I just came across this, I haven't looked at it yet but will leave for future reference:

* [scikit-maad](https://github.com/scikit-maad/scikit-maad) // xeno-canto [example](https://scikit-maad.github.io/_auto_examples/2_advanced/plot_xenocanto_wookpecker_activities.html#sphx-glr-auto-examples-2-advanced-plot-xenocanto-wookpecker-activities-py), [source code](https://github.com/scikit-maad/scikit-maad/blob/production/maad/util/xeno_canto.py)

Glad we agree :slightly_smiling_face: -- I did link to that library above but I know I put a lot in the issue. I hadn't seen the docs though, that's helpful

[NickleDave]

Yes vignettes like their metadata example are I think exactly what we'd want