API: make filtering the included packages the encouraged behavior - Githubissues

Quansight-Labs / intersphinx_registry

https://pypi.org/project/intersphinx_registry

MIT License

9 stars 4 forks source link

API: make filtering the included packages the encouraged behavior #8

Closed tacaswell closed 1 month ago

tacaswell commented 1 month ago

I think defaulting to expecting a list is good because:

limits needless downloads (it is only 3-4M pre run, but that will add up quickly)
makes it easy to see in conf.py what external links should work

The con is that it is a bit more verbose, but still an improvement over every project maintaining the urls.

bskinn commented 1 month ago

FWIW I'm strongly +1 to requiring this filter, both for avoiding the time and bandwidth of irrelevant downloads, plus aligning better with 'explicit is better than implicit'.

bskinn commented 1 month ago

I could see value in some sort of special all behavior, though, if it were useful for internal testing purposes.

Carreau commented 1 month ago

+1 to the behavior, do you think we want a short but existing deprecation period even if the package is brand new ?

bskinn commented 1 month ago

do you think we want a short but existing deprecation period even if the package is brand new ?

The project is still at v0.0.4 on PyPI, with a couple dozen downloads per day. While it would be strictly correct to deprecate and then change, I vote -0.5 to a deprecation period given the newness and light uptake as yet. But, I vote for emitting a custom-crafted error message when the filter is missing (perhaps with a link to more information, if that makes sense) so that users don't have to search around for the fix.

It's not like it will give wrong behavior or break live code. Some users' docs builds will fail; they'll realize they need to add the config item, and then all should be well.

Carreau commented 1 month ago

Ok, I pushed a suggestion of new behavior, let me know.

tacaswell commented 1 month ago

I'm normally very (very) 👎🏻 on CalVer, but in this case I think it makes sense as the functionality is thin and the thing that will actually change is the data (and it should be something that should be left un-pinned in downstream libraries).

Carreau commented 1 month ago

For calver, let's discuss on #4 there are a few possibilities for calver format.

Carreau commented 1 month ago

I made all keys lowercase (pillow, pypug), and added a test they are all lowercase.

Carreau commented 1 month ago

Ok, let's try that.