On 17 November 2016 at 14:45, Chris Angelico <ros...@gmail.com> wrote:
> Personally, when I hit step 6, I search the web. PyPI search is
> exhaustive but not very usefully ranked (for this purpose). Searching
> for a keyword or protocol will give undue weight to a module whose
> name is simply that word, even if that module is terrible,
> unmaintained, etc, etc. Properly-ranked web search results are
> generally more useful in pointing me to the appropriate package, even
> if they're telling me to use something with a very different name.
> (Consider a search for "python http". You'll get httplib/http.client,
> but shortly after that, you get pointed to 'requests'.)
>
> As another bonus, blog posts of that nature will help to explain to
> more experienced devs "why should this matter to me". People who've
> already used requests-oauthlib are unlikely to reach for a new and
> unproven package without a good reason. So give them that reason! :)
Additionally, I look for simple usage examples. When I did search for
OAuth, I got lots of hits for libraries, some even included "how to
add OAuth to your Flask app" examples. But not one showed me how I
should call a web service that uses OAuth from the Python interpreter
prompt using that library.
Contrast the first page of the requests documentation:
>>> import requests
>>> r = requests.get('https://api.github.com/user', auth=('user', 'pass'))
>>> r.status_code
200
>>> r.headers['content-type']
'application/json; charset=utf8'
>>> r.encoding
'utf-8'
>>> r.text
u'{"type":"User"...'
>>> r.json()
{u'private_gists': 419, u'total_private_repos': 77, ...}
With that, I immediately see how to use the code. Something similar
with an OAuth using service would be what I'm looking for.
I'd consider that sort of use case focused documentation as a minimum
for any library that was looking to be included in the stdlib.
I know I've been arguing earlier in this thread that "OAuth may be a
good candidate for the stdlib". Here, what I'm saying is "... but I
don't see any library implementing it that's ready for stdlib
inclusion". While oic may be highly standards-compliant, IMO it's not
ready for stdlib inclusion without user-focused design and
documentation. On the other hand, nor was any other OAuth package I
found via a quick search.
Paul
_______________________________________________
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/
