The remote debugging protocol has been generating spurious
vulnerability reports from automated scanners that pattern-match
on "remote access" and "memory operations" without understanding
the privilege model. This section documents the security boundaries
so reporters can self-triage before submitting.
The threat model clarifies three points: attaching requires the
same OS-level privileges as GDB (ptrace, task_for_pid, or
SeDebugPrivilege), crashes caused by reading corrupted target
process memory are not security issues, and a compromised target
process is out of scope. A subsection explains when operators
should use PYTHON_DISABLE_REMOTE_DEBUG for defence-in-depth.
Add a warning in the free-threading extensions howto explaining that
PyObject.ob_mutex is reserved for the critical section API and must not
be locked directly with PyMutex_Lock, as this can cause deadlocks.
Extension authors who need their own lock should add a separate PyMutex
field to their object struct.
Also add an ob_mutex member entry under PyObject in the C API reference
(Doc/c-api/structures.rst) with a cross-reference to the howto.
Co-authored-by: Victor Stinner <vstinner@python.org>
To avoid duplicate content in the Enum HOWTO and
API documentation which is not automatically synced,
the section about supported __dunder__ and _sunder
names is moved from HOWTO to API docs.
See also https://github.com/python/cpython/pull/136791
Although PEP 768 mentions how to disable the mechanism of
remote debugging, it is not documented in the Python docs.
This change adds a note on how to disable remote debugging support
in a Python interpreter to the remote debugging how-to.
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
* gh-140550: PEP 793 reference documentation
Since the PEP calls for soft-deprecation of the existing initialization
function, this reorganizes the relevant docs to put the new way of
doing things first, and de-emphasize the old.
Some bits, like the tutorial, are left out of this patch. (See the
issue for a list.)
Co-authored-by: Éric <merwok@netwok.org>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
* Docs: Move Enum functions and add examples
When the `Enum` functions `_add_alias_` and `_add_value_alias_` were added in de6bca9564, the documentation for them was done under `EnumType` instead of `Enum`.
This change moves them to the docs of the `Enum` class and adds an example for each function.
---------
Co-authored-by: Ethan Furman <ethan@stoneleaf.us>
* - Add an explainer guide (aka HOWTO, not how-to) for asyncio.
* Fix linter errors.
* - Enforce max line length of roughly 79 chars.
- Start sentences on new lines to minimize disruption of diffs.
* Add reference to subinterpreters.
* - Significantly reduce article size. Remove both example sections & "Which concurrency do I want" section.
* Align section-header lengths with section names.
* - Remove reference to deleted section.
* - Fix a variety of rote style guide items like title-alignment, use of ie and $, and so forth.
- Add links to other parts of the docs for keywords and objects like await, coro, task, future, etc.
* - One last title alignment.
* - Style nit.
* - Rework a variety of I statements.
* Lint fix.
* - Firm up commentary on yield from in corotuines.
* Update language comparing await and yield from.
* - Remove await-ing Tasks and futures section
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* - Address comments related to style & writing flow.
* per-thread event loop note.
* Add section describing coroutines roots in generators.
* Phrasing tweak.
* Use asyncio.create_task instead of asyncio.Task
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* small phrasing.
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* phrasing nit.
* style nits
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* phrasing nit
* Fix misnaming of async generator.
* phrasing nits.
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* consistent spacing
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* phrasing nits
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* add conclusion
* nits
* - Variety of style & grammar improvements thanks to ZeroIntensity's comments.
* - Make all directives start with a 3 space indent. Then 4 thereafter.
* - Use :linenos: instead of manually writing the line numbers.
* - Fix label typo for article.
* fix label link.
* Apply suggestions from code review
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* - introduce async-sleep name
* Phrasing
* nit
* ungendered octopus
* teammates
* jobs
* rework fella to penguin
* - remove byline; add seealso
* Change ref from asyncio to use seealso block.
* Remove typehints. Fix indentation in one code example.
* Slight rephrase for clarity.
* Make references point to asyncio. Wrap some long lines.
* - Variety of style/phrasing improvements based on PR feedback.
* phrasing.
* phrasing nit.
* Apply suggestions from code review
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
* nit
* Apply suggestions from code review
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
* fix backticks.
* nits
* nit
* add section on asyncio.run
* title change under the hood.
* modify task coro example.
* howtos article link.
* prefer await without backticks.
* phrasing tweak.
* Rework phrasing around how await tasks pauses and returns control in the await section.
* move code block to beforfe explanation in coroutine under the hood.
* phrasing.
* link to yield from.
* style nits
* nit
* - Modify language re: event-loop cycling endlessly.
- Discuss why await was designed to not yield for coros.
* - Add a note about debug=True on asyncio.run to await coro section.
* clarity nit
* - Add two other references in seealso block.
* nit
* Language simplification
* Apply suggestions from code review
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
* nit
* grammar fix.
* fix
* worker bees
* rework event loop paragraph to significantly deemphasize queues
* remove all references to queue besides the initial analogy.
* add note about garbage collection of tasks
* add practical note re: garbage collection
* phrasing nits
* re arrange note on task gc.
* line wrap nit
* Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Kumar Aditya <kumaraditya@python.org>
* link to debug mode docs.
* readd part2 prefix.
* simplify title.
* fix titles. tihnk I messed this up earlier.
* avoid idiom in title.
* fix titles once agian.
* Apply suggestions from code review
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
* rework task gc example.
* phrasing tweak.
* tewak.
* nit
* nit
* nit
* nit
---------
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Co-authored-by: Kumar Aditya <kumaraditya@python.org>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
The documentation incorrectly stated that generator.close() 'raises' a
GeneratorExit exception. This was misleading because the method doesn't
raise the exception to the caller - it sends the exception internally
to the generator and returns None.
Some curses module-level functions and window methods now raise
a `curses.error` when a call to a C curses function fails:
- Module-level functions: assume_default_colors, baudrate, cbreak,
echo, longname, initscr, nl, raw, termattrs, termname, and unctrl.
- Window methods: addch, addnstr, addstr, border, box, chgat,
getbkgd, inch, insstr, and insnstr.
In addition, `curses.window.refresh` and `curses.window.noutrefresh`
now raise a `TypeError` instead of a `curses.error` when called with an
incorrect number of arguments for pads.
See also ee36db5500 for similar
changes.
