# SOME DESCRIPTIVE TITLE.

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

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

# FIRST AUTHOR <EMAIL@ADDRESS>, 2017.

#

#, fuzzy

msgid ""

msgstr ""

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

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

"POT-Creation-Date: 2018-12-25 10:27+0900\n"

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

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

"Language-Team: LANGUAGE <LL@li.org>\n"

"MIME-Version: 1.0\n"

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

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

"Generated-By: Babel 2.6.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:1246

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:1260

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:1232

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