Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 18e951e

Browse files
committed
Review edits of parsing_arguments.rst
1 parent a6fce96 commit 18e951e

File tree

1 file changed

+39
-11
lines changed

1 file changed

+39
-11
lines changed

‎doc/sphinx/source/parsing_arguments.rst

Lines changed: 39 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ This section describes how you write functions that accept Python ``*args`` and
2020
arguments and how to extract ``PyObject`` or C fundamental types from them.
2121

2222

23+
====================================
2324
Specifying the Function Arguments
2425
====================================
2526

@@ -31,6 +32,7 @@ Two important features of CPython C functions are:
3132

3233
These are described below.
3334

35+
-------------------------------
3436
C Function Declaration
3537
-------------------------------
3638

@@ -52,8 +54,18 @@ supress a compiler warning or error thus:
5254
static PyObject *
5355
parse_args_kwargs(PyObject *Py_UNUSED(module), PyObject *args, PyObject *kwargs);
5456
57+
.. index::
58+
single: Parsing Arguments; ml_flags
59+
60+
Setting the ``ml_flags`` Field
61+
------------------------------
62+
63+
The `ml_flags <https://docs.python.org/3.13/c-api/structures.html#c.PyMethodDef.ml_flags>`_ field in
64+
`PyMethodDef <https://docs.python.org/3.13/c-api/structures.html#c.PyMethodDef>`_ specifies the form of the arguments.
65+
5566
.. index::
5667
single: Parsing Arguments; No Arguments
68+
single: Parsing Arguments; METH_NOARGS
5769

5870
No Arguments
5971
^^^^^^^^^^^^^^^^^^
@@ -64,6 +76,7 @@ No Arguments
6476

6577
.. index::
6678
single: Parsing Arguments; One Argument
79+
single: Parsing Arguments; METH_O
6780

6881
One Argument
6982
^^^^^^^^^^^^^^^^^^
@@ -74,23 +87,27 @@ One Argument
7487

7588
.. index::
7689
single: Parsing Arguments; Multiple Arguments
90+
single: Parsing Arguments; METH_VARARGS
7791

7892
Multiple Positional Arguments
7993
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8094

8195
- The flags will be `METH_VARARGS <https://docs.python.org/3/c-api/structures.html#c.METH_VARARGS>`_
8296
- The C Function Signature will be ``PyObject *PyCFunction(PyObject *self, PyObject *args);``
83-
- Second value will be a sequence of arguments.
97+
- Second value will be a tuple of arguments.
98+
- `PyArg_ParseTuple()`_ is used to unpack the arguments.
8499

85100
.. index::
86101
single: Parsing Arguments; Positional and Keyword Arguments
102+
single: Parsing Arguments; METH_KEYWORDS
87103

88104
Positional and Keyword Arguments
89105
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
90106

91107
- The flags will be `METH_NOARGS | METH_KEYWORDS <https://docs.python.org/3/c-api/structures.html#c.METH_KEYWORDS>`_
92108
- The C Function Signature will be ``PyObject *PyCFunctionWithKeywords(PyObject *self, PyObject *args, PyObject *kwargs);``
93109
- Second value will be a sequence of arguments, the third the dictionary of arguments.
110+
- `PyArg_ParseTupleAndKeywords()`_ is used to unpack the arguments.
94111

95112
Documentation:
96113

@@ -137,7 +154,8 @@ And this would be added to the module, say, by using:
137154
Parsing the Arguments
138155
------------------------------
139156

140-
Once whe have the C function correctly declared then the arguments have to parsed according to their types.
157+
Once we have the C function correctly declared then the arguments have to parsed according to their types and,
158+
if required, converted to C types (so-called "unboxing").
141159
This is done using the `PyArg_ParseTuple()`_ and `PyArg_ParseTupleAndKeywords()`_
142160
(ignoring "old-style" functions which use `PyArg_Parse <https://docs.python.org/3/c-api/arg.html#c.PyArg_Parse>`_).
143161

