# Copyright (C) 2001-2020, Python Software Foundation

# This file is distributed under the same license as the Python package.

# Maintained by the python-doc-es workteam.

# docs-es@python.org /

# https://mail.python.org/mailman3/lists/docs-es.python.org/

# Check https://github.com/PyCampES/python-docs-es/blob/3.8/TRANSLATORS to

# get the list of volunteers

#

#, fuzzy

msgid ""

msgstr ""

"Project-Id-Version: Python 3.8\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2020-05-05 12:54+0200\n"

"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"

"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"

"Language-Team: python-doc-es\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=utf-8\n"

"Content-Transfer-Encoding: 8bit\n"

"Generated-By: Babel 2.8.0\n"

#: ../Doc/howto/clinic.rst:5

msgid "Argument Clinic How-To"

msgstr ""

#: ../Doc/howto/clinic.rst

msgid "author"

msgstr ""

#: ../Doc/howto/clinic.rst:7

msgid "Larry Hastings"

msgstr ""

msgid "Abstract"

msgstr ""

#: ../Doc/howto/clinic.rst:12

msgid ""

"Argument Clinic is a preprocessor for CPython C files. Its purpose is to "

"automate all the boilerplate involved with writing argument parsing code for "

"\"builtins\". This document shows you how to convert your first C function "

"to work with Argument Clinic, and then introduces some advanced topics on "

"Argument Clinic usage."

msgstr ""

#: ../Doc/howto/clinic.rst:19

msgid ""

"Currently Argument Clinic is considered internal-only for CPython. Its use "

"is not supported for files outside CPython, and no guarantees are made "

"regarding backwards compatibility for future versions. In other words: if "

"you maintain an external C extension for CPython, you're welcome to "

"experiment with Argument Clinic in your own code. But the version of "

"Argument Clinic that ships with the next version of CPython *could* be "

"totally incompatible and break all your code."

msgstr ""

#: ../Doc/howto/clinic.rst:29

msgid "The Goals Of Argument Clinic"

msgstr ""

#: ../Doc/howto/clinic.rst:31

msgid ""

"Argument Clinic's primary goal is to take over responsibility for all "

"argument parsing code inside CPython. This means that, when you convert a "

"function to work with Argument Clinic, that function should no longer do any "

"of its own argument parsing—the code generated by Argument Clinic should be "

"a \"black box\" to you, where CPython calls in at the top, and your code "

"gets called at the bottom, with ``PyObject *args`` (and maybe ``PyObject "

"*kwargs``) magically converted into the C variables and types you need."

msgstr ""

#: ../Doc/howto/clinic.rst:41

msgid ""

"In order for Argument Clinic to accomplish its primary goal, it must be easy "

"to use. Currently, working with CPython's argument parsing library is a "

"chore, requiring maintaining redundant information in a surprising number of "

"places. When you use Argument Clinic, you don't have to repeat yourself."

msgstr ""

#: ../Doc/howto/clinic.rst:47

msgid ""

"Obviously, no one would want to use Argument Clinic unless it's solving "

"their problem—and without creating new problems of its own. So it's "

"paramount that Argument Clinic generate correct code. It'd be nice if the "

"code was faster, too, but at the very least it should not introduce a major "

"speed regression. (Eventually Argument Clinic *should* make a major speedup "

"possible—we could rewrite its code generator to produce tailor-made argument "

"parsing code, rather than calling the general-purpose CPython argument "

"parsing library. That would make for the fastest argument parsing possible!)"

msgstr ""

#: ../Doc/howto/clinic.rst:59

msgid ""

"Additionally, Argument Clinic must be flexible enough to work with any "

"approach to argument parsing. Python has some functions with some very "

"strange parsing behaviors; Argument Clinic's goal is to support all of them."

msgstr ""

#: ../Doc/howto/clinic.rst:64

msgid ""

"Finally, the original motivation for Argument Clinic was to provide "

"introspection \"signatures\" for CPython builtins. It used to be, the "

"introspection query functions would throw an exception if you passed in a "

"builtin. With Argument Clinic, that's a thing of the past!"

msgstr ""

#: ../Doc/howto/clinic.rst:70

msgid ""

"One idea you should keep in mind, as you work with Argument Clinic: the more "

"information you give it, the better job it'll be able to do. Argument Clinic "

"is admittedly relatively simple right now. But as it evolves it will get "

"more sophisticated, and it should be able to do many interesting and smart "

"things with all the information you give it."

msgstr ""

#: ../Doc/howto/clinic.rst:80

msgid "Basic Concepts And Usage"

msgstr ""

#: ../Doc/howto/clinic.rst:82

msgid ""

"Argument Clinic ships with CPython; you'll find it in ``Tools/clinic/clinic."

"py``. If you run that script, specifying a C file as an argument:"

msgstr ""

#: ../Doc/howto/clinic.rst:89

msgid ""

"Argument Clinic will scan over the file looking for lines that look exactly "

"like this:"

msgstr ""

#: ../Doc/howto/clinic.rst:96

msgid ""

"When it finds one, it reads everything up to a line that looks exactly like "

"this:"

msgstr ""

#: ../Doc/howto/clinic.rst:103

msgid ""

"Everything in between these two lines is input for Argument Clinic. All of "

"these lines, including the beginning and ending comment lines, are "

"collectively called an Argument Clinic \"block\"."

msgstr ""

#: ../Doc/howto/clinic.rst:107

msgid ""

"When Argument Clinic parses one of these blocks, it generates output. This "

"output is rewritten into the C file immediately after the block, followed by "

"a comment containing a checksum. The Argument Clinic block now looks like "

"this:"

msgstr ""

#: ../Doc/howto/clinic.rst:120

msgid ""

"If you run Argument Clinic on the same file a second time, Argument Clinic "

"will discard the old output and write out the new output with a fresh "

"checksum line. However, if the input hasn't changed, the output won't "

"change either."

msgstr ""

#: ../Doc/howto/clinic.rst:124

msgid ""

"You should never modify the output portion of an Argument Clinic block. "

"Instead, change the input until it produces the output you want. (That's "

"the purpose of the checksum—to detect if someone changed the output, as "

"these edits would be lost the next time Argument Clinic writes out fresh "

"output.)"

msgstr ""

#: ../Doc/howto/clinic.rst:129

msgid ""

"For the sake of clarity, here's the terminology we'll use with Argument "

"Clinic:"

msgstr ""

#: ../Doc/howto/clinic.rst:131

msgid ""

"The first line of the comment (``/*[clinic input]``) is the *start line*."

msgstr ""

#: ../Doc/howto/clinic.rst:132

msgid ""

"The last line of the initial comment (``[clinic start generated code]*/``) "

"is the *end line*."

msgstr ""

#: ../Doc/howto/clinic.rst:133

msgid ""

"The last line (``/*[clinic end generated code: checksum=...]*/``) is the "

"*checksum line*."

msgstr ""

#: ../Doc/howto/clinic.rst:134

msgid "In between the start line and the end line is the *input*."

msgstr ""

#: ../Doc/howto/clinic.rst:135

msgid "In between the end line and the checksum line is the *output*."

msgstr ""

#: ../Doc/howto/clinic.rst:136

msgid ""

"All the text collectively, from the start line to the checksum line "

"inclusively, is the *block*. (A block that hasn't been successfully "

"processed by Argument Clinic yet doesn't have output or a checksum line, but "

"it's still considered a block.)"

msgstr ""

#: ../Doc/howto/clinic.rst:143

msgid "Converting Your First Function"

msgstr ""

#: ../Doc/howto/clinic.rst:145

msgid ""

"The best way to get a sense of how Argument Clinic works is to convert a "

"function to work with it. Here, then, are the bare minimum steps you'd need "

"to follow to convert a function to work with Argument Clinic. Note that for "

"code you plan to check in to CPython, you really should take the conversion "

"farther, using some of the advanced concepts you'll see later on in the "

"document (like \"return converters\" and \"self converters\"). But we'll "

"keep it simple for this walkthrough so you can learn."

msgstr ""

#: ../Doc/howto/clinic.rst:154

msgid "Let's dive in!"

msgstr ""

#: ../Doc/howto/clinic.rst:156

msgid ""

"Make sure you're working with a freshly updated checkout of the CPython "

"trunk."

msgstr ""

#: ../Doc/howto/clinic.rst:159

msgid ""

"Find a Python builtin that calls either :c:func:`PyArg_ParseTuple` or :c:"

"func:`PyArg_ParseTupleAndKeywords`, and hasn't been converted to work with "

"Argument Clinic yet. For my example I'm using ``_pickle.Pickler.dump()``."

msgstr ""

#: ../Doc/howto/clinic.rst:164

msgid ""

"If the call to the ``PyArg_Parse`` function uses any of the following format "

"units:"

msgstr ""

#: ../Doc/howto/clinic.rst:176

msgid ""

"or if it has multiple calls to :c:func:`PyArg_ParseTuple`, you should choose "

"a different function. Argument Clinic *does* support all of these "

