content search: R and Py version filter flag improvements

[dbkegley]

Our content search filters --py-version and --r-version use semver to allow users to search for content based on the versions of R and Python in use. The current syntax uses comparators like >=, <=, >, <, and == to specify the filters.

For example --py-version >=2.7.0 would return python content using at least python 2.7.0.

The argument parsing of these flags can cause confusion depending on the user's $SHELL. For example --py-version==2.7.0 will fail to parse because --py-version= is parsed as the flag by our argparsing library, leaving =2.7.0 as the argument = alone is not a valid comparator.

Similarly, bash might interpret the following as a redirect: --py-version=>2.7.0 because of >. To avoid this, the argument needs to be quoted --py-version ">2.7.0"

In short, our use of the characters >, =, < could be a usability issue. We might consider an alternative syntax, for example gt(2.7.0), gte(2.7.0), eq(2.7.0) could replace >2.7.0, >=2.7.0, ==2.7.0. That's just an example, I welcome other suggestions here.

@kellobri @colearendt @aronatkins we would appreciate your thoughts on this. Is this something we should address in our docs to unblock our release or should we revisit this command now (to avoid confusion later)

This was noted by @kgartland-rstudio during our QA for the next release

[aronatkins]

I'm OK requiring quoting for certain comparison syntaxes. Parentheses can also cause problems, depending on the shell.

We could have = be short-hand to == and also let the lack of a comparison operator imply ==, meaning the following would all be identical:

• --py-version=2.7.0, or --py-version="2.7.0"
• --py-version==2.7.0, or --py-version="=2.7.0"
• --py-version===2.7.0, or --py-version="==2.7.0"

How would someone say: Show me all content using R-4.0.x on a server that uses R-3.6.x, R-4.0.x, and R-4.1.x? How rich are the comparisons allowed?

If folks are unhappy with the comparison options that are available, they could always produce JSON and do their own filtering. We're approaching the edge of what we should do in the tool versus lean on other tools (e.g. jq).

[dbkegley]

These flags are also the sole reason we added the semver dependency. It's a relatively complex part of the codebase, frankly. I'm also open to removing them entirely and replacing that section of the docs with comparable jq commands.

How would someone say: Show me all content using R-4.0.x on a server that uses R-3.6.x, R-4.0.x, and R-4.1.x? How rich are the comparisons allowed?

The version filters allow multiple and are combined with an AND implicitly so to accomplish this you would need to provide --r-version ">=4.0.0" --r-version "<4.1.0"

[mmarchetti]

pip already has to deal with the shell implications of these kinds of characters, and the usual solution is just to quote them.

The = getting eaten by the argument parser is unfortunate, and we probably need to handle that case.

Also if there's interest in simplifying / dropping a dependency, the packaging package (which is used by setuptools so it is everywhere) supports those types of spec comparisons: https://packaging.pypa.io/en/latest/specifiers.html