Skip to content

Commit

Permalink
Docs: Argument Clinic: Group guides about default values (python/cpyt…
Browse files Browse the repository at this point in the history
…hon#106872)

Previous ToC layout (excerpt):

    - How to use symbolic default values
    ...
    - How to assign default values to parameter
      - How to use the ``NULL`` default value
      - How to use expressions as default values

New layout:

    - How to assign default values to parameter
      - The ``NULL`` default value
      - Symbolic default values
      - Expressions as default values
  • Loading branch information
erlend-aasland committed Sep 8, 2023
1 parent bf2b77d commit 2647a31
Showing 1 changed file with 20 additions and 20 deletions.
40 changes: 20 additions & 20 deletions Doc/howto/clinic.rst
Original file line number Diff line number Diff line change
Expand Up @@ -564,22 +564,6 @@ How-to guides
=============


How to use symbolic default values
----------------------------------

The default value you provide for a parameter can't be any arbitrary
expression. Currently the following are explicitly supported:

* Numeric constants (integer and float)
* String constants
* ``True``, ``False``, and ``None``
* Simple symbolic constants like ``sys.maxsize``, which must
start with the name of the module

(In the future, this may need to get even more elaborate,
to allow full expressions like ``CONSTANT - 1``.)


How to to rename C functions and variables generated by Argument Clinic
-----------------------------------------------------------------------

Expand Down Expand Up @@ -965,8 +949,8 @@ There's also special support for a default value of ``NULL``, and
for simple expressions, documented in the following sections.


How to use the ``NULL`` default value
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``NULL`` default value
^^^^^^^^^^^^^^^^^^^^^^^^^^

For string and object parameters, you can set them to ``None`` to indicate
that there's no default. However, that means the C variable will be
Expand All @@ -976,8 +960,24 @@ behaves like a default value of ``None``, but the C variable is initialized
with ``NULL``.


How to use expressions as default values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Symbolic default values
^^^^^^^^^^^^^^^^^^^^^^^

The default value you provide for a parameter can't be any arbitrary
expression. Currently the following are explicitly supported:

* Numeric constants (integer and float)
* String constants
* ``True``, ``False``, and ``None``
* Simple symbolic constants like ``sys.maxsize``, which must
start with the name of the module

(In the future, this may need to get even more elaborate,
to allow full expressions like ``CONSTANT - 1``.)


Expressions as default values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The default value for a parameter can be more than just a literal value.
It can be an entire expression, using math operators and looking up attributes
Expand Down

0 comments on commit 2647a31

Please sign in to comment.