"scenarios. But these are advanced topics—let's do something simpler for "

"your first function."

msgstr ""

#: ../Doc/howto/clinic.rst:181

msgid ""

"Also, if the function has multiple calls to :c:func:`PyArg_ParseTuple` or :c:"

"func:`PyArg_ParseTupleAndKeywords` where it supports different types for the "

"same argument, or if the function uses something besides PyArg_Parse "

"functions to parse its arguments, it probably isn't suitable for conversion "

"to Argument Clinic. Argument Clinic doesn't support generic functions or "

"polymorphic parameters."

msgstr ""

#: ../Doc/howto/clinic.rst:188

msgid "Add the following boilerplate above the function, creating our block::"

msgstr ""

#: ../Doc/howto/clinic.rst:193

msgid ""

"Cut the docstring and paste it in between the ``[clinic]`` lines, removing "

"all the junk that makes it a properly quoted C string. When you're done you "

"should have just the text, based at the left margin, with no line wider than "

"80 characters. (Argument Clinic will preserve indents inside the docstring.)"

msgstr ""

#: ../Doc/howto/clinic.rst:199

msgid ""

"If the old docstring had a first line that looked like a function signature, "

"throw that line away. (The docstring doesn't need it anymore—when you use "

"``help()`` on your builtin in the future, the first line will be built "

"automatically based on the function's signature.)"

msgstr ""

#: ../Doc/howto/clinic.rst:205 ../Doc/howto/clinic.rst:226

#: ../Doc/howto/clinic.rst:250 ../Doc/howto/clinic.rst:308

#: ../Doc/howto/clinic.rst:348 ../Doc/howto/clinic.rst:375

#: ../Doc/howto/clinic.rst:481 ../Doc/howto/clinic.rst:533

msgid "Sample::"

msgstr ""

#: ../Doc/howto/clinic.rst:211

msgid ""

"If your docstring doesn't have a \"summary\" line, Argument Clinic will "

"complain. So let's make sure it has one. The \"summary\" line should be a "

"paragraph consisting of a single 80-column line at the beginning of the "

"docstring."

msgstr ""

#: ../Doc/howto/clinic.rst:216

msgid ""

"(Our example docstring consists solely of a summary line, so the sample code "

"doesn't have to change for this step.)"

msgstr ""

#: ../Doc/howto/clinic.rst:219

msgid ""

"Above the docstring, enter the name of the function, followed by a blank "

"line. This should be the Python name of the function, and should be the "

"full dotted path to the function—it should start with the name of the "

"module, include any sub-modules, and if the function is a method on a class "

"it should include the class name too."

msgstr ""

#: ../Doc/howto/clinic.rst:234

msgid ""

"If this is the first time that module or class has been used with Argument "

"Clinic in this C file, you must declare the module and/or class. Proper "

"Argument Clinic hygiene prefers declaring these in a separate block "

"somewhere near the top of the C file, in the same way that include files and "

"statics go at the top. (In our sample code we'll just show the two blocks "

"next to each other.)"

msgstr ""

#: ../Doc/howto/clinic.rst:242

msgid ""

"The name of the class and module should be the same as the one seen by "

"Python. Check the name defined in the :c:type:`PyModuleDef` or :c:type:"

"`PyTypeObject` as appropriate."

msgstr ""

#: ../Doc/howto/clinic.rst:246

msgid ""

"When you declare a class, you must also specify two aspects of its type in "

"C: the type declaration you'd use for a pointer to an instance of this "

"class, and a pointer to the :c:type:`PyTypeObject` for this class."

msgstr ""

#: ../Doc/howto/clinic.rst:266

msgid ""

"Declare each of the parameters to the function. Each parameter should get "

"its own line. All the parameter lines should be indented from the function "

"name and the docstring."

msgstr ""

#: ../Doc/howto/clinic.rst:270

msgid "The general form of these parameter lines is as follows:"

msgstr ""

#: ../Doc/howto/clinic.rst:276

msgid "If the parameter has a default value, add that after the converter:"

msgstr ""

#: ../Doc/howto/clinic.rst:283

msgid ""

"Argument Clinic's support for \"default values\" is quite sophisticated; "

"please see :ref:`the section below on default values <default_values>` for "

"more information."

msgstr ""

#: ../Doc/howto/clinic.rst:287

msgid "Add a blank line below the parameters."

msgstr ""

#: ../Doc/howto/clinic.rst:289

msgid ""

"What's a \"converter\"? It establishes both the type of the variable used "

"in C, and the method to convert the Python value into a C value at runtime. "

"For now you're going to use what's called a \"legacy converter\"—a "

"convenience syntax intended to make porting old code into Argument Clinic "

"easier."

msgstr ""

#: ../Doc/howto/clinic.rst:296

msgid ""

"For each parameter, copy the \"format unit\" for that parameter from the "

"``PyArg_Parse()`` format argument and specify *that* as its converter, as a "

"quoted string. (\"format unit\" is the formal name for the one-to-three "

"character substring of the ``format`` parameter that tells the argument "

"parsing function what the type of the variable is and how to convert it. "

"For more on format units please see :ref:`arg-parsing`.)"

msgstr ""

#: ../Doc/howto/clinic.rst:305

msgid ""

"For multicharacter format units like ``z#``, use the entire two-or-three "

"character string."

msgstr ""

#: ../Doc/howto/clinic.rst:323

msgid ""

"If your function has ``|`` in the format string, meaning some parameters "

"have default values, you can ignore it. Argument Clinic infers which "

"parameters are optional based on whether or not they have default values."

msgstr ""

#: ../Doc/howto/clinic.rst:328

msgid ""

"If your function has ``$`` in the format string, meaning it takes keyword-"

"only arguments, specify ``*`` on a line by itself before the first keyword-"

"only argument, indented the same as the parameter lines."

msgstr ""

#: ../Doc/howto/clinic.rst:333

msgid "(``_pickle.Pickler.dump`` has neither, so our sample is unchanged.)"

msgstr ""

#: ../Doc/howto/clinic.rst:336

msgid ""

"If the existing C function calls :c:func:`PyArg_ParseTuple` (as opposed to :"

"c:func:`PyArg_ParseTupleAndKeywords`), then all its arguments are positional-"

"only."

msgstr ""

#: ../Doc/howto/clinic.rst:340

msgid ""

"To mark all parameters as positional-only in Argument Clinic, add a ``/`` on "

"a line by itself after the last parameter, indented the same as the "

"parameter lines."

msgstr ""

#: ../Doc/howto/clinic.rst:344

msgid ""

"Currently this is all-or-nothing; either all parameters are positional-only, "

"or none of them are. (In the future Argument Clinic may relax this "

"restriction.)"

msgstr ""

#: ../Doc/howto/clinic.rst:364

msgid ""

"It's helpful to write a per-parameter docstring for each parameter. But per-"

"parameter docstrings are optional; you can skip this step if you prefer."

msgstr ""

#: ../Doc/howto/clinic.rst:368

msgid ""

"Here's how to add a per-parameter docstring. The first line of the per-"

"parameter docstring must be indented further than the parameter definition. "

"The left margin of this first line establishes the left margin for the whole "

"per-parameter docstring; all the text you write will be outdented by this "

"amount. You can write as much text as you like, across multiple lines if "

"you wish."

msgstr ""

#: ../Doc/howto/clinic.rst:392

msgid ""

"Save and close the file, then run ``Tools/clinic/clinic.py`` on it. With "

"luck everything worked---your block now has output, and a ``.c.h`` file has "

"been generated! Reopen the file in your text editor to see::"

msgstr ""

#: ../Doc/howto/clinic.rst:411

msgid ""

"Obviously, if Argument Clinic didn't produce any output, it's because it "

"found an error in your input. Keep fixing your errors and retrying until "

"Argument Clinic processes your file without complaint."

msgstr ""

#: ../Doc/howto/clinic.rst:415

msgid ""

"For readability, most of the glue code has been generated to a ``.c.h`` "

"file. You'll need to include that in your original ``.c`` file, typically "

"right after the clinic module block::"

msgstr ""

#: ../Doc/howto/clinic.rst:421

msgid ""

"Double-check that the argument-parsing code Argument Clinic generated looks "

"basically the same as the existing code."

msgstr ""

#: ../Doc/howto/clinic.rst:424

msgid ""

"First, ensure both places use the same argument-parsing function. The "

"existing code must call either :c:func:`PyArg_ParseTuple` or :c:func:"

"`PyArg_ParseTupleAndKeywords`; ensure that the code generated by Argument "

"Clinic calls the *exact* same function."

msgstr ""

#: ../Doc/howto/clinic.rst:430

msgid ""

"Second, the format string passed in to :c:func:`PyArg_ParseTuple` or :c:func:"

"`PyArg_ParseTupleAndKeywords` should be *exactly* the same as the hand-"

"written one in the existing function, up to the colon or semi-colon."

msgstr ""

#: ../Doc/howto/clinic.rst:435

msgid ""

"(Argument Clinic always generates its format strings with a ``:`` followed "

"by the name of the function. If the existing code's format string ends with "

"``;``, to provide usage help, this change is harmless—don't worry about it.)"

msgstr ""

#: ../Doc/howto/clinic.rst:440

msgid ""

"Third, for parameters whose format units require two arguments (like a "

"length variable, or an encoding string, or a pointer to a conversion "

"function), ensure that the second argument is *exactly* the same between the "

"two invocations."

msgstr ""

#: ../Doc/howto/clinic.rst:445

msgid ""

"Fourth, inside the output portion of the block you'll find a preprocessor "

"macro defining the appropriate static :c:type:`PyMethodDef` structure for "

"this builtin::"

msgstr ""

#: ../Doc/howto/clinic.rst:452

msgid ""

"This static structure should be *exactly* the same as the existing static :c:"

"type:`PyMethodDef` structure for this builtin."

msgstr ""

#: ../Doc/howto/clinic.rst:455

msgid ""

"If any of these items differ in *any way*, adjust your Argument Clinic "

"function specification and rerun ``Tools/clinic/clinic.py`` until they *are* "

"the same."

msgstr ""

#: ../Doc/howto/clinic.rst:460

msgid ""

"Notice that the last line of its output is the declaration of your \"impl\" "

"function. This is where the builtin's implementation goes. Delete the "

"existing prototype of the function you're modifying, but leave the opening "

"curly brace. Now delete its argument parsing code and the declarations of "

"all the variables it dumps the arguments into. Notice how the Python "

"arguments are now arguments to this impl function; if the implementation "

"used different names for these variables, fix it."

msgstr ""

#: ../Doc/howto/clinic.rst:468

msgid ""

"Let's reiterate, just because it's kind of weird. Your code should now look "

"like this::"

msgstr ""

#: ../Doc/howto/clinic.rst:477

msgid ""

"Argument Clinic generated the checksum line and the function prototype just "

"above it. You should write the opening (and closing) curly braces for the "

"function, and the implementation inside."

msgstr ""

#: ../Doc/howto/clinic.rst:522

msgid ""

"Remember the macro with the :c:type:`PyMethodDef` structure for this "

"function? Find the existing :c:type:`PyMethodDef` structure for this "

"function and replace it with a reference to the macro. (If the builtin is "

"at module scope, this will probably be very near the end of the file; if the "

"builtin is a class method, this will probably be below but relatively near "

"to the implementation.)"

msgstr ""

#: ../Doc/howto/clinic.rst:529

msgid ""

"Note that the body of the macro contains a trailing comma. So when you "

"replace the existing static :c:type:`PyMethodDef` structure with the macro, "

"*don't* add a comma to the end."

msgstr ""

#: ../Doc/howto/clinic.rst:542

msgid ""

"Compile, then run the relevant portions of the regression-test suite. This "

"change should not introduce any new compile-time warnings or errors, and "

"there should be no externally-visible change to Python's behavior."

msgstr ""

#: ../Doc/howto/clinic.rst:546

msgid ""

"Well, except for one difference: ``inspect.signature()`` run on your "

"function should now provide a valid signature!"

msgstr ""

#: ../Doc/howto/clinic.rst:549

msgid ""

"Congratulations, you've ported your first function to work with Argument "

"Clinic!"

msgstr ""

#: ../Doc/howto/clinic.rst:552

msgid "Advanced Topics"

msgstr ""

#: ../Doc/howto/clinic.rst:554

msgid ""

"Now that you've had some experience working with Argument Clinic, it's time "

"for some advanced topics."

msgstr ""

#: ../Doc/howto/clinic.rst:559

msgid "Symbolic default values"

msgstr ""

#: ../Doc/howto/clinic.rst:561

msgid ""

"The default value you provide for a parameter can't be any arbitrary "

"expression. Currently the following are explicitly supported:"

msgstr ""

#: ../Doc/howto/clinic.rst:564

msgid "Numeric constants (integer and float)"

msgstr ""

#: ../Doc/howto/clinic.rst:565

msgid "String constants"

msgstr ""

#: ../Doc/howto/clinic.rst:566

msgid "``True``, ``False``, and ``None``"

msgstr ""

#: ../Doc/howto/clinic.rst:567

msgid ""

"Simple symbolic constants like ``sys.maxsize``, which must start with the "

"name of the module"

msgstr ""

#: ../Doc/howto/clinic.rst:570

msgid ""

"In case you're curious, this is implemented in ``from_builtin()`` in ``Lib/"