@@ -153,7 +171,7 @@ The reference documentation is excellent: `argument parsing and building values
153171

154172
``static PyObject *parse_args(PyObject *module, PyObject *args);``
155173

156-
Which expects the Python argument[0] to be a bytes object and the Python argument[1]
174+
Which expects the Python args[0] to be a bytes object and the Python args[1]
157175
to be an integer by using:
158176

159177
``PyArg_ParseTuple(args, "Si", &arg0, &arg1)``
@@ -185,6 +203,7 @@ These examples are in ``src/cpy/cParseArgs.c`` and their tests are in ``tests/un
185203

186204
.. index::
187205
single: Parsing Arguments Example; No Arguments
206+
single: Parsing Arguments; METH_NOARGS
188207

189208
No Arguments
190209
------------------------------------
@@ -219,6 +238,7 @@ The Python interpreter will raise a ``TypeError`` on any arguments are offered t
219238
220239
.. index::
221240
single: Parsing Arguments Example; One Argument
241+
single: Parsing Arguments; METH_O
222242

223243
One Argument
224244
------------------------------------
@@ -304,6 +324,7 @@ Side note: Of course this does not protect you from malicious/badly written code
304324

305325
.. index::
306326
single: Parsing Arguments Example; Variable Number of Arguments
327+
single: Parsing Arguments; METH_VARARGS
307328

308329
Variable Number of Arguments
309330
----------------------------------------------------
@@ -316,7 +337,8 @@ In the following code we are expecting a bytes object, an integer and an optiona
316337
For demonstration purposes, this returns the same three arguments.
317338
In Python the equivalent function signature would be::
318339

319-
def parse_args(a: bytes, b: int, c: str = 'default_string') -> typing.Tuple[bytes, int, str]:
340+
def parse_args(a: bytes, b: int, c: str = 'default_string') \
341+
-> typing.Tuple[bytes, int, str]:
320342

321343
Here is the C code, note the string that describes the argument types passed to ``PyArg_ParseTuple``, if these types
322344
are not present a ``ValueError`` will be set.
@@ -361,6 +383,7 @@ Note the wide variety of error messages that are obtained.
361383
.. index::
362384
single: Parsing Arguments Example; Variable Number of Arguments
363385
single: Parsing Arguments Example; Keyword Arguments
386+
single: Parsing Arguments; METH_KEYWORDS
364387

365388
Variable Number of Arguments and Keyword Arguments
366389
--------------------------------------------------------------------------
@@ -374,7 +397,8 @@ In the following code we are expecting a sequence and an optional integer count
374397
It returns the `sequence` repeated `count` times.
375398
In Python the equivalent function declaration would be::
376399

377-
def parse_args_kwargs(sequence=typing.Sequence[typing.Any], count: = 1) -> typing.Sequence[typing.Any]:
400+
def parse_args_kwargs(sequence=typing.Sequence[typing.Any], count: = 1) \
401+
-> typing.Sequence[typing.Any]:
378402
return sequence * count
379403

380404
Here is the C code, note the string ``"O|i"`` that describes the argument types passed to
@@ -393,7 +417,9 @@ Here is the C code, note the string ``"O|i"`` that describes the argument types
393417
NULL,
394418
};
395419
396-
if (!PyArg_ParseTupleAndKeywords(args, kwargs, "O|i", kwlist, &py_sequence, &count)) {
420+
if (!PyArg_ParseTupleAndKeywords(
421+
args, kwargs, "O|i", kwlist, &py_sequence, &count
422+
)) {
397423
goto except;
398424
}
399425
@@ -470,6 +496,7 @@ The solution is to cast away const in the call:
470496
single: Parsing Arguments Example; Default String Arguments
471497
single: Parsing Arguments Example; Default Bytes Arguments
472498
single: Default Arguments; C
499+
single: Py_buffer
473500

474501
Default String and Bytes Arguments
475502
------------------------------------------
@@ -559,8 +586,8 @@ Suppose we want the functional equivalent of the Python function signature
559586

560587
.. code-block:: python
561588
562-
def parse_pos_only_kwd_only(pos1: str, pos2: int, /, pos_or_kwd: bytes, *,kwd1: float,
563-
kwd2: int):
589+
def parse_pos_only_kwd_only(pos1: str, pos2: int, /, pos_or_kwd: bytes, *,
590+
kwd1: float=256.0, kwd2: int=-421):
564591
return None
565592
566593
This is achieved by combining two techniques:
@@ -696,7 +723,7 @@ Being Pythonic with Default Mutable Arguments
696723
=============================================
697724

698725
If the arguments default to some C fundamental type the code above is fine.
699-
However if the arguments default to Python objects then a little more work is needed.
726+
However if the mutable arguments default to Python objects then a little more work is needed.
700727

701728
.. note::
702729

@@ -926,7 +953,8 @@ Firstly a macro to declare the static default object:
926953
927954
.. warning::
928955

929-
When using this macro in a source file then make sure each given "name" argument is unique.
956+
When using this macro in a source file then make sure each given "name" argument is unique within the
957+
translation unit.
930958

931959
And a macro to set it:
932960

@@ -937,7 +965,7 @@ And a macro to set it:
937965
name = default_##name; \
938966
}
939967
940-
And a macro to chek the type of the argument:
968+
And a macro to check the type of the argument:
941969

942970
.. code-block:: c
943971

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /