[issue47069] socket._GLOBAL_DEFAULT_TIMEOUT being an object() makes for ugly docstrings, can be better
New submission from FeRD (Frank Dana) : socket._GLOBAL_DEFAULT_TIMEOUT's status as a bare object() instance has been brought up before (bpo-12441). That was reported as a bug, but appeared to stem from developer confusion, so it was correctly closed as "not a bug". At the time @orsenthil defended _GLOBAL_DEFAULT_TIMEOUT's current status quo as: > The _GLOBAL_DEFAULT_TIMEOUT usage is an established pattern with socket > > module. https://github.com/python/cpython/blob/main/Lib/socket.py#L805 I don't disagree with that, but I think it can be improved upon, which is why I'm opening this as an enhancement instead of a bug report. If nothing else, the current implementation of _GLOBAL_DEFAULT_TIMEOUT makes for some really ugly method synopses, both in socket.py and in other classes that make use of it: >>> import socket, urllib.request >>> help(socket.create_connection) Help on function create_connection in module socket: create_connection(address, timeout=, source_address=None) Connect to *address* and return the socket object. >>> help(urllib.request.urlopen) Help on function urlopen in module urllib.request: urlopen(url, data=None, timeout=, *, cafile=None, capath=None, cadefault=False, context=None) Open the URL url, which can be either a string or a Request object. >>> ...Converting socket._GLOBAL_DEFAULT_TIMEOUT from an object() instance to a bare class definition, in the style of an Exception subclass, appears to be semantically equivalent in all cases, but has the advantage that the resulting docstrings become VASTLY more readable: >>> import myedits; import myedits.socket as socket >>> help(socket.create_connection) Help on function create_connection in module myedits.socket: create_connection(address, timeout=, source_address=None) Connect to *address* and return the socket object. >>> import sys; sys.modules['socket'] = myedits.socket >>> import myedits.urllib.request >>> help(myedits.urllib.request.urlopen) urlopen(url, data=None, timeout=, *, cafile=None, capath=None, cadefault=False, context=None) Open the URL url, which can be either a string or a Request object. >>> Unless someone objects, I'd like to open a PR changing the definition of socket._GLOBAL_DEFAULT_TIMEOUT from: _GLOBAL_DEFAULT_TIMEOUT = object() to: class _GLOBAL_DEFAULT_TIMEOUT: pass While leaving everything else the same. AFAICT from testing, that should have no impact on the functionality of socket or its consumers, but improve life for Python developers by making the module more readable and self-documenting. -- components: Library (Lib) messages: 415568 nosy: ferdnyc priority: normal severity: normal status: open title: socket._GLOBAL_DEFAULT_TIMEOUT being an object() makes for ugly docstrings, can be better type: enhancement versions: Python 3.11 ___ Python tracker <https://bugs.python.org/issue47069> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue46279] [docs] Minor information-ordering issue in __main__ doc
FeRD (Frank Dana) added the comment: Readding Tal to the nosy list, since my previous comment was inadvertently accompanied by an eviction! (Sorry about that.) -- nosy: +taleinat ___ Python tracker <https://bugs.python.org/issue46279> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue46279] [docs] Minor information-ordering issue in __main__ doc
FeRD (Frank Dana) added the comment: Maybe, """ This won’t work for __main__.py files in the root directory of a .zip file though. Thus, for consistency, it is usually preferred to place code in other modules. That code can then be invoked from a minimal ``__main__.py``. """ (And then the see-also opens, "See venv for an example of a package with a minimal __main__.py in the standard library." which is a natural extension of the discussion.) @taleinat's suggestion works as well (crossed streams). -- nosy: -taleinat ___ Python tracker <https://bugs.python.org/issue46279> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue46279] [docs] Minor information-ordering issue in __main__ doc
FeRD (Frank Dana) added the comment:
TBH, personally I don't think I'd just reword it with "below". That seems like
the path of least resistance, but then the sentence becomes this:
"""
This won’t work for __main__.py files in the root directory of a .zip file
though. Hence, for consistency, minimal __main__.py like the venv one mentioned
below are preferred.
"""
Doesn't really track. How can you draw conclusions ("Hence...") from something
that hasn't even been discussed yet?
It might actually be better to just drop the mention of venv from that
particular sentence. The see-also text introduces *itself* as an example of
what was just discussed. There's no real reason to bring it up ahead of time,
because the see-also already flows naturally from the previous discussion
without any setup.
--
___
Python tracker
<https://bugs.python.org/issue46279>
___
___
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue46279] [docs] Minor information-ordering issue in __main__ doc
New submission from FeRD (Frank Dana) : The expanded documentation on top-level environments is quite an improvement, but there's one passage that causes some confusion. In the section '__main__.py in Python Packages', towards the end, it reads: """ This won’t work for __main__.py files in the root directory of a .zip file though. Hence, for consistency, minimal __main__.py like the venv one mentioned above are preferred. """ Problem is, that's the first mention of venv anywhere in the document. There's a 'See also:' box right BELOW the sentence in question that references venv and its minimal __main__.py, but it hasn't been introduced yet when that first mention comes along. -- assignee: docs@python components: Documentation messages: 409839 nosy: docs@python, ferdnyc priority: normal severity: normal status: open title: [docs] Minor information-ordering issue in __main__ doc versions: Python 3.11 ___ Python tracker <https://bugs.python.org/issue46279> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