"inspect.py``."

msgstr ""

#: ../Doc/howto/clinic.rst:573

msgid ""

"(In the future, this may need to get even more elaborate, to allow full "

"expressions like ``CONSTANT - 1``.)"

msgstr ""

#: ../Doc/howto/clinic.rst:578

msgid "Renaming the C functions and variables generated by Argument Clinic"

msgstr ""

#: ../Doc/howto/clinic.rst:580

msgid ""

"Argument Clinic automatically names the functions it generates for you. "

"Occasionally this may cause a problem, if the generated name collides with "

"the name of an existing C function. There's an easy solution: override the "

"names used for the C functions. Just add the keyword ``\"as\"`` to your "

"function declaration line, followed by the function name you wish to use. "

"Argument Clinic will use that function name for the base (generated) "

"function, then add ``\"_impl\"`` to the end and use that for the name of the "

"impl function."

msgstr ""

#: ../Doc/howto/clinic.rst:588

msgid ""

"For example, if we wanted to rename the C function names generated for "

"``pickle.Pickler.dump``, it'd look like this::"

msgstr ""

#: ../Doc/howto/clinic.rst:596

msgid ""

"The base function would now be named ``pickler_dumper()``, and the impl "

"function would now be named ``pickler_dumper_impl()``."

msgstr ""

#: ../Doc/howto/clinic.rst:600

msgid ""

"Similarly, you may have a problem where you want to give a parameter a "

"specific Python name, but that name may be inconvenient in C. Argument "

"Clinic allows you to give a parameter different names in Python and in C, "

"using the same ``\"as\"`` syntax::"

msgstr ""

#: ../Doc/howto/clinic.rst:614

msgid ""

"Here, the name used in Python (in the signature and the ``keywords`` array) "

"would be ``file``, but the C variable would be named ``file_obj``."

msgstr ""

#: ../Doc/howto/clinic.rst:617

msgid "You can use this to rename the ``self`` parameter too!"

msgstr ""

#: ../Doc/howto/clinic.rst:621

msgid "Converting functions using PyArg_UnpackTuple"

msgstr ""

#: ../Doc/howto/clinic.rst:623

msgid ""

"To convert a function parsing its arguments with :c:func:"

"`PyArg_UnpackTuple`, simply write out all the arguments, specifying each as "

"an ``object``. You may specify the ``type`` argument to cast the type as "

"appropriate. All arguments should be marked positional-only (add a ``/`` on "

"a line by itself after the last argument)."

msgstr ""

#: ../Doc/howto/clinic.rst:629

msgid ""

"Currently the generated code will use :c:func:`PyArg_ParseTuple`, but this "

"will change soon."

msgstr ""

#: ../Doc/howto/clinic.rst:633

msgid "Optional Groups"

msgstr ""

#: ../Doc/howto/clinic.rst:635

msgid ""

"Some legacy functions have a tricky approach to parsing their arguments: "

"they count the number of positional arguments, then use a ``switch`` "

"statement to call one of several different :c:func:`PyArg_ParseTuple` calls "

"depending on how many positional arguments there are. (These functions "

"cannot accept keyword-only arguments.) This approach was used to simulate "

"optional arguments back before :c:func:`PyArg_ParseTupleAndKeywords` was "

"created."

msgstr ""

#: ../Doc/howto/clinic.rst:642

msgid ""

"While functions using this approach can often be converted to use :c:func:"

"`PyArg_ParseTupleAndKeywords`, optional arguments, and default values, it's "

"not always possible. Some of these legacy functions have behaviors :c:func:"

"`PyArg_ParseTupleAndKeywords` doesn't directly support. The most obvious "

"example is the builtin function ``range()``, which has an optional argument "

"on the *left* side of its required argument! Another example is ``curses."

"window.addch()``, which has a group of two arguments that must always be "

"specified together. (The arguments are called ``x`` and ``y``; if you call "

"the function passing in ``x``, you must also pass in ``y``—and if you don't "

"pass in ``x`` you may not pass in ``y`` either.)"

msgstr ""

#: ../Doc/howto/clinic.rst:654

msgid ""

"In any case, the goal of Argument Clinic is to support argument parsing for "

"all existing CPython builtins without changing their semantics. Therefore "

"Argument Clinic supports this alternate approach to parsing, using what are "

"called *optional groups*. Optional groups are groups of arguments that must "

"all be passed in together. They can be to the left or the right of the "

"required arguments. They can *only* be used with positional-only parameters."

msgstr ""

#: ../Doc/howto/clinic.rst:662

msgid ""

"Optional groups are *only* intended for use when converting functions that "

"make multiple calls to :c:func:`PyArg_ParseTuple`! Functions that use *any* "

"other approach for parsing arguments should *almost never* be converted to "

"Argument Clinic using optional groups. Functions using optional groups "

"currently cannot have accurate signatures in Python, because Python just "

"doesn't understand the concept. Please avoid using optional groups wherever "

"possible."

msgstr ""

#: ../Doc/howto/clinic.rst:671

msgid ""

"To specify an optional group, add a ``[`` on a line by itself before the "

"parameters you wish to group together, and a ``]`` on a line by itself after "

"these parameters. As an example, here's how ``curses.window.addch`` uses "

"optional groups to make the first two parameters and the last parameter "

"optional::"

msgstr ""

#: ../Doc/howto/clinic.rst:700

msgid "Notes:"

msgstr ""

#: ../Doc/howto/clinic.rst:702

msgid ""

"For every optional group, one additional parameter will be passed into the "

"impl function representing the group. The parameter will be an int named "

"``group_{direction}_{number}``, where ``{direction}`` is either ``right`` or "

"``left`` depending on whether the group is before or after the required "

"parameters, and ``{number}`` is a monotonically increasing number (starting "

"at 1) indicating how far away the group is from the required parameters. "

"When the impl is called, this parameter will be set to zero if this group "

"was unused, and set to non-zero if this group was used. (By used or unused, "

"I mean whether or not the parameters received arguments in this invocation.)"

msgstr ""

#: ../Doc/howto/clinic.rst:713

msgid ""

"If there are no required arguments, the optional groups will behave as if "

"they're to the right of the required arguments."

msgstr ""

#: ../Doc/howto/clinic.rst:716

msgid ""

"In the case of ambiguity, the argument parsing code favors parameters on the "

"left (before the required parameters)."

msgstr ""

#: ../Doc/howto/clinic.rst:719

msgid "Optional groups can only contain positional-only parameters."

msgstr ""

#: ../Doc/howto/clinic.rst:721

msgid ""

"Optional groups are *only* intended for legacy code. Please do not use "

"optional groups for new code."

msgstr ""

#: ../Doc/howto/clinic.rst:726

msgid "Using real Argument Clinic converters, instead of \"legacy converters\""

msgstr ""

#: ../Doc/howto/clinic.rst:728

msgid ""

"To save time, and to minimize how much you need to learn to achieve your "

"first port to Argument Clinic, the walkthrough above tells you to use "

"\"legacy converters\". \"Legacy converters\" are a convenience, designed "

"explicitly to make porting existing code to Argument Clinic easier. And to "

"be clear, their use is acceptable when porting code for Python 3.4."

msgstr ""

#: ../Doc/howto/clinic.rst:735

msgid ""

"However, in the long term we probably want all our blocks to use Argument "

"Clinic's real syntax for converters. Why? A couple reasons:"

msgstr ""

#: ../Doc/howto/clinic.rst:739

msgid ""

"The proper converters are far easier to read and clearer in their intent."

msgstr ""

#: ../Doc/howto/clinic.rst:740

msgid ""

"There are some format units that are unsupported as \"legacy converters\", "

"because they require arguments, and the legacy converter syntax doesn't "

"support specifying arguments."

msgstr ""

#: ../Doc/howto/clinic.rst:743

msgid ""

"In the future we may have a new argument parsing library that isn't "

"restricted to what :c:func:`PyArg_ParseTuple` supports; this flexibility "

"won't be available to parameters using legacy converters."

msgstr ""

#: ../Doc/howto/clinic.rst:747

msgid ""

"Therefore, if you don't mind a little extra effort, please use the normal "

"converters instead of legacy converters."

msgstr ""

#: ../Doc/howto/clinic.rst:750

msgid ""

"In a nutshell, the syntax for Argument Clinic (non-legacy) converters looks "

"like a Python function call. However, if there are no explicit arguments to "

"the function (all functions take their default values), you may omit the "

"parentheses. Thus ``bool`` and ``bool()`` are exactly the same converters."

msgstr ""

#: ../Doc/howto/clinic.rst:756

msgid ""

"All arguments to Argument Clinic converters are keyword-only. All Argument "

"Clinic converters accept the following arguments:"

msgstr ""

#: ../Doc/howto/clinic.rst:764 ../Doc/howto/clinic.rst:1252

msgid "``c_default``"

msgstr ""

#: ../Doc/howto/clinic.rst:760

msgid ""

"The default value for this parameter when defined in C. Specifically, this "

"will be the initializer for the variable declared in the \"parse function"

"\". See :ref:`the section on default values <default_values>` for how to "

"use this. Specified as a string."

msgstr ""

#: ../Doc/howto/clinic.rst:769

msgid "``annotation``"

msgstr ""

#: ../Doc/howto/clinic.rst:767

msgid ""

"The annotation value for this parameter. Not currently supported, because :"

"pep:`8` mandates that the Python library may not use annotations."

msgstr ""

#: ../Doc/howto/clinic.rst:771

msgid ""

"In addition, some converters accept additional arguments. Here is a list of "

"these arguments, along with their meanings:"

msgstr ""

#: ../Doc/howto/clinic.rst:780

msgid "``accept``"

msgstr ""

#: ../Doc/howto/clinic.rst:775

msgid ""

"A set of Python types (and possibly pseudo-types); this restricts the "

"allowable Python argument to values of these types. (This is not a general-"

"purpose facility; as a rule it only supports specific lists of types as "

"shown in the legacy converter table.)"

msgstr ""

#: ../Doc/howto/clinic.rst:780

msgid "To accept ``None``, add ``NoneType`` to this set."

msgstr ""

#: ../Doc/howto/clinic.rst:785

msgid "``bitwise``"

msgstr ""

#: ../Doc/howto/clinic.rst:783

msgid ""

"Only supported for unsigned integers. The native integer value of this "

"Python argument will be written to the parameter without any range checking, "

"even for negative values."

msgstr ""

#: ../Doc/howto/clinic.rst:790 ../Doc/howto/clinic.rst:1266

msgid "``converter``"

msgstr ""

#: ../Doc/howto/clinic.rst:788

msgid ""

"Only supported by the ``object`` converter. Specifies the name of a :ref:`C "

"\"converter function\" <o_ampersand>` to use to convert this object to a "

"native type."

msgstr ""

#: ../Doc/howto/clinic.rst:795

msgid "``encoding``"

msgstr ""

#: ../Doc/howto/clinic.rst:793

msgid ""

"Only supported for strings. Specifies the encoding to use when converting "

"this string from a Python str (Unicode) value into a C ``char *`` value."

msgstr ""

#: ../Doc/howto/clinic.rst:799

msgid "``subclass_of``"

msgstr ""

#: ../Doc/howto/clinic.rst:798

msgid ""

"Only supported for the ``object`` converter. Requires that the Python value "

"be a subclass of a Python type, as expressed in C."

msgstr ""

#: ../Doc/howto/clinic.rst:804 ../Doc/howto/clinic.rst:1238

msgid "``type``"

msgstr ""

#: ../Doc/howto/clinic.rst:802

msgid ""

"Only supported for the ``object`` and ``self`` converters. Specifies the C "

"type that will be used to declare the variable. Default value is ``"

"\"PyObject *\"``."

msgstr ""

#: ../Doc/howto/clinic.rst:810

msgid "``zeroes``"

msgstr ""

#: ../Doc/howto/clinic.rst:807

msgid ""

"Only supported for strings. If true, embedded NUL bytes (``'\\\\0'``) are "

"permitted inside the value. The length of the string will be passed in to "

"the impl function, just after the string parameter, as a parameter named "

"``<parameter_name>_length``."

msgstr ""

#: ../Doc/howto/clinic.rst:812

msgid ""

"Please note, not every possible combination of arguments will work. Usually "

"these arguments are implemented by specific ``PyArg_ParseTuple`` *format "

"units*, with specific behavior. For example, currently you cannot call "

"``unsigned_short`` without also specifying ``bitwise=True``. Although it's "

"perfectly reasonable to think this would work, these semantics don't map to "

"any existing format unit. So Argument Clinic doesn't support it. (Or, at "

"least, not yet.)"

msgstr ""

#: ../Doc/howto/clinic.rst:820

msgid ""

"Below is a table showing the mapping of legacy converters into real Argument "

"Clinic converters. On the left is the legacy converter, on the right is the "

"text you'd replace it with."

msgstr ""

#: ../Doc/howto/clinic.rst:825

msgid "``'B'``"

msgstr ""

#: ../Doc/howto/clinic.rst:825

msgid "``unsigned_char(bitwise=True)``"

msgstr ""

#: ../Doc/howto/clinic.rst:826

msgid "``'b'``"

msgstr ""

#: ../Doc/howto/clinic.rst:826

msgid "``unsigned_char``"

msgstr ""

#: ../Doc/howto/clinic.rst:827

msgid "``'c'``"

msgstr ""