From 20678fd8740de31e5b078a470a0f7629b0994f51 Mon Sep 17 00:00:00 2001 From: Peter Lamut Date: Mon, 30 Jul 2018 16:15:44 +0100 Subject: [PATCH] Add docstrings to public methods from context.c (GH-8531) --- Misc/ACKS | 1 + Python/clinic/context.c.h | 45 +++++++++++++++++++++++++++------- Python/context.c | 51 +++++++++++++++++++++++++++++++++------ 3 files changed, 80 insertions(+), 17 deletions(-) diff --git a/Misc/ACKS b/Misc/ACKS index 0b0bb3a763d..0cb73a00308 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -888,6 +888,7 @@ Loïc Lajeanne David Lam Thomas Lamb Valerie Lambert +Peter Lamut Jean-Baptiste "Jiba" Lamy Ronan Lamy Peter Landry diff --git a/Python/clinic/context.c.h b/Python/clinic/context.c.h index dcf4c214e1b..683b9d7902f 100644 --- a/Python/clinic/context.c.h +++ b/Python/clinic/context.c.h @@ -5,7 +5,11 @@ preserve PyDoc_STRVAR(_contextvars_Context_get__doc__, "get($self, key, default=None, /)\n" "--\n" -"\n"); +"\n" +"Return the value for `key` if `key` has the value in the context object.\n" +"\n" +"If `key` does not exist, return `default`. If `default` is not given,\n" +"return None."); #define _CONTEXTVARS_CONTEXT_GET_METHODDEF \ {"get", (PyCFunction)_contextvars_Context_get, METH_FASTCALL, _contextvars_Context_get__doc__}, @@ -35,7 +39,10 @@ exit: PyDoc_STRVAR(_contextvars_Context_items__doc__, "items($self, /)\n" "--\n" -"\n"); +"\n" +"Return all variables and their values in the context object.\n" +"\n" +"The result is returned as a list of 2-tuples (variable, value)."); #define _CONTEXTVARS_CONTEXT_ITEMS_METHODDEF \ {"items", (PyCFunction)_contextvars_Context_items, METH_NOARGS, _contextvars_Context_items__doc__}, @@ -52,7 +59,8 @@ _contextvars_Context_items(PyContext *self, PyObject *Py_UNUSED(ignored)) PyDoc_STRVAR(_contextvars_Context_keys__doc__, "keys($self, /)\n" "--\n" -"\n"); +"\n" +"Return a list of all variables in the context object."); #define _CONTEXTVARS_CONTEXT_KEYS_METHODDEF \ {"keys", (PyCFunction)_contextvars_Context_keys, METH_NOARGS, _contextvars_Context_keys__doc__}, @@ -69,7 +77,8 @@ _contextvars_Context_keys(PyContext *self, PyObject *Py_UNUSED(ignored)) PyDoc_STRVAR(_contextvars_Context_values__doc__, "values($self, /)\n" "--\n" -"\n"); +"\n" +"Return a list of all variables’ values in the context object."); #define _CONTEXTVARS_CONTEXT_VALUES_METHODDEF \ {"values", (PyCFunction)_contextvars_Context_values, METH_NOARGS, _contextvars_Context_values__doc__}, @@ -86,7 +95,8 @@ _contextvars_Context_values(PyContext *self, PyObject *Py_UNUSED(ignored)) PyDoc_STRVAR(_contextvars_Context_copy__doc__, "copy($self, /)\n" "--\n" -"\n"); +"\n" +"Return a shallow copy of the context object."); #define _CONTEXTVARS_CONTEXT_COPY_METHODDEF \ {"copy", (PyCFunction)_contextvars_Context_copy, METH_NOARGS, _contextvars_Context_copy__doc__}, @@ -103,7 +113,14 @@ _contextvars_Context_copy(PyContext *self, PyObject *Py_UNUSED(ignored)) PyDoc_STRVAR(_contextvars_ContextVar_get__doc__, "get($self, default=None, /)\n" "--\n" -"\n"); +"\n" +"Return a value for the context variable for the current context.\n" +"\n" +"If there is no value for the variable in the current context, the method will:\n" +" * return the value of the default argument of the method, if provided; or\n" +" * return the default value for the context variable, if it was created\n" +" with one; or\n" +" * raise a LookupError."); #define _CONTEXTVARS_CONTEXTVAR_GET_METHODDEF \ {"get", (PyCFunction)_contextvars_ContextVar_get, METH_FASTCALL, _contextvars_ContextVar_get__doc__}, @@ -131,7 +148,13 @@ exit: PyDoc_STRVAR(_contextvars_ContextVar_set__doc__, "set($self, value, /)\n" "--\n" -"\n"); +"\n" +"Call to set a new value for the context variable in the current context.\n" +"\n" +"The required value argument is the new value for the context variable.\n" +"\n" +"Returns a Token object that can be used to restore the variable to its previous\n" +"value via the `ContextVar.reset()` method."); #define _CONTEXTVARS_CONTEXTVAR_SET_METHODDEF \ {"set", (PyCFunction)_contextvars_ContextVar_set, METH_O, _contextvars_ContextVar_set__doc__}, @@ -139,8 +162,12 @@ PyDoc_STRVAR(_contextvars_ContextVar_set__doc__, PyDoc_STRVAR(_contextvars_ContextVar_reset__doc__, "reset($self, token, /)\n" "--\n" -"\n"); +"\n" +"Reset the context variable.\n" +"\n" +"The variable is reset to the value it had before the `ContextVar.set()` that\n" +"created the token was used."); #define _CONTEXTVARS_CONTEXTVAR_RESET_METHODDEF \ {"reset", (PyCFunction)_contextvars_ContextVar_reset, METH_O, _contextvars_ContextVar_reset__doc__}, -/*[clinic end generated code: output=d9a675e3a52a14fc input=a9049054013a1b77]*/ +/*[clinic end generated code: output=33414d13716d0648 input=a9049054013a1b77]*/ diff --git a/Python/context.c b/Python/context.c index 8ee048ccdd5..c9658bae33c 100644 --- a/Python/context.c +++ b/Python/context.c @@ -489,12 +489,17 @@ _contextvars.Context.get key: object default: object = None / + +Return the value for `key` if `key` has the value in the context object. + +If `key` does not exist, return `default`. If `default` is not given, +return None. [clinic start generated code]*/ static PyObject * _contextvars_Context_get_impl(PyContext *self, PyObject *key, PyObject *default_value) -/*[clinic end generated code: output=0c54aa7664268189 input=8d4c33c8ecd6d769]*/ +/*[clinic end generated code: output=0c54aa7664268189 input=c8eeb81505023995]*/ { if (context_check_key_type(key)) { return NULL; @@ -516,11 +521,15 @@ _contextvars_Context_get_impl(PyContext *self, PyObject *key, /*[clinic input] _contextvars.Context.items + +Return all variables and their values in the context object. + +The result is returned as a list of 2-tuples (variable, value). [clinic start generated code]*/ static PyObject * _contextvars_Context_items_impl(PyContext *self) -/*[clinic end generated code: output=fa1655c8a08502af input=2d570d1455004979]*/ +/*[clinic end generated code: output=fa1655c8a08502af input=00db64ae379f9f42]*/ { return _PyHamt_NewIterItems(self->ctx_vars); } @@ -528,11 +537,13 @@ _contextvars_Context_items_impl(PyContext *self) /*[clinic input] _contextvars.Context.keys + +Return a list of all variables in the context object. [clinic start generated code]*/ static PyObject * _contextvars_Context_keys_impl(PyContext *self) -/*[clinic end generated code: output=177227c6b63ec0e2 input=13005e142fbbf37d]*/ +/*[clinic end generated code: output=177227c6b63ec0e2 input=114b53aebca3449c]*/ { return _PyHamt_NewIterKeys(self->ctx_vars); } @@ -540,11 +551,13 @@ _contextvars_Context_keys_impl(PyContext *self) /*[clinic input] _contextvars.Context.values + +Return a list of all variables’ values in the context object. [clinic start generated code]*/ static PyObject * _contextvars_Context_values_impl(PyContext *self) -/*[clinic end generated code: output=d286dabfc8db6dde input=c2cbc40a4470e905]*/ +/*[clinic end generated code: output=d286dabfc8db6dde input=6c3d08639ba3bf67]*/ { return _PyHamt_NewIterValues(self->ctx_vars); } @@ -552,11 +565,13 @@ _contextvars_Context_values_impl(PyContext *self) /*[clinic input] _contextvars.Context.copy + +Return a shallow copy of the context object. [clinic start generated code]*/ static PyObject * _contextvars_Context_copy_impl(PyContext *self) -/*[clinic end generated code: output=30ba8896c4707a15 input=3e3fd72d598653ab]*/ +/*[clinic end generated code: output=30ba8896c4707a15 input=ebafdbdd9c72d592]*/ { return (PyObject *)context_new_from_vars(self->ctx_vars); } @@ -872,11 +887,19 @@ error: _contextvars.ContextVar.get default: object = NULL / + +Return a value for the context variable for the current context. + +If there is no value for the variable in the current context, the method will: + * return the value of the default argument of the method, if provided; or + * return the default value for the context variable, if it was created + with one; or + * raise a LookupError. [clinic start generated code]*/ static PyObject * _contextvars_ContextVar_get_impl(PyContextVar *self, PyObject *default_value) -/*[clinic end generated code: output=0746bd0aa2ced7bf input=8d002b02eebbb247]*/ +/*[clinic end generated code: output=0746bd0aa2ced7bf input=30aa2ab9e433e401]*/ { if (!PyContextVar_CheckExact(self)) { PyErr_SetString( @@ -901,11 +924,18 @@ _contextvars_ContextVar_get_impl(PyContextVar *self, PyObject *default_value) _contextvars.ContextVar.set value: object / + +Call to set a new value for the context variable in the current context. + +The required value argument is the new value for the context variable. + +Returns a Token object that can be used to restore the variable to its previous +value via the `ContextVar.reset()` method. [clinic start generated code]*/ static PyObject * _contextvars_ContextVar_set(PyContextVar *self, PyObject *value) -/*[clinic end generated code: output=446ed5e820d6d60b input=a2d88f57c6d86f7c]*/ +/*[clinic end generated code: output=446ed5e820d6d60b input=c0a6887154227453]*/ { return (PyObject *)PyContextVar_Set(self, value); } @@ -914,11 +944,16 @@ _contextvars_ContextVar_set(PyContextVar *self, PyObject *value) _contextvars.ContextVar.reset token: object / + +Reset the context variable. + +The variable is reset to the value it had before the `ContextVar.set()` that +created the token was used. [clinic start generated code]*/ static PyObject * _contextvars_ContextVar_reset(PyContextVar *self, PyObject *token) -/*[clinic end generated code: output=d4ee34d0742d62ee input=4c871b6f1f31a65f]*/ +/*[clinic end generated code: output=d4ee34d0742d62ee input=ebe2881e5af4ffda]*/ { if (!PyContextToken_CheckExact(token)) { PyErr_Format(PyExc_TypeError,