https://github.com/python/cpython/commit/ff7266efd0ef6b42dad30c9c0d210f843cc... commit: ff7266efd0ef6b42dad30c9c0d210f843cc44f39 branch: 3.8 author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> committer: scoder <stefan_ml@behnel.de> date: 2021-04-28T17:11:53+02:00 summary: bpo-43959: clarify the documentation of the PyContextVar C-API (GH-25671) (GH-25690) (cherry picked from commit 4c49be766897968e509c41397e0e624c25b1675d) files: A Misc/NEWS.d/next/Documentation/2021-04-27-22-22-22.bpo-43959.n2261q.rst M Doc/c-api/contextvars.rst diff --git a/Doc/c-api/contextvars.rst b/Doc/c-api/contextvars.rst index 38256a3b0f2a06..314c8b7847e898 100644 --- a/Doc/c-api/contextvars.rst +++ b/Doc/c-api/contextvars.rst @@ -112,9 +112,9 @@ Context variable functions: .. c:function:: PyObject *PyContextVar_New(const char *name, PyObject *def) Create a new ``ContextVar`` object. The *name* parameter is used - for introspection and debug purposes. The *def* parameter may optionally - specify the default value for the context variable. If an error has - occurred, this function returns ``NULL``. + for introspection and debug purposes. The *def* parameter specifies + a default value for the context variable, or ``NULL`` for no default. + If an error has occurred, this function returns ``NULL``. .. c:function:: int PyContextVar_Get(PyObject *var, PyObject *default_value, PyObject **value) @@ -129,13 +129,12 @@ Context variable functions: - the default value of *var*, if not ``NULL``; - ``NULL`` - If the value was found, the function will create a new reference to it. + Except for ``NULL``, the function returns a new reference. .. c:function:: PyObject *PyContextVar_Set(PyObject *var, PyObject *value) - Set the value of *var* to *value* in the current context. Returns a - pointer to a :c:type:`PyObject` object, or ``NULL`` if an error - has occurred. + Set the value of *var* to *value* in the current context. Returns + a new token object for this change, or ``NULL`` if an error has occurred. .. c:function:: int PyContextVar_Reset(PyObject *var, PyObject *token) diff --git a/Misc/NEWS.d/next/Documentation/2021-04-27-22-22-22.bpo-43959.n2261q.rst b/Misc/NEWS.d/next/Documentation/2021-04-27-22-22-22.bpo-43959.n2261q.rst new file mode 100644 index 00000000000000..ba23ffd577b3d4 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2021-04-27-22-22-22.bpo-43959.n2261q.rst @@ -0,0 +1 @@ +The documentation on the PyContextVar C-API was clarified.