Effortless writing #14514
Description
The writing in typeshed is better than most Python projects, and I can clearly see that y'all intentionally put effort into your writing. Hard work is not a substitute, however, for skills, training, and tools.
I’m stuck on an error message, and I’m confident most of you could revise the code and clear the error in just 30 seconds. Then I realized I could revise the error message and clarify its meaning in just 30 seconds if I knew the message's implied details.
The error message, which is essentially irrelevant
* Executing task: cmd /c "call .venv\Scripts\activate.bat && for /F "tokens=1,2 delims=/" %G in ('git diff --cached --name-only --diff-filter=AM') do (tests\runtests.py --run-stubtest %G/%H)"
(.venv) C:\clones\typeshed>(tests\runtests.py --run-stubtest stubs/networkx )
Running pre-commit...
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
check yaml...........................................(no files to check)Skipped
check toml...............................................................Passed
check for merge conflicts................................................Passed
mixed line ending........................................................Passed
check for case conflicts.................................................Passed
Run ruff on stubs, tests and scripts.....................................Passed
Run ruff on the test cases...............................................Passed
black....................................................................Passed
flake8...................................................................Passed
Check hooks apply to the repository..................(no files to check)Skipped
Running check_typeshed_structure.py...
Running Pyright (base configs) for Python 3.10...
11.4.2
Running: C:\Program Files\nodejs\npx.CMD pyright@1.1.403 stubs\networkx --pythonversion 3.10
0 errors, 0 warnings, 0 informations
Running mypy for Python 3.10...
*** Testing Python 3.10 on win32
Testing third-party packages...
testing networkx (285 files)... success
--- success, 285 files checked ---
Running stubtest...
networkx... (76.61 s) fail
**********************************************************************
Commands run:
C:\Users\hunte\AppData\Local\Temp\stubtest-mczbs3f7\Scripts\pip.exe install networkx[]==3.5 mypy==1.16.1 numpy>=1.20 pandas
MYPYPATH=stubs\networkx C:\Users\hunte\AppData\Local\Temp\stubtest-mczbs3f7\Scripts\python.exe -m mypy.stubtest --mypy-config-file C:\Users\hunte\AppData\Local\Temp\tmpqjujhgxi --show-traceback --custom-typeshed-dir . networkx --allowlist stubs\networkx\@tests\stubtest_allowlist.txt
**********************************************************************
Command output:
error: networkx.MultiGraph.get_edge_data is inconsistent, runtime argument "default" has a default value of type None, which is incompatible with stub argument type Union[_Any`-1, _Any`-1]. This is often caused by overloads failing to account for explicitly passing in the default value.
Stub: in file C:\clones\typeshed\stubs\networkx\networkx\__init__.pyi:29
Overload(def [_Any in (Any, None)] (self: networkx.classes.multigraph.MultiGraph[_Node`1], u: _Node`1, v: _Node`1, key: typing.Hashable, default: _Any`-1 =) -> Union[typing.Mapping[builtins.str, Any], _Any`-1], def [_Any in (Any, None)] (self: networkx.classes.multigraph.MultiGraph[_Node`1], u: _Node`1, v: _Node`1, key: None =, default: _Any`-1 =) -> typing.Mapping[typing.Hashable, Union[typing.Mapping[builtins.str, Any], _Any`-1]])
Inferred signature: def (self: networkx.classes.multigraph.MultiGraph[_Node`1], u: _Node`1, v: _Node`1, key: typing.Hashable = ..., default: Union[_Any`-1, _Any`-1] = ...)
Runtime: in file C:\Users\hunte\AppData\Local\Temp\stubtest-mczbs3f7\Lib\site-packages\networkx\classes\multigraph.py:898
def (self, u, v, key=None, default=None)
error: networkx.classes.MultiGraph.get_edge_data is inconsistent, runtime argument "default" has a default value of type None, which is incompatible with stub argument type Union[_Any`-1, _Any`-1]. This is often caused by overloads failing to account for explicitly passing in the default value.
Stub: in file C:\clones\typeshed\stubs\networkx\networkx\classes\__init__.pyi:29
Overload(def [_Any in (Any, None)] (self: networkx.classes.multigraph.MultiGraph[_Node`1], u: _Node`1, v: _Node`1, key: typing.Hashable, default: _Any`-1 =) -> Union[typing.Mapping[builtins.str, Any], _Any`-1], def [_Any in (Any, None)] (self: networkx.classes.multigraph.MultiGraph[_Node`1], u: _Node`1, v: _Node`1, key: None =, default: _Any`-1 =) -> typing.Mapping[typing.Hashable, Union[typing.Mapping[builtins.str, Any], _Any`-1]])
Inferred signature: def (self: networkx.classes.multigraph.MultiGraph[_Node`1], u: _Node`1, v: _Node`1, key: typing.Hashable = ..., default: Union[_Any`-1, _Any`-1] = ...)
Runtime: in file C:\Users\hunte\AppData\Local\Temp\stubtest-mczbs3f7\Lib\site-packages\networkx\classes\multigraph.py:898
def (self, u, v, key=None, default=None)
error: networkx.classes.multigraph.MultiGraph.get_edge_data is inconsistent, runtime argument "default" has a default value of type None, which is incompatible with stub argument type Union[_Any`-1, _Any`-1]. This is often caused by overloads failing to account for explicitly passing in the default value.
Stub: in file C:\clones\typeshed\stubs\networkx\networkx\classes\multigraph.pyi:29
Overload(def [_Any in (Any, None)] (self: networkx.classes.multigraph.MultiGraph[_Node`1], u: _Node`1, v: _Node`1, key: typing.Hashable, default: _Any`-1 =) -> Union[typing.Mapping[builtins.str, Any], _Any`-1], def [_Any in (Any, None)] (self: networkx.classes.multigraph.MultiGraph[_Node`1], u: _Node`1, v: _Node`1, key: None =, default: _Any`-1 =) -> typing.Mapping[typing.Hashable, Union[typing.Mapping[builtins.str, Any], _Any`-1]])
Inferred signature: def (self: networkx.classes.multigraph.MultiGraph[_Node`1], u: _Node`1, v: _Node`1, key: typing.Hashable = ..., default: Union[_Any`-1, _Any`-1] = ...)
Runtime: in file C:\Users\hunte\AppData\Local\Temp\stubtest-mczbs3f7\Lib\site-packages\networkx\classes\multigraph.py:898
def (self, u, v, key=None, default=None)
Found 3 errors (checked 573 modules)
**********************************************************************
Python version: Python 3.12.10 (tags/v3.12.10:0cc8128, Apr 8 2025, 12:21:36) [MSC v.1943 64 bit (AMD64)]
Ran with the following environment:
mypy==1.16.1
mypy_extensions==1.1.0
networkx==3.5
numpy==2.3.2
pandas==2.3.1
pathspec==0.12.1
pip==25.2
python-dateutil==2.9.0.post0
pytz==2025.2
six==1.17.0
typing_extensions==4.14.1
tzdata==2025.2
**********************************************************************
To fix "unused allowlist" errors, remove the corresponding entries from stubs\networkx\@tests\stubtest_allowlist.txt
**********************************************************************
Upstream repository: https://github.com/networkx/networkx
Typeshed source code: https://github.com/python/typeshed/tree/main/stubs/networkx
**********************************************************************
Running Pyright regression tests for Python 3.10...
11.4.2
Running: C:\Program Files\nodejs\npx.CMD pyright@1.1.403 stubs\networkx\@tests\test_cases --pythonversion 3.10 -p pyrightconfig.testcases.json
0 errors, 0 warnings, 0 informations
Running mypy regression tests for Python 3.10...
Running mypy --platform win32 --python-version 3.10 on the test cases for 'networkx'...
Test completed successfully!
--- TEST SUMMARY: One or more tests failed. See above for details. ---
pre-commit Success
Check structure: Success
Pyright: Success
mypy: Success
stubtest: Failed
Pyright regression tests: Success
mypy regression test: Success
* The terminal process "C:\WINDOWS\System32\cmd.exe /d /c "cmd /c "call .venv\Scripts\activate.bat && for /F "tokens=1,2 delims=/" %G in ('git diff --cached --name-only --diff-filter=AM') do (tests\runtests.py --run-stubtest %G/%H)""" terminated with exit code: 1.
* Terminal will be reused by tasks, press any key to close it. I struggle to understand Python documentation
More often than not, I struggle to understand Python documentation, but I am not the source of the problem. On my own, I studied ten computer science textbooks, cover to cover, from the University of Texas computer science curriculum and scored in the 53rd percentile on the Computer Science GRE. I scored 173 on the LSAT, which was higher than the 75th percentile of students admitted to Yale Law School. I worked in IT for nine years and earned 15 certifications.
Less effort and better writing
I firmly believe we can work together to improve the writing in typeshed and reduce the time and energy y'all spend on writing. Way back on 2016 March 19, I wrote this on my Facebook page:
I have decided to share the writing techniques that were taught to me or learned through experience. For now, the new focus of this page will be about how anyone can improve their writing with simple rules, practical techniques, writing references, and software tools.
That idea didn't transform my life (I'm still disabled and homeless), but it supports my claim that I want to make it easier for y'all to write.
I'm not demanding better writing from you. I'm not demanding you do things my way. I'm suggesting that we work together so that the writing is generally better because y'all are using processes that require less effort.