sopel-irc / sopel

:robot::speech_balloon: An easy-to-use and highly extensible IRC Bot framework. Formerly Willie.
https://sopel.chat
Other
950 stars 405 forks source link

docs: add docstring to library root module #2494

Closed SnoopJ closed 12 months ago

SnoopJ commented 1 year ago

Description

This PR fixes #2493 by adding a module-level docstring to sopel/__init__.py. I just copied the first two sentences from https://sopel.chat

Checklist

SnoopJ commented 1 year ago

And actually, digging further into this, the issue is no longer actually present after Python 3.7, when PEP 538 was implemented to coerce the C locale to UTF-8. I believe we could remove the restriction to use only ASCII text in that module, and the associated warning might be superfluous now as well. On the other hand, the LC_ALL setting can still influence the default encoding used for files, stdio, and pipes, so maybe it would be wise to leave the warning about the legacy locale until PEP 686 makes that problem go away. We could drop the "Python 3 [does] stupid things" bit, though :sweat_smile:

I'll leave that out of this PR unless y'all agree that they can go, but the default behavior since 3.7 is to coerce these problematic locales to UTF-8, so the problem just doesn't exist in versions we support now anyway.

SnoopJ commented 1 year ago

Done. I preserved the warning about non-UTF-8 locale but softened the language of it a bit. I'm not really sure it's a concern anymore with the changes that happened since Python 3.7, but I'm not confident enough to remove it entirely for the handful of users who will have a locale that is not using UTF-8 and is not coerced to same.