python-docs-fr/howto/clinic.po

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2001-2016, Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: Python 3.5\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2016-10-30 10:42+0100\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"

#: ../Doc/howto/clinic.rst:3
msgid "Argument Clinic How-To"
msgstr ""

#: ../Doc/howto/clinic.rst:5
msgid "Larry Hastings"
msgstr ""

#: ../Doc/howto/clinic.rst:0
msgid "Abstract"
msgstr "Résumé"

#: ../Doc/howto/clinic.rst:10
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 ""
"Argument Clinic est un préprocesseur pour les fichiers C de CPython. Il "
"permet d'automatiser les tâches répétitives lors de la rédaction du code "
"d'analyse d'arguments pour les modules natifs.  Ce document vous montre "
"comment convertir votre première fonction C de façon à ce qu'elle fonctionne "
"avec Argument Clinic, avant d'introduire des usages plus avancés d'Argument "
"Clinic. "

#: ../Doc/howto/clinic.rst:17
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 CPython 3.5 *could* be totally incompatible "
"and break all your code."
msgstr ""

#: ../Doc/howto/clinic.rst:27
msgid "The Goals Of Argument Clinic"
msgstr "Les objectifs d'Argument Clinic"

#: ../Doc/howto/clinic.rst:29
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:39
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 ""
"Pour que le premier objectif d'Argument Clinic soit atteint, il faut qu'il "
"soit facile à utiliser. Actuellement, travailler avec la bibliothèque "
"d'analyse d'arguments de CPython est une corvée. Il faut maintenir une "
"quantité surprenante d'informations redondantes. En utilisant Argument "
"Clinic, il n'est plus nécessaire de se répéter."

#: ../Doc/howto/clinic.rst:45
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:57
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 ""
"De plus, Argument Clinic doit être suffisamment flexible pour s'accommoder "
"d'approches différentes de l'analyse d'arguments. Il y a des fonctions dans "
"Python dont le traitement des arguments est très étrange ; le but d'Argument "
"Clinic est de les gérer toutes. "

#: ../Doc/howto/clinic.rst:62
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 ""
"Finalement, la motivation première d'Argument Clinic était de fournir des « "
"signatures » pour l'introspection des composants natifs de CPython. "
"Précédemment, les fonctions d'introspection levaient une exception si vous "
"passiez un composant natif. Grâce à Argument Clinic, ce comportement "
"appartient au passé !"

#: ../Doc/howto/clinic.rst:68
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 ""
"En travaillant avec Argument Clinic, il faut garder à l'esprit que plus vous "
"lui donnez de détails, meilleur sera son boulot. Argument Clinic est bien "
"sûr assez simple pour le moment. Mais à mesure qu'il évoluera et deviendra "
"plus sophistiqué, il sera capable de faire beaucoup de choses intéressantes "
"et intelligentes à partir de l'information que vous lui fournissez."

#: ../Doc/howto/clinic.rst:78
msgid "Basic Concepts And Usage"
msgstr "Concepts de base et utilisation"

#: ../Doc/howto/clinic.rst:80
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:85
msgid ""
"Argument Clinic will scan over the file looking for lines that look exactly "
"like this::"
msgstr ""

#: ../Doc/howto/clinic.rst:90
msgid ""
"When it finds one, it reads everything up to a line that looks exactly like "
"this::"
msgstr ""

#: ../Doc/howto/clinic.rst:95
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 ""
"Tout ce qui se trouve entre ces deux lignes est une entrée pour Argument "
"Clinic. Toutes ces lignes, en incluant les commentaires de début et de fin, "
"sont appelées collectivement un « bloc » d'Argument Clinic. "

#: ../Doc/howto/clinic.rst:99
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:110
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 ""
"Si vous exécutez de nouveau Argument Clinic sur ce même fichier, Argument "
"Clinic supprime la vieille sortie, et écrit la nouvelle sortie avec une "
"ligne de somme de contrôle mise à jour. Cependant, si l'entrée n'a pas "
"changé, la sortie ne change pas non plus. "

#: ../Doc/howto/clinic.rst:114
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:119
msgid ""
"For the sake of clarity, here's the terminology we'll use with Argument "
"Clinic:"
msgstr "Par souci de clarté, voilà la terminologie que nous emploierons :"

#: ../Doc/howto/clinic.rst:121
msgid ""
"The first line of the comment (``/*[clinic input]``) is the *start line*."
msgstr ""
"La première ligne du commentaire (``/*[clinic input]``) est la *ligne de "
"début*."

#: ../Doc/howto/clinic.rst:122
msgid ""
"The last line of the initial comment (``[clinic start generated code]*/``) "
"is the *end line*."
msgstr ""
"La dernière ligne du commentaire initial (``[clinic start generated code]*/"
"``) est la *ligne de fin*."

#: ../Doc/howto/clinic.rst:123
msgid ""
"The last line (``/*[clinic end generated code: checksum=...]*/``) is the "
"*checksum line*."
msgstr ""
"La dernière ligne (``/*[clinic end generated code: checksum=...]*/``) est la "
"*ligne de contrôle*. "

#: ../Doc/howto/clinic.rst:124
msgid "In between the start line and the end line is the *input*."
msgstr ""
"On appelle *entrée* ce qui se trouve entre la ligne de début et la ligne de "
"fin."

#: ../Doc/howto/clinic.rst:125
msgid "In between the end line and the checksum line is the *output*."
msgstr ""
"Et on appelle *sortie* ce qui se trouve entre la ligne de fin et la ligne de "
"contrôle."

#: ../Doc/howto/clinic.rst:126
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 ""
"L'ensemble du texte, depuis la ligne de début jusqu'à la ligne de contrôle "
"incluse s'appelle le *bloc*. (Un bloc qui n'a pas encore été traité avec "
"succès par Argument Clinic n'a pas encore de sortie ni de ligne de contrôle "
"mais est quand même considéré comme un bloc)"

#: ../Doc/howto/clinic.rst:133
msgid "Converting Your First Function"
msgstr "Convertissez votre première fonction"

#: ../Doc/howto/clinic.rst:135
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 ""
"La meilleure manière de comprendre le fonctionnement d'Argument Clinic est "
"de convertir une fonction. Voici donc les étapes minimales que vous devez "
"suivre pour convertir une fonction de manière à ce qu'elle fonctionne avec "
"Argument Clinic. Remarquez que pour du code que vous comptez inclure dans "
"CPython, vous devrez certainement pousser plus loin la conversion, en "
"utilisant les concepts avancés que nous verrons plus loin dans ce document "
"(comme ``return converters`` et ``self converters``). Mais concentrons nous "
"pour le moment sur les choses simples."

#: ../Doc/howto/clinic.rst:144
msgid "Let's dive in!"
msgstr "En route !"

#: ../Doc/howto/clinic.rst:146
msgid ""
"Make sure you're working with a freshly updated checkout of the CPython "
"trunk."
msgstr ""
"Assurez-vous que vous travaillez sur une copie récemment mise à jour du code "
"de CPython."

#: ../Doc/howto/clinic.rst:149
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 ""
"Trouvez une fonction native de Python qui fait appel à :c:func:"
"`PyArg_ParseTuple` ou :c:func:`PyArg_ParseTupleAndKeywords`, et n'a pas "
"encore été convertie par Argument Clinic. Pour cet exemple, j'utilise "
"``_pickle.Pickler.dump()``."

#: ../Doc/howto/clinic.rst:154
msgid ""
"If the call to the ``PyArg_Parse`` function uses any of the following format "
"units:"
msgstr "Si l'appel à ``PyArg_Parse`` utilise l'un des formats suivants :"

#: ../Doc/howto/clinic.rst:166
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:171
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 ""
"Par ailleurs, si la fonction a des appels multiples à :c:func:"
"`PyArg_ParseTuple` ou :c:func:`PyArg_ParseTupleAndKeywords` dans lesquels "
"elle permet différents types pour les mêmes arguments, il n'est probablement "
"pas possible de la convertir pour Argument Clinic. Argument Clinic ne gère "
"pas les fonctions génériques ou les paramètres polymorphes."

#: ../Doc/howto/clinic.rst:178
msgid "Add the following boilerplate above the function, creating our block::"
msgstr ""
"Ajoutez les lignes standard suivantes au-dessus de votre fonction pour créer "
"notre bloc : ::"

#: ../Doc/howto/clinic.rst:183
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 ""
"Coupez la *docstring* et collez-la entre les lignes commençant par "
"``[clinic]``, en enlevant tout le bazar qui en fait une chaîne de caractères "
"correcte en C. Une fois que c'est fait, vous devez avoir seulement le texte, "
"aligné à gauche, sans ligne plus longue que 80 caractères (Argument Clinic "
"préserve l'indentation à l'intérieur de la *docstring*)."

#: ../Doc/howto/clinic.rst:189
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:195 ../Doc/howto/clinic.rst:216
#: ../Doc/howto/clinic.rst:240 ../Doc/howto/clinic.rst:294
#: ../Doc/howto/clinic.rst:334 ../Doc/howto/clinic.rst:361
#: ../Doc/howto/clinic.rst:470 ../Doc/howto/clinic.rst:522
msgid "Sample::"
msgstr "Échantillon : ::"

#: ../Doc/howto/clinic.rst:201
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 ""
"Si votre *docstring* ne contient pas de ligne « résumé », Argument Clinic va "
"se plaindre. Assurons-nous donc qu'il y en a une. La ligne « résumé » doit "
"être un paragraphe consistant en une seule ligne de 80 colonnes au début de "
"la *docstring*."

#: ../Doc/howto/clinic.rst:206
msgid ""
"(Our example docstring consists solely of a summary line, so the sample code "
"doesn't have to change for this step.)"
msgstr ""
"Dans notre exemple, la *docstring* est seulement composée d'une ligne de "
"résumé, donc le code ne change pas à cette étape."

#: ../Doc/howto/clinic.rst:209
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:224
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 ""
"Si c'est la première fois que ce module ou cette classe est utilisée avec "
"Argument Clinic dans ce fichier C, vous devez déclarer votre module et/ou "
"votre classe. Pour suivre de bonnes pratiques avec Argument Clinic, il vaut "
"mieux faire ces déclaration quelque part en tête du fichier C, comme les "
"fichiers inclus et les statiques (dans cet extrait, nous montrons les deux "
"blocs à côté l'un de l'autre)."

#: ../Doc/howto/clinic.rst:232
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 ""
"Le nom de la classe et du module doivent être les mêmes que ceux vus par "
"Python. Selon le cas, référez-vous à :c:type:`PyModuleDef` ou :c:type:"
"`PyTypeObject`"

#: ../Doc/howto/clinic.rst:236
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 ""
"Quand vous déclarez une classe, vous devez aussi spécifier deux aspects de "
"son type en C: la déclaration de type que vous utiliseriez pour un pointeur "
"vers une instance de cette classe et un pointeur vers le :c:type:"
"`PyTypeObject` de cette classe."

#: ../Doc/howto/clinic.rst:256
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 ""
"Déclarez chacun des paramètres de la fonction. Chaque paramètre doit être "
"sur une ligne séparée. Tous les paramètres doivent être indentés par rapport "
"au nom de la fonction et à la *docstring*."

#: ../Doc/howto/clinic.rst:260
msgid "The general form of these parameter lines is as follows::"
msgstr ""

#: ../Doc/howto/clinic.rst:264
msgid "If the parameter has a default value, add that after the converter::"
msgstr ""

#: ../Doc/howto/clinic.rst:269
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 ""
"Argument Clinic peut traiter les « valeurs par défaut » de manière assez "
"sophistiquée; voyez :ref:`la section ci-dessous sur les valeurs par défaut "
"<default_values>` pour plus de détails."

#: ../Doc/howto/clinic.rst:273
msgid "Add a blank line below the parameters."
msgstr "Ajoutez une ligne vide sous les paramètres."

#: ../Doc/howto/clinic.rst:275
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:282
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 ""
"Pour chaque paramètre, copiez l'« unité de format » de ce paramètre à partir "
"de l'argument de ``PyArg_Parse()`` et spécifiez *ça* comme convertisseur, "
"entre guillemets. (l'« unité de format » est le nom formel pour la partie du "
"paramètre ``format``, de un à trois caractères, qui indique à la fonction "
"d'analyse d'arguments quel est le type de la variable et comment la "
"convertir. Pour plus d'information sur les unités de format, voyez :ref:`arg-"
"parsing`.)"

#: ../Doc/howto/clinic.rst:291
msgid ""
"For multicharacter format units like ``z#``, use the entire two-or-three "
"character string."
msgstr ""
"Pour des unités de format de plusieurs caractères, comme ``z#``, utilisez "
"l'ensemble des 2 ou 3 caractères de la chaîne. "

#: ../Doc/howto/clinic.rst:309
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 ""
"Si votre fonction a le caractère ``|`` dans son format, parce que certains "
"paramètres ont des valeurs par défaut, vous pouvez l'ignorer. Argument "
"Clinic infère quels paramètres sont optionnels selon s'ils ont ou non une "
"valeur par défaut."

#: ../Doc/howto/clinic.rst:314
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 ""
"Si votre fonction a le caractère ``$`` dans son format, parce qu'elle "
"n'accepte que des arguments nommés, spécifiez ``*`` sur une ligne à part, "
"avant le premier argument nommé, avec la même indentation que les lignes de "
"paramètres."

#: ../Doc/howto/clinic.rst:319
msgid "(``_pickle.Pickler.dump`` has neither, so our sample is unchanged.)"
msgstr ""
"(``_pickle.Pickler.dump`` n'a ni l'un ni l'autre, donc notre exemple est "
"inchangé.)"

#: ../Doc/howto/clinic.rst:322
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 ""
"Si la fonction C existante appelle :c:func:`PyArg_ParseTuple` (et pas :c:"
"func:`PyArg_ParseTupleAndKeywords`), alors tous ses arguments sont "
"uniquement positionnels. "

#: ../Doc/howto/clinic.rst:326
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 ""
"Pour marquer tous les paramètres comme uniquement positionnels dans Argument "
"Clinic, ajoutez ``/`` sur une ligne à part après le dernier paramètre, avec "
"la même indentation que les lignes de paramètres."

#: ../Doc/howto/clinic.rst:330
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 ""
"Pour le moment, c'est tout ou rien ; soit tous les paramètres sont "
"uniquement positionnels, ou aucun ne l'est. (Dans le futur, Argument Clinic "
"supprimera peut être cette restriction.)"

#: ../Doc/howto/clinic.rst:350
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 ""
"Il est utile d'ajouter une *docstring* pour chaque paramètre, mais c'est "
"optionnel; vous pouvez passer cette étape si vous préférez."

#: ../Doc/howto/clinic.rst:354
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 ""
"Voici comment ajouter la *docstring* d'un paramètre. La première ligne doit "
"être plus indentée que la définition du paramètre. La marge gauche de cette "
"première ligne établit la marge gauche pour l'ensemble de la *docstring* de "
"ce paramètre; tout le texte que vous écrivez sera indenté de cette quantité. "
"Vous pouvez écrire autant de texte que vous le souhaitez, sur plusieurs "
"lignes."

#: ../Doc/howto/clinic.rst:378
msgid ""
"Save and close the file, then run ``Tools/clinic/clinic.py`` on it. With "
"luck everything worked and your block now has output!  Reopen the file in "
"your text editor to see::"
msgstr ""

#: ../Doc/howto/clinic.rst:406
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 ""
"Bien sûr, si Argument Clinic n'a pas produit de sortie, c'est qu'il a "
"rencontré une erreur dans votre entrée. Corrigez vos erreurs et réessayez "
"jusqu'à ce qu'Argument Clinic traite votre fichier sans problème."

#: ../Doc/howto/clinic.rst:410
msgid ""
"Double-check that the argument-parsing code Argument Clinic generated looks "
"basically the same as the existing code."
msgstr ""
"Vérifiez bien que le code d'analyse d'argument généré par Argument Clinic "
"ressemble bien au code existant."

#: ../Doc/howto/clinic.rst:413
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 ""
"Assurez vous premièrement que les deux codes utilisent la même fonction pour "
"analyser les arguments. Le code existant doit appeler soit :c:func:"
"`PyArg_ParseTuple` soit :c:func:`PyArg_ParseTupleAndKeywords`; assurez vous "
"que le code généré par Argument Clinic appelle *exactement* la même fonction."

#: ../Doc/howto/clinic.rst:419
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 ""
"Deuxièmement, la chaîne de caractère du format passée dans :c:func:"
"`PyArg_ParseTuple` ou :c:func:`PyArg_ParseTupleAndKeywords` doit être "
"*exactement* la même que celle écrite à la main, jusqu'aux deux points ou au "
"point virgule."

#: ../Doc/howto/clinic.rst:424
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:429
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 ""
"Troisièmement, pour des paramètres dont l'unité de format nécessite deux "
"arguments (comme une variable de longueur, ou une chaîne d'encodage, ou un "
"pointeur vers une fonction de conversion), assurez vous que ce deuxième "
"argument est *exactement* le même entre les deux invocations."

#: ../Doc/howto/clinic.rst:434
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 ""
"Quatrièmement, à l'intérieur de la section sortie du bloc, vous trouverez "
"une macro pré-processeur qui définit les structures statiques :c:type:"
"`PyMethodDef` appropriées pour ce module natif : ::"

#: ../Doc/howto/clinic.rst:441
msgid ""
"This static structure should be *exactly* the same as the existing static :c:"
"type:`PyMethodDef` structure for this builtin."
msgstr ""
"Cette structure statique doit être *exactement* la même que la structure "
"statique :c:type:`PyMethodDef` existante pour ce module natif."

#: ../Doc/howto/clinic.rst:444
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 ""
"Si l'un de ces éléments diffère *de quelque façon que se soit*, ajustez la "
"spécification de fonction d'Argument Clinic et exécutez de nouveau ``Tools/"
"clinic/clinic.py`` jusqu'à ce qu'elles soient identiques."

#: ../Doc/howto/clinic.rst:449
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 ""
"Notez que la dernière ligne de cette sortie est la déclaration de votre "
"fonction ``impl``. C'est là que va l'implémentation de la fonction native. "
"Supprimez le prototype de la fonction que vous modifiez, mais laissez "
"l'accolade ouverte. Maintenant, supprimez tout le code d'analyse d'argument "
"et les déclarations de toutes les variables auxquelles il assigne les "
"arguments. Vous voyez que désormais, les arguments Python sont ceux de cette "
"fonction  ``impl``; si l'implémentation utilise des noms différents pour ces "
"variables, corrigez-les."

#: ../Doc/howto/clinic.rst:457
msgid ""
"Let's reiterate, just because it's kind of weird.  Your code should now look "
"like this::"
msgstr ""
"Comme c'est un peu bizarre, ça vaut la peine de répéter. Votre fonction doit "
"ressembler à ça : ::"

#: ../Doc/howto/clinic.rst:466
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:511
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 ""
"Vous vous souvenez de la macro avec la structure :c:type:`PyMethodDef` pour "
"cette fonction ? Trouvez la structure :c:type:`PyMethodDef` existante pour "
"cette fonction et remplacez là par une référence à cette macro. (Si la "
"fonction native est définie au niveau d'un module, vous le trouverez "
"certainement vers la fin du fichier; s'il s'agît d'une méthode de classe, se "
"sera sans doute plus bas, mais relativement près de l'implémentation.)"

#: ../Doc/howto/clinic.rst:518
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 ""
"Notez que le corps de la macro contient une virgule finale. Donc, lorsque "
"vous remplacez la structure statique :c:type:`PyMethodDef` par la macro, "
"*n'ajoutez pas* de virgule à la fin."

#: ../Doc/howto/clinic.rst:531
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 ""
"Compilez, puis faites tourner les portions idoines de la suite de tests de "
"régressions. Ce changement ne doit introduire aucun nouveau message d'erreur "
"ou avertissement à la compilation, et il ne devrait y avoir aucun changement "
"visible de l'extérieur au comportement de Python."

#: ../Doc/howto/clinic.rst:535
msgid ""
"Well, except for one difference: ``inspect.signature()`` run on your "
"function should now provide a valid signature!"
msgstr ""
"Enfin, à part pour une différence : si vous exécutez ``inspect.signature()`` "
"sur votre fonction, vous obtiendrez maintenant une signature valide !"

#: ../Doc/howto/clinic.rst:538
msgid ""
"Congratulations, you've ported your first function to work with Argument "
"Clinic!"
msgstr ""
"Félicitations, vous avez adapté votre première fonction pour qu'elle utilise "
"Argument Clinic !"

#: ../Doc/howto/clinic.rst:541
msgid "Advanced Topics"
msgstr ""

#: ../Doc/howto/clinic.rst:543
msgid ""
"Now that you've had some experience working with Argument Clinic, it's time "
"for some advanced topics."
msgstr ""

#: ../Doc/howto/clinic.rst:548
msgid "Symbolic default values"
msgstr ""

#: ../Doc/howto/clinic.rst:550
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:553
msgid "Numeric constants (integer and float)"
msgstr ""

#: ../Doc/howto/clinic.rst:554
msgid "String constants"
msgstr "Chaînes constantes"

#: ../Doc/howto/clinic.rst:555
msgid "``True``, ``False``, and ``None``"
msgstr ""

#: ../Doc/howto/clinic.rst:556
msgid ""
"Simple symbolic constants like ``sys.maxsize``, which must start with the "
"name of the module"
msgstr ""

#: ../Doc/howto/clinic.rst:559
msgid ""
"In case you're curious, this is implemented in  ``from_builtin()`` in ``Lib/"
"inspect.py``."
msgstr ""

#: ../Doc/howto/clinic.rst:562
msgid ""
"(In the future, this may need to get even more elaborate, to allow full "
"expressions like ``CONSTANT - 1``.)"
msgstr ""

#: ../Doc/howto/clinic.rst:567
msgid "Renaming the C functions and variables generated by Argument Clinic"
msgstr ""

#: ../Doc/howto/clinic.rst:569
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:577
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:585
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:589
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:603
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:606
msgid "You can use this to rename the ``self`` parameter too!"
msgstr ""

#: ../Doc/howto/clinic.rst:610
msgid "Converting functions using PyArg_UnpackTuple"
msgstr ""

#: ../Doc/howto/clinic.rst:612
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:618
msgid ""
"Currently the generated code will use :c:func:`PyArg_ParseTuple`, but this "
"will change soon."
msgstr ""

#: ../Doc/howto/clinic.rst:622
msgid "Optional Groups"
msgstr ""

#: ../Doc/howto/clinic.rst:624
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:631
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:643
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:651
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:660
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:689
msgid "Notes:"
msgstr "Notes :"

#: ../Doc/howto/clinic.rst:691
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:702
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:705
msgid ""
"In the case of ambiguity, the argument parsing code favors parameters on the "
"left (before the required parameters)."
msgstr ""

#: ../Doc/howto/clinic.rst:708
msgid "Optional groups can only contain positional-only parameters."
msgstr ""

#: ../Doc/howto/clinic.rst:710
msgid ""
"Optional groups are *only* intended for legacy code.  Please do not use "
"optional groups for new code."
msgstr ""

#: ../Doc/howto/clinic.rst:715
msgid "Using real Argument Clinic converters, instead of \"legacy converters\""
msgstr ""

#: ../Doc/howto/clinic.rst:717
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:724
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:728
msgid ""
"The proper converters are far easier to read and clearer in their intent."
msgstr ""

#: ../Doc/howto/clinic.rst:729
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:732
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:736
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:739
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:745
msgid ""
"All arguments to Argument Clinic converters are keyword-only. All Argument "
"Clinic converters accept the following arguments:"
msgstr ""

#: ../Doc/howto/clinic.rst:753 ../Doc/howto/clinic.rst:1223
msgid "``c_default``"
msgstr ""

#: ../Doc/howto/clinic.rst:749
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:758
msgid "``annotation``"
msgstr ""

#: ../Doc/howto/clinic.rst:756
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:760
msgid ""
"In addition, some converters accept additional arguments.  Here is a list of "
"these arguments, along with their meanings:"
msgstr ""

#: ../Doc/howto/clinic.rst:769
msgid "``accept``"
msgstr ""

#: ../Doc/howto/clinic.rst:764
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:769
msgid "To accept ``None``, add ``NoneType`` to this set."
msgstr ""

#: ../Doc/howto/clinic.rst:774
msgid "``bitwise``"
msgstr ""

#: ../Doc/howto/clinic.rst:772
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:779 ../Doc/howto/clinic.rst:1237
msgid "``converter``"
msgstr ""

#: ../Doc/howto/clinic.rst:777
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:784
msgid "``encoding``"
msgstr "``encoding``"

#: ../Doc/howto/clinic.rst:782
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:788
msgid "``subclass_of``"
msgstr ""

#: ../Doc/howto/clinic.rst:787
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:793 ../Doc/howto/clinic.rst:1209
msgid "``type``"
msgstr "``type``"

#: ../Doc/howto/clinic.rst:791
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:799
msgid "``zeroes``"
msgstr ""

#: ../Doc/howto/clinic.rst:796
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:801
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:809
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:814
msgid "``'B'``"
msgstr "``'B'``"

#: ../Doc/howto/clinic.rst:814
msgid "``unsigned_char(bitwise=True)``"
msgstr ""

#: ../Doc/howto/clinic.rst:815
msgid "``'b'``"
msgstr "``'b'``"

#: ../Doc/howto/clinic.rst:815
msgid "``unsigned_char``"
msgstr ""

#: ../Doc/howto/clinic.rst:816
msgid "``'c'``"
msgstr "``'c'``"

#: ../Doc/howto/clinic.rst:816
msgid "``char``"
msgstr ""

#: ../Doc/howto/clinic.rst:817
msgid "``'C'``"
msgstr ""

#: ../Doc/howto/clinic.rst:817
msgid "``int(accept={str})``"
msgstr ""

#: ../Doc/howto/clinic.rst:818
msgid "``'d'``"
msgstr "``'d'``"

#: ../Doc/howto/clinic.rst:818
msgid "``double``"
msgstr ""

#: ../Doc/howto/clinic.rst:819
msgid "``'D'``"
msgstr "``'D'``"

#: ../Doc/howto/clinic.rst:819
msgid "``Py_complex``"
msgstr ""

#: ../Doc/howto/clinic.rst:820
msgid "``'es'``"
msgstr ""

#: ../Doc/howto/clinic.rst:820
msgid "``str(encoding='name_of_encoding')``"
msgstr ""

#: ../Doc/howto/clinic.rst:821
msgid "``'es#'``"
msgstr ""

#: ../Doc/howto/clinic.rst:821
msgid "``str(encoding='name_of_encoding', zeroes=True)``"
msgstr ""

#: ../Doc/howto/clinic.rst:822
msgid "``'et'``"
msgstr ""

#: ../Doc/howto/clinic.rst:822
msgid "``str(encoding='name_of_encoding', accept={bytes, bytearray, str})``"
msgstr ""

#: ../Doc/howto/clinic.rst:823
msgid "``'et#'``"
msgstr ""

#: ../Doc/howto/clinic.rst:823
msgid ""
"``str(encoding='name_of_encoding', accept={bytes, bytearray, str}, "
"zeroes=True)``"
msgstr ""

#: ../Doc/howto/clinic.rst:824
msgid "``'f'``"
msgstr "``'f'``"

#: ../Doc/howto/clinic.rst:824
msgid "``float``"
msgstr ""

#: ../Doc/howto/clinic.rst:825
msgid "``'h'``"
msgstr "``'h'``"

#: ../Doc/howto/clinic.rst:825
msgid "``short``"
msgstr ""

#: ../Doc/howto/clinic.rst:826
msgid "``'H'``"
msgstr "``'H'``"

#: ../Doc/howto/clinic.rst:826
msgid "``unsigned_short(bitwise=True)``"
msgstr ""

#: ../Doc/howto/clinic.rst:827
msgid "``'i'``"
msgstr "``'i'``"

#: ../Doc/howto/clinic.rst:827
msgid "``int``"
msgstr "``int``"

#: ../Doc/howto/clinic.rst:828
msgid "``'I'``"
msgstr "``'I'``"

#: ../Doc/howto/clinic.rst:828
msgid "``unsigned_int(bitwise=True)``"
msgstr ""

#: ../Doc/howto/clinic.rst:829
msgid "``'k'``"
msgstr ""

#: ../Doc/howto/clinic.rst:829
msgid "``unsigned_long(bitwise=True)``"
msgstr ""

#: ../Doc/howto/clinic.rst:830
msgid "``'K'``"
msgstr ""

#: ../Doc/howto/clinic.rst:830
msgid "``unsigned_PY_LONG_LONG(bitwise=True)``"
msgstr ""

#: ../Doc/howto/clinic.rst:831
msgid "``'l'``"
msgstr "``'l'``"

#: ../Doc/howto/clinic.rst:831
msgid "``long``"
msgstr "``long``"

#: ../Doc/howto/clinic.rst:832
msgid "``'L'``"
msgstr "``'L'``"

#: ../Doc/howto/clinic.rst:832
msgid "``PY_LONG_LONG``"
msgstr ""

#: ../Doc/howto/clinic.rst:833
msgid "``'n'``"
msgstr "``'n'``"

#: ../Doc/howto/clinic.rst:833
msgid "``Py_ssize_t``"
msgstr ""

#: ../Doc/howto/clinic.rst:834
msgid "``'O'``"
msgstr ""

#: ../Doc/howto/clinic.rst:834
msgid "``object``"
msgstr ""

#: ../Doc/howto/clinic.rst:835
msgid "``'O!'``"
msgstr ""

#: ../Doc/howto/clinic.rst:835
msgid "``object(subclass_of='&PySomething_Type')``"
msgstr ""

#: ../Doc/howto/clinic.rst:836
msgid "``'O&'``"
msgstr ""

#: ../Doc/howto/clinic.rst:836
msgid "``object(converter='name_of_c_function')``"
msgstr ""

#: ../Doc/howto/clinic.rst:837
msgid "``'p'``"
msgstr ""

#: ../Doc/howto/clinic.rst:837
msgid "``bool``"
msgstr ""

#: ../Doc/howto/clinic.rst:838
msgid "``'S'``"
msgstr "``'S'``"

#: ../Doc/howto/clinic.rst:838
msgid "``PyBytesObject``"
msgstr ""

#: ../Doc/howto/clinic.rst:839
msgid "``'s'``"
msgstr "``'s'``"

#: ../Doc/howto/clinic.rst:839
msgid "``str``"
msgstr ""

#: ../Doc/howto/clinic.rst:840
msgid "``'s#'``"
msgstr ""

#: ../Doc/howto/clinic.rst:840
msgid "``str(zeroes=True)``"
msgstr ""

#: ../Doc/howto/clinic.rst:841
msgid "``'s*'``"
msgstr ""

#: ../Doc/howto/clinic.rst:841
msgid "``Py_buffer(accept={buffer, str})``"
msgstr ""

#: ../Doc/howto/clinic.rst:842
msgid "``'U'``"
msgstr "``'U'``"

#: ../Doc/howto/clinic.rst:842
msgid "``unicode``"
msgstr ""

#: ../Doc/howto/clinic.rst:843
msgid "``'u'``"
msgstr "``'u'``"

#: ../Doc/howto/clinic.rst:843
msgid "``Py_UNICODE``"
msgstr ""

#: ../Doc/howto/clinic.rst:844
msgid "``'u#'``"
msgstr ""

#: ../Doc/howto/clinic.rst:844
msgid "``Py_UNICODE(zeroes=True)``"
msgstr ""

#: ../Doc/howto/clinic.rst:845
msgid "``'w*'``"
msgstr ""

#: ../Doc/howto/clinic.rst:845
msgid "``Py_buffer(accept={rwbuffer})``"
msgstr ""

#: ../Doc/howto/clinic.rst:846
msgid "``'Y'``"
msgstr ""

#: ../Doc/howto/clinic.rst:846
msgid "``PyByteArrayObject``"
msgstr ""

#: ../Doc/howto/clinic.rst:847
msgid "``'y'``"
msgstr ""

#: ../Doc/howto/clinic.rst:847
msgid "``str(accept={bytes})``"
msgstr ""

#: ../Doc/howto/clinic.rst:848
msgid "``'y#'``"
msgstr ""

#: ../Doc/howto/clinic.rst:848
msgid "``str(accept={robuffer}, zeroes=True)``"
msgstr ""

#: ../Doc/howto/clinic.rst:849
msgid "``'y*'``"
msgstr ""

#: ../Doc/howto/clinic.rst:849
msgid "``Py_buffer``"
msgstr ""

#: ../Doc/howto/clinic.rst:850
msgid "``'Z'``"
msgstr ""

#: ../Doc/howto/clinic.rst:850
msgid "``Py_UNICODE(accept={str, NoneType})``"
msgstr ""

#: ../Doc/howto/clinic.rst:851
msgid "``'Z#'``"
msgstr ""

#: ../Doc/howto/clinic.rst:851
msgid "``Py_UNICODE(accept={str, NoneType}, zeroes=True)``"
msgstr ""

#: ../Doc/howto/clinic.rst:852
msgid "``'z'``"
msgstr ""

#: ../Doc/howto/clinic.rst:852
msgid "``str(accept={str, NoneType})``"
msgstr ""

#: ../Doc/howto/clinic.rst:853
msgid "``'z#'``"
msgstr ""

#: ../Doc/howto/clinic.rst:853
msgid "``str(accept={str, NoneType}, zeroes=True)``"
msgstr ""

#: ../Doc/howto/clinic.rst:854
msgid "``'z*'``"
msgstr ""

#: ../Doc/howto/clinic.rst:854
msgid "``Py_buffer(accept={buffer, str, NoneType})``"
msgstr ""

#: ../Doc/howto/clinic.rst:857
msgid ""
"As an example, here's our sample ``pickle.Pickler.dump`` using the proper "
"converter::"
msgstr ""

#: ../Doc/howto/clinic.rst:870
msgid ""
"Argument Clinic will show you all the converters it has available.  For each "
"converter it'll show you all the parameters it accepts, along with the "
"default value for each parameter. Just run ``Tools/clinic/clinic.py --"
"converters`` to see the full list."
msgstr ""

#: ../Doc/howto/clinic.rst:876
msgid "Py_buffer"
msgstr ""

#: ../Doc/howto/clinic.rst:878
msgid ""
"When using the ``Py_buffer`` converter (or the ``'s*'``, ``'w*'``, ``'*y'``, "
"or ``'z*'`` legacy converters), you *must* not call :c:func:"
"`PyBuffer_Release` on the provided buffer. Argument Clinic generates code "
"that does it for you (in the parsing function)."
msgstr ""

#: ../Doc/howto/clinic.rst:886
msgid "Advanced converters"
msgstr ""

#: ../Doc/howto/clinic.rst:888
msgid ""
"Remember those format units you skipped for your first time because they "
"were advanced?  Here's how to handle those too."
msgstr ""

#: ../Doc/howto/clinic.rst:891
msgid ""
"The trick is, all those format units take arguments--either conversion "
"functions, or types, or strings specifying an encoding. (But \"legacy "
"converters\" don't support arguments.  That's why we skipped them for your "
"first function.)  The argument you specified to the format unit is now an "
"argument to the converter; this argument is either ``converter`` (for "
"``O&``), ``subclass_of`` (for ``O!``), or ``encoding`` (for all the format "
"units that start with ``e``)."
msgstr ""

#: ../Doc/howto/clinic.rst:899
msgid ""
"When using ``subclass_of``, you may also want to use the other custom "
"argument for ``object()``: ``type``, which lets you set the type actually "
"used for the parameter.  For example, if you want to ensure that the object "
"is a subclass of ``PyUnicode_Type``, you probably want to use the converter "
"``object(type='PyUnicodeObject *', subclass_of='&PyUnicode_Type')``."
msgstr ""

#: ../Doc/howto/clinic.rst:905
msgid ""
"One possible problem with using Argument Clinic: it takes away some possible "
"flexibility for the format units starting with ``e``.  When writing a "
"``PyArg_Parse`` call by hand, you could theoretically decide at runtime what "
"encoding string to pass in to :c:func:`PyArg_ParseTuple`.   But now this "
"string must be hard-coded at Argument-Clinic-preprocessing-time.  This "
"limitation is deliberate; it made supporting this format unit much easier, "
"and may allow for future optimizations. This restriction doesn't seem "
"unreasonable; CPython itself always passes in static hard-coded encoding "
"strings for parameters whose format units start with ``e``."
msgstr ""

#: ../Doc/howto/clinic.rst:918
msgid "Parameter default values"
msgstr ""

#: ../Doc/howto/clinic.rst:920
msgid ""
"Default values for parameters can be any of a number of values. At their "
"simplest, they can be string, int, or float literals::"
msgstr ""

#: ../Doc/howto/clinic.rst:927
msgid "They can also use any of Python's built-in constants::"
msgstr ""

#: ../Doc/howto/clinic.rst:933
msgid ""
"There's also special support for a default value of ``NULL``, and for simple "
"expressions, documented in the following sections."
msgstr ""

#: ../Doc/howto/clinic.rst:938
msgid "The ``NULL`` default value"
msgstr ""

#: ../Doc/howto/clinic.rst:940
msgid ""
"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 "
"initialized to ``Py_None``.  For convenience's sakes, there's a special "
"value called ``NULL`` for just this reason: from Python's perspective it "
"behaves like a default value of ``None``, but the C variable is initialized "
"with ``NULL``."
msgstr ""

#: ../Doc/howto/clinic.rst:948
msgid "Expressions specified as default values"
msgstr ""

#: ../Doc/howto/clinic.rst:950
msgid ""
"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 "
"on objects.  However, this support isn't exactly simple, because of some non-"
"obvious semantics."
msgstr ""

#: ../Doc/howto/clinic.rst:955
msgid "Consider the following example::"
msgstr ""

#: ../Doc/howto/clinic.rst:959
msgid ""
"``sys.maxsize`` can have different values on different platforms.  Therefore "
"Argument Clinic can't simply evaluate that expression locally and hard-code "
"it in C.  So it stores the default in such a way that it will get evaluated "
"at runtime, when the user asks for the function's signature."
msgstr ""

#: ../Doc/howto/clinic.rst:964
msgid ""
"What namespace is available when the expression is evaluated?  It's "
"evaluated in the context of the module the builtin came from.  So, if your "
"module has an attribute called \"``max_widgets``\", you may simply use it::"
msgstr ""

#: ../Doc/howto/clinic.rst:970
msgid ""
"If the symbol isn't found in the current module, it fails over to looking in "
"``sys.modules``.  That's how it can find ``sys.maxsize`` for example.  "
"(Since you don't know in advance what modules the user will load into their "
"interpreter, it's best to restrict yourself to modules that are preloaded by "
"Python itself.)"
msgstr ""

#: ../Doc/howto/clinic.rst:975
msgid ""
"Evaluating default values only at runtime means Argument Clinic can't "
"compute the correct equivalent C default value.  So you need to tell it "
"explicitly. When you use an expression, you must also specify the equivalent "
"expression in C, using the ``c_default`` parameter to the converter::"
msgstr ""

#: ../Doc/howto/clinic.rst:982
msgid ""
"Another complication: Argument Clinic can't know in advance whether or not "
"the expression you supply is valid.  It parses it to make sure it looks "
"legal, but it can't *actually* know.  You must be very careful when using "
"expressions to specify values that are guaranteed to be valid at runtime!"
msgstr ""

#: ../Doc/howto/clinic.rst:987
msgid ""
"Finally, because expressions must be representable as static C values, there "
"are many restrictions on legal expressions.  Here's a list of Python "
"features you're not permitted to use:"
msgstr ""

#: ../Doc/howto/clinic.rst:991
msgid "Function calls."
msgstr ""

#: ../Doc/howto/clinic.rst:992
msgid "Inline if statements (``3 if foo else 5``)."
msgstr ""

#: ../Doc/howto/clinic.rst:993
msgid "Automatic sequence unpacking (``*[1, 2, 3]``)."
msgstr ""

#: ../Doc/howto/clinic.rst:994
msgid "List/set/dict comprehensions and generator expressions."
msgstr ""

#: ../Doc/howto/clinic.rst:995
msgid "Tuple/list/set/dict literals."
msgstr ""

#: ../Doc/howto/clinic.rst:1000
msgid "Using a return converter"
msgstr ""

#: ../Doc/howto/clinic.rst:1002
msgid ""
"By default the impl function Argument Clinic generates for you returns "
"``PyObject *``. But your C function often computes some C type, then "
"converts it into the ``PyObject *`` at the last moment.  Argument Clinic "
"handles converting your inputs from Python types into native C types--why "
"not have it convert your return value from a native C type into a Python "
"type too?"
msgstr ""

#: ../Doc/howto/clinic.rst:1008
msgid ""
"That's what a \"return converter\" does.  It changes your impl function to "
"return some C type, then adds code to the generated (non-impl) function to "
"handle converting that value into the appropriate ``PyObject *``."
msgstr ""

#: ../Doc/howto/clinic.rst:1012
msgid ""
"The syntax for return converters is similar to that of parameter converters. "
"You specify the return converter like it was a return annotation on the "
"function itself.  Return converters behave much the same as parameter "
"converters; they take arguments, the arguments are all keyword-only, and if "
"you're not changing any of the default arguments you can omit the "
"parentheses."
msgstr ""

#: ../Doc/howto/clinic.rst:1018
msgid ""
"(If you use both ``\"as\"`` *and* a return converter for your function, the "
"``\"as\"`` should come before the return converter.)"
msgstr ""

#: ../Doc/howto/clinic.rst:1021
msgid ""
"There's one additional complication when using return converters: how do you "
"indicate an error has occurred?  Normally, a function returns a valid (non-"
"``NULL``) pointer for success, and ``NULL`` for failure.  But if you use an "
"integer return converter, all integers are valid.  How can Argument Clinic "
"detect an error?  Its solution: each return converter implicitly looks for a "
"special value that indicates an error.  If you return that value, and an "
"error has been set (``PyErr_Occurred()`` returns a true value), then the "
"generated code will propagate the error.  Otherwise it will encode the value "
"you return like normal."
msgstr ""

#: ../Doc/howto/clinic.rst:1030
msgid "Currently Argument Clinic supports only a few return converters::"
msgstr ""

#: ../Doc/howto/clinic.rst:1043
msgid ""
"None of these take parameters.  For the first three, return -1 to indicate "
"error.  For ``DecodeFSDefault``, the return type is ``char *``; return a "
"NULL pointer to indicate an error."
msgstr ""

#: ../Doc/howto/clinic.rst:1047
msgid ""
"(There's also an experimental ``NoneType`` converter, which lets you return "
"``Py_None`` on success or ``NULL`` on failure, without having to increment "
"the reference count on ``Py_None``.  I'm not sure it adds enough clarity to "
"be worth using.)"
msgstr ""

#: ../Doc/howto/clinic.rst:1052
msgid ""
"To see all the return converters Argument Clinic supports, along with their "
"parameters (if any), just run ``Tools/clinic/clinic.py --converters`` for "
"the full list."
msgstr ""

#: ../Doc/howto/clinic.rst:1058
msgid "Cloning existing functions"
msgstr ""

#: ../Doc/howto/clinic.rst:1060
msgid ""
"If you have a number of functions that look similar, you may be able to use "
"Clinic's \"clone\" feature.  When you clone an existing function, you reuse:"
msgstr ""

#: ../Doc/howto/clinic.rst:1064
msgid "its parameters, including"
msgstr ""

#: ../Doc/howto/clinic.rst:1066
msgid "their names,"
msgstr ""

#: ../Doc/howto/clinic.rst:1068
msgid "their converters, with all parameters,"
msgstr ""

#: ../Doc/howto/clinic.rst:1070
msgid "their default values,"
msgstr ""

#: ../Doc/howto/clinic.rst:1072
msgid "their per-parameter docstrings,"
msgstr ""

#: ../Doc/howto/clinic.rst:1074
msgid ""
"their *kind* (whether they're positional only, positional or keyword, or "
"keyword only), and"
msgstr ""

#: ../Doc/howto/clinic.rst:1077
msgid "its return converter."
msgstr ""

#: ../Doc/howto/clinic.rst:1079
msgid ""
"The only thing not copied from the original function is its docstring; the "
"syntax allows you to specify a new docstring."
msgstr ""

#: ../Doc/howto/clinic.rst:1082
msgid "Here's the syntax for cloning a function::"
msgstr ""

#: ../Doc/howto/clinic.rst:1090
msgid ""
"(The functions can be in different modules or classes.  I wrote ``module."
"class`` in the sample just to illustrate that you must use the full path to "
"*both* functions.)"
msgstr ""

#: ../Doc/howto/clinic.rst:1094
msgid ""
"Sorry, there's no syntax for partially-cloning a function, or cloning a "
"function then modifying it.  Cloning is an all-or nothing proposition."
msgstr ""

#: ../Doc/howto/clinic.rst:1097
msgid ""
"Also, the function you are cloning from must have been previously defined in "
"the current file."
msgstr ""

#: ../Doc/howto/clinic.rst:1101
msgid "Calling Python code"
msgstr ""

#: ../Doc/howto/clinic.rst:1103
msgid ""
"The rest of the advanced topics require you to write Python code which lives "
"inside your C file and modifies Argument Clinic's runtime state.  This is "
"simple: you simply define a Python block."
msgstr ""

#: ../Doc/howto/clinic.rst:1107
msgid ""
"A Python block uses different delimiter lines than an Argument Clinic "
"function block.  It looks like this::"
msgstr ""

#: ../Doc/howto/clinic.rst:1114
msgid ""
"All the code inside the Python block is executed at the time it's parsed.  "
"All text written to stdout inside the block is redirected into the \"output"
"\" after the block."
msgstr ""

#: ../Doc/howto/clinic.rst:1118
msgid ""
"As an example, here's a Python block that adds a static integer variable to "
"the C code::"
msgstr ""

#: ../Doc/howto/clinic.rst:1129
msgid "Using a \"self converter\""
msgstr ""

#: ../Doc/howto/clinic.rst:1131
msgid ""
"Argument Clinic automatically adds a \"self\" parameter for you using a "
"default converter.  It automatically sets the ``type`` of this parameter to "
"the \"pointer to an instance\" you specified when you declared the type.  "
"However, you can override Argument Clinic's converter and specify one "
"yourself. Just add your own ``self`` parameter as the first parameter in a "
"block, and ensure that its converter is an instance of ``self_converter`` or "
"a subclass thereof."
msgstr ""

#: ../Doc/howto/clinic.rst:1140
msgid ""
"What's the point?  This lets you override the type of ``self``, or give it a "
"different default name."
msgstr ""

#: ../Doc/howto/clinic.rst:1143
msgid ""
"How do you specify the custom type you want to cast ``self`` to? If you only "
"have one or two functions with the same type for ``self``, you can directly "
"use Argument Clinic's existing ``self`` converter, passing in the type you "
"want to use as the ``type`` parameter::"
msgstr ""

#: ../Doc/howto/clinic.rst:1159
msgid ""
"On the other hand, if you have a lot of functions that will use the same "
"type for ``self``, it's best to create your own converter, subclassing "
"``self_converter`` but overwriting the ``type`` member::"
msgstr ""

#: ../Doc/howto/clinic.rst:1182
msgid "Writing a custom converter"
msgstr ""

#: ../Doc/howto/clinic.rst:1184
msgid ""
"As we hinted at in the previous section... you can write your own "
"converters! A converter is simply a Python class that inherits from "
"``CConverter``. The main purpose of a custom converter is if you have a "
"parameter using the ``O&`` format unit--parsing this parameter means calling "
"a :c:func:`PyArg_ParseTuple` \"converter function\"."
msgstr ""

#: ../Doc/howto/clinic.rst:1190
msgid ""
"Your converter class should be named ``*something*_converter``. If the name "
"follows this convention, then your converter class will be automatically "
"registered with Argument Clinic; its name will be the name of your class "
"with the ``_converter`` suffix stripped off.  (This is accomplished with a "
"metaclass.)"
msgstr ""

#: ../Doc/howto/clinic.rst:1196
msgid ""
"You shouldn't subclass ``CConverter.__init__``.  Instead, you should write a "
"``converter_init()`` function.  ``converter_init()`` always accepts a "
"``self`` parameter; after that, all additional parameters *must* be keyword-"
"only.  Any arguments passed in to the converter in Argument Clinic will be "
"passed along to your ``converter_init()``."
msgstr ""

#: ../Doc/howto/clinic.rst:1203
msgid ""
"There are some additional members of ``CConverter`` you may wish to specify "
"in your subclass.  Here's the current list:"
msgstr ""

#: ../Doc/howto/clinic.rst:1207
msgid ""
"The C type to use for this variable. ``type`` should be a Python string "
"specifying the type, e.g. ``int``. If this is a pointer type, the type "
"string should end with ``' *'``."
msgstr ""

#: ../Doc/howto/clinic.rst:1213
msgid "``default``"
msgstr ""

#: ../Doc/howto/clinic.rst:1212
msgid ""
"The Python default value for this parameter, as a Python value. Or the magic "
"value ``unspecified`` if there is no default."
msgstr ""

#: ../Doc/howto/clinic.rst:1218
msgid "``py_default``"
msgstr ""

#: ../Doc/howto/clinic.rst:1216
msgid ""
"``default`` as it should appear in Python code, as a string. Or ``None`` if "
"there is no default."
msgstr ""

#: ../Doc/howto/clinic.rst:1221
msgid ""
"``default`` as it should appear in C code, as a string. Or ``None`` if there "
"is no default."
msgstr ""

#: ../Doc/howto/clinic.rst:1234
msgid "``c_ignored_default``"
msgstr ""

#: ../Doc/howto/clinic.rst:1226
msgid ""
"The default value used to initialize the C variable when there is no "
"default, but not specifying a default may result in an \"uninitialized "
"variable\" warning.  This can easily happen when using option groups--"
"although properly-written code will never actually use this value, the "
"variable does get passed in to the impl, and the C compiler will complain "
"about the \"use\" of the uninitialized value.  This value should always be a "
"non-empty string."
msgstr ""

#: ../Doc/howto/clinic.rst:1237
msgid "The name of the C converter function, as a string."
msgstr ""

#: ../Doc/howto/clinic.rst:1242
msgid "``impl_by_reference``"
msgstr ""

#: ../Doc/howto/clinic.rst:1240
msgid ""
"A boolean value.  If true, Argument Clinic will add a ``&`` in front of the "
"name of the variable when passing it into the impl function."
msgstr ""

#: ../Doc/howto/clinic.rst:1248
msgid "``parse_by_reference``"
msgstr ""

#: ../Doc/howto/clinic.rst:1245
msgid ""
"A boolean value.  If true, Argument Clinic will add a ``&`` in front of the "
"name of the variable when passing it into :c:func:`PyArg_ParseTuple`."
msgstr ""

#: ../Doc/howto/clinic.rst:1250
msgid ""
"Here's the simplest example of a custom converter, from ``Modules/zlibmodule."
"c``::"
msgstr ""

#: ../Doc/howto/clinic.rst:1261
msgid ""
"This block adds a converter to Argument Clinic named ``ssize_t``.  "
"Parameters declared as ``ssize_t`` will be declared as type ``Py_ssize_t``, "
"and will be parsed by the ``'O&'`` format unit, which will call the "
"``ssize_t_converter`` converter function.  ``ssize_t`` variables "
"automatically support default values."
msgstr ""

#: ../Doc/howto/clinic.rst:1267
msgid ""
"More sophisticated custom converters can insert custom C code to handle "
"initialization and cleanup. You can see more examples of custom converters "
"in the CPython source tree; grep the C files for the string ``CConverter``."
msgstr ""

#: ../Doc/howto/clinic.rst:1273
msgid "Writing a custom return converter"
msgstr ""

#: ../Doc/howto/clinic.rst:1275
msgid ""
"Writing a custom return converter is much like writing a custom converter.  "
"Except it's somewhat simpler, because return converters are themselves much "
"simpler."
msgstr ""

#: ../Doc/howto/clinic.rst:1279
msgid ""
"Return converters must subclass ``CReturnConverter``. There are no examples "
"yet of custom return converters, because they are not widely used yet.  If "
"you wish to write your own return converter, please read ``Tools/clinic/"
"clinic.py``, specifically the implementation of ``CReturnConverter`` and all "
"its subclasses."
msgstr ""

#: ../Doc/howto/clinic.rst:1287
msgid "METH_O and METH_NOARGS"
msgstr ""

#: ../Doc/howto/clinic.rst:1289
msgid ""
"To convert a function using ``METH_O``, make sure the function's single "
"argument is using the ``object`` converter, and mark the arguments as "
"positional-only::"
msgstr ""

#: ../Doc/howto/clinic.rst:1301
msgid ""
"To convert a function using ``METH_NOARGS``, just don't specify any "
"arguments."
msgstr ""

#: ../Doc/howto/clinic.rst:1304
msgid ""
"You can still use a self converter, a return converter, and specify a "
"``type`` argument to the object converter for ``METH_O``."
msgstr ""

#: ../Doc/howto/clinic.rst:1308
msgid "tp_new and tp_init functions"
msgstr ""

#: ../Doc/howto/clinic.rst:1310
msgid ""
"You can convert ``tp_new`` and ``tp_init`` functions.  Just name them "
"``__new__`` or ``__init__`` as appropriate.  Notes:"
msgstr ""

#: ../Doc/howto/clinic.rst:1313
msgid ""
"The function name generated for ``__new__`` doesn't end in ``__new__`` like "
"it would by default.  It's just the name of the class, converted into a "
"valid C identifier."
msgstr ""

#: ../Doc/howto/clinic.rst:1317
msgid "No ``PyMethodDef`` ``#define`` is generated for these functions."
msgstr ""

#: ../Doc/howto/clinic.rst:1319
msgid "``__init__`` functions return ``int``, not ``PyObject *``."
msgstr ""

#: ../Doc/howto/clinic.rst:1321
msgid "Use the docstring as the class docstring."
msgstr ""

#: ../Doc/howto/clinic.rst:1323
msgid ""
"Although ``__new__`` and ``__init__`` functions must always accept both the "
"``args`` and ``kwargs`` objects, when converting you may specify any "
"signature for these functions that you like. (If your function doesn't "
"support keywords, the parsing function generated will throw an exception if "
"it receives any.)"
msgstr ""

#: ../Doc/howto/clinic.rst:1330
msgid "Changing and redirecting Clinic's output"
msgstr ""

#: ../Doc/howto/clinic.rst:1332
msgid ""
"It can be inconvenient to have Clinic's output interspersed with your "
"conventional hand-edited C code.  Luckily, Clinic is configurable: you can "
"buffer up its output for printing later (or earlier!), or write its output "
"to a separate file.  You can also add a prefix or suffix to every line of "
"Clinic's generated output."
msgstr ""

#: ../Doc/howto/clinic.rst:1338
msgid ""
"While changing Clinic's output in this manner can be a boon to readability, "
"it may result in Clinic code using types before they are defined, or your "
"code attempting to use Clinic-generated code before it is defined. These "
"problems can be easily solved by rearranging the declarations in your file, "
"or moving where Clinic's generated code goes.  (This is why the default "
"behavior of Clinic is to output everything into the current block; while "
"many people consider this hampers readability, it will never require "
"rearranging your code to fix definition-before-use problems.)"
msgstr ""

#: ../Doc/howto/clinic.rst:1347
msgid "Let's start with defining some terminology:"
msgstr ""

#: ../Doc/howto/clinic.rst:1372
msgid "*field*"
msgstr ""

#: ../Doc/howto/clinic.rst:1350
msgid ""
"A field, in this context, is a subsection of Clinic's output. For example, "
"the ``#define`` for the ``PyMethodDef`` structure is a field, called "
"``methoddef_define``.  Clinic has seven different fields it can output per "
"function definition::"
msgstr ""

#: ../Doc/howto/clinic.rst:1363
msgid ""
"All the names are of the form ``\"<a>_<b>\"``, where ``\"<a>\"`` is the "
"semantic object represented (the parsing function, the impl function, the "
"docstring, or the methoddef structure) and ``\"<b>\"`` represents what kind "
"of statement the field is.  Field names that end in ``\"_prototype\"`` "
"represent forward declarations of that thing, without the actual body/data "
"of the thing; field names that end in ``\"_definition\"`` represent the "
"actual definition of the thing, with the body/data of the thing.  (``"
"\"methoddef\"`` is special, it's the only one that ends with ``\"_define"
"\"``, representing that it's a preprocessor #define.)"
msgstr ""

#: ../Doc/howto/clinic.rst:1406
msgid "*destination*"
msgstr ""

#: ../Doc/howto/clinic.rst:1375
msgid ""
"A destination is a place Clinic can write output to.  There are five built-"
"in destinations:"
msgstr ""

#: ../Doc/howto/clinic.rst:1380 ../Doc/howto/clinic.rst:1449
#: ../Doc/howto/clinic.rst:1523
msgid "``block``"
msgstr ""

#: ../Doc/howto/clinic.rst:1379
msgid ""
"The default destination: printed in the output section of the current Clinic "
"block."
msgstr ""

#: ../Doc/howto/clinic.rst:1386 ../Doc/howto/clinic.rst:1476
#: ../Doc/howto/clinic.rst:1526
msgid "``buffer``"
msgstr ""

#: ../Doc/howto/clinic.rst:1383
msgid ""
"A text buffer where you can save text for later.  Text sent here is appended "
"to the end of any existing text.  It's an error to have any text left in the "
"buffer when Clinic finishes processing a file."
msgstr ""

#: ../Doc/howto/clinic.rst:1397 ../Doc/howto/clinic.rst:1462
#: ../Doc/howto/clinic.rst:1552
msgid "``file``"
msgstr ""

#: ../Doc/howto/clinic.rst:1389
msgid ""
"A separate \"clinic file\" that will be created automatically by Clinic. The "
"filename chosen for the file is ``{basename}.clinic{extension}``, where "
"``basename`` and ``extension`` were assigned the output from ``os.path."
"splitext()`` run on the current file.  (Example: the ``file`` destination "
"for ``_pickle.c`` would be written to ``_pickle.clinic.c``.)"
msgstr ""

#: ../Doc/howto/clinic.rst:1396
msgid ""
"**Important: When using a** ``file`` **destination, you** *must check in* "
"**the generated file!**"
msgstr ""

#: ../Doc/howto/clinic.rst:1402 ../Doc/howto/clinic.rst:1489
#: ../Doc/howto/clinic.rst:1556
msgid "``two-pass``"
msgstr ""

#: ../Doc/howto/clinic.rst:1400
msgid ""
"A buffer like ``buffer``.  However, a two-pass buffer can only be written "
"once, and it prints out all text sent to it during all of processing, even "
"from Clinic blocks *after* the"
msgstr ""

#: ../Doc/howto/clinic.rst:1406 ../Doc/howto/clinic.rst:1519
msgid "``suppress``"
msgstr ""

#: ../Doc/howto/clinic.rst:1405
msgid "The text is suppressed--thrown away."
msgstr ""

#: ../Doc/howto/clinic.rst:1408
msgid "Clinic defines five new directives that let you reconfigure its output."
msgstr ""

#: ../Doc/howto/clinic.rst:1410
msgid "The first new directive is ``dump``::"
msgstr ""

#: ../Doc/howto/clinic.rst:1414
msgid ""
"This dumps the current contents of the named destination into the output of "
"the current block, and empties it.  This only works with ``buffer`` and "
"``two-pass`` destinations."
msgstr ""

#: ../Doc/howto/clinic.rst:1418
msgid ""
"The second new directive is ``output``.  The most basic form of ``output`` "
"is like this::"
msgstr ""

#: ../Doc/howto/clinic.rst:1423
msgid ""
"This tells Clinic to output *field* to *destination*.  ``output`` also "
"supports a special meta-destination, called ``everything``, which tells "
"Clinic to output *all* fields to that *destination*."
msgstr ""

#: ../Doc/howto/clinic.rst:1427
msgid "``output`` has a number of other functions::"
msgstr ""

#: ../Doc/howto/clinic.rst:1434
msgid ""
"``output push`` and ``output pop`` allow you to push and pop configurations "
"on an internal configuration stack, so that you can temporarily modify the "
"output configuration, then easily restore the previous configuration.  "
"Simply push before your change to save the current configuration, then pop "
"when you wish to restore the previous configuration."
msgstr ""

#: ../Doc/howto/clinic.rst:1441
msgid ""
"``output preset`` sets Clinic's output to one of several built-in preset "
"configurations, as follows:"
msgstr ""

#: ../Doc/howto/clinic.rst:1445
msgid ""
"Clinic's original starting configuration.  Writes everything immediately "
"after the input block."
msgstr ""

#: ../Doc/howto/clinic.rst:1448
msgid ""
"Suppress the ``parser_prototype`` and ``docstring_prototype``, write "
"everything else to ``block``."
msgstr ""

#: ../Doc/howto/clinic.rst:1452
msgid ""
"Designed to write everything to the \"clinic file\" that it can. You then "
"``#include`` this file near the top of your file. You may need to rearrange "
"your file to make this work, though usually this just means creating forward "
"declarations for various ``typedef`` and ``PyTypeObject`` definitions."
msgstr ""

#: ../Doc/howto/clinic.rst:1458
msgid ""
"Suppress the ``parser_prototype`` and ``docstring_prototype``, write the "
"``impl_definition`` to ``block``, and write everything else to ``file``."
msgstr ""

#: ../Doc/howto/clinic.rst:1462
msgid "The default filename is ``\"{dirname}/clinic/{basename}.h\"``."
msgstr ""

#: ../Doc/howto/clinic.rst:1465
msgid ""
"Save up all most of the output from Clinic, to be written into your file "
"near the end.  For Python files implementing modules or builtin types, it's "
"recommended that you dump the buffer just above the static structures for "
"your module or builtin type; these are normally very near the end.  Using "
"``buffer`` may require even more editing than ``file``, if your file has "
"static ``PyMethodDef`` arrays defined in the middle of the file."
msgstr ""

#: ../Doc/howto/clinic.rst:1474
msgid ""
"Suppress the ``parser_prototype``, ``impl_prototype``, and "
"``docstring_prototype``, write the ``impl_definition`` to ``block``, and "
"write everything else to ``file``."
msgstr ""

#: ../Doc/howto/clinic.rst:1479
msgid ""
"Similar to the ``buffer`` preset, but writes forward declarations to the "
"``two-pass`` buffer, and definitions to the ``buffer``. This is similar to "
"the ``buffer`` preset, but may require less editing than ``buffer``.  Dump "
"the ``two-pass`` buffer near the top of your file, and dump the ``buffer`` "
"near the end just like you would when using the ``buffer`` preset."
msgstr ""

#: ../Doc/howto/clinic.rst:1486
msgid ""
"Suppresses the ``impl_prototype``, write the ``impl_definition`` to "
"``block``, write ``docstring_prototype``, ``methoddef_define``, and "
"``parser_prototype`` to ``two-pass``, write everything else to ``buffer``."
msgstr ""

#: ../Doc/howto/clinic.rst:1500
msgid "``partial-buffer``"
msgstr ""

#: ../Doc/howto/clinic.rst:1492
msgid ""
"Similar to the ``buffer`` preset, but writes more things to ``block``, only "
"writing the really big chunks of generated code to ``buffer``. This avoids "
"the definition-before-use problem of ``buffer`` completely, at the small "
"cost of having slightly more stuff in the block's output. Dump the "
"``buffer`` near the end, just like you would when using the ``buffer`` "
"preset."
msgstr ""

#: ../Doc/howto/clinic.rst:1499
msgid ""
"Suppresses the ``impl_prototype``, write the ``docstring_definition`` and "
"``parser_definition`` to ``buffer``, write everything else to ``block``."
msgstr ""

#: ../Doc/howto/clinic.rst:1502
msgid "The third new directive is ``destination``::"
msgstr ""

#: ../Doc/howto/clinic.rst:1506
msgid "This performs an operation on the destination named ``name``."
msgstr ""

#: ../Doc/howto/clinic.rst:1508
msgid "There are two defined subcommands: ``new`` and ``clear``."
msgstr ""

#: ../Doc/howto/clinic.rst:1510
msgid "The ``new`` subcommand works like this::"
msgstr ""

#: ../Doc/howto/clinic.rst:1514
msgid ""
"This creates a new destination with name ``<name>`` and type ``<type>``."
msgstr ""

#: ../Doc/howto/clinic.rst:1516
msgid "There are five destination types:"
msgstr ""

#: ../Doc/howto/clinic.rst:1519
msgid "Throws the text away."
msgstr ""

#: ../Doc/howto/clinic.rst:1522
msgid ""
"Writes the text to the current block.  This is what Clinic originally did."
msgstr ""

#: ../Doc/howto/clinic.rst:1526
msgid "A simple text buffer, like the \"buffer\" builtin destination above."
msgstr ""

#: ../Doc/howto/clinic.rst:1529
msgid ""
"A text file.  The file destination takes an extra argument, a template to "
"use for building the filename, like so:"
msgstr ""

#: ../Doc/howto/clinic.rst:1532
msgid "destination <name> new <type> <file_template>"
msgstr ""

#: ../Doc/howto/clinic.rst:1534
msgid ""
"The template can use three strings internally that will be replaced by bits "
"of the filename:"
msgstr ""

#: ../Doc/howto/clinic.rst:1537
msgid "{path}"
msgstr ""

#: ../Doc/howto/clinic.rst:1538
msgid "The full path to the file, including directory and full filename."
msgstr ""

#: ../Doc/howto/clinic.rst:1539
msgid "{dirname}"
msgstr ""

#: ../Doc/howto/clinic.rst:1540
msgid "The name of the directory the file is in."
msgstr ""

#: ../Doc/howto/clinic.rst:1541
msgid "{basename}"
msgstr ""

#: ../Doc/howto/clinic.rst:1542
msgid "Just the name of the file, not including the directory."
msgstr ""

#: ../Doc/howto/clinic.rst:1544
msgid "{basename_root}"
msgstr ""

#: ../Doc/howto/clinic.rst:1544
msgid ""
"Basename with the extension clipped off (everything up to but not including "
"the last '.')."
msgstr ""

#: ../Doc/howto/clinic.rst:1548
msgid "{basename_extension}"
msgstr ""

#: ../Doc/howto/clinic.rst:1547
msgid ""
"The last '.' and everything after it.  If the basename does not contain a "
"period, this will be the empty string."
msgstr ""

#: ../Doc/howto/clinic.rst:1550
msgid ""
"If there are no periods in the filename, {basename} and {filename} are the "
"same, and {extension} is empty.  \"{basename}{extension}\" is always exactly "
"the same as \"{filename}\".\""
msgstr ""

#: ../Doc/howto/clinic.rst:1555
msgid "A two-pass buffer, like the \"two-pass\" builtin destination above."
msgstr ""

#: ../Doc/howto/clinic.rst:1558
msgid "The ``clear`` subcommand works like this::"
msgstr ""

#: ../Doc/howto/clinic.rst:1562
msgid ""
"It removes all the accumulated text up to this point in the destination. (I "
"don't know what you'd need this for, but I thought maybe it'd be useful "
"while someone's experimenting.)"
msgstr ""

#: ../Doc/howto/clinic.rst:1566
msgid "The fourth new directive is ``set``::"
msgstr ""

#: ../Doc/howto/clinic.rst:1571
msgid ""
"``set`` lets you set two internal variables in Clinic. ``line_prefix`` is a "
"string that will be prepended to every line of Clinic's output; "
"``line_suffix`` is a string that will be appended to every line of Clinic's "
"output."
msgstr ""

#: ../Doc/howto/clinic.rst:1575
msgid "Both of these support two format strings:"
msgstr ""

#: ../Doc/howto/clinic.rst:1578
msgid "``{block comment start}``"
msgstr ""

#: ../Doc/howto/clinic.rst:1578
msgid ""
"Turns into the string ``/*``, the start-comment text sequence for C files."
msgstr ""

#: ../Doc/howto/clinic.rst:1581
msgid "``{block comment end}``"
msgstr ""

#: ../Doc/howto/clinic.rst:1581
msgid ""
"Turns into the string ``*/``, the end-comment text sequence for C files."
msgstr ""

#: ../Doc/howto/clinic.rst:1583
msgid ""
"The final new directive is one you shouldn't need to use directly, called "
"``preserve``::"
msgstr ""

#: ../Doc/howto/clinic.rst:1588
msgid ""
"This tells Clinic that the current contents of the output should be kept, "
"unmodified. This is used internally by Clinic when dumping output into "
"``file`` files; wrapping it in a Clinic block lets Clinic use its existing "
"checksum functionality to ensure the file was not modified by hand before it "
"gets overwritten."
msgstr ""

#: ../Doc/howto/clinic.rst:1595
msgid "The #ifdef trick"
msgstr ""

#: ../Doc/howto/clinic.rst:1597
msgid ""
"If you're converting a function that isn't available on all platforms, "
"there's a trick you can use to make life a little easier.  The existing code "
"probably looks like this::"
msgstr ""

#: ../Doc/howto/clinic.rst:1608
msgid ""
"And then in the ``PyMethodDef`` structure at the bottom the existing code "
"will have::"
msgstr ""

#: ../Doc/howto/clinic.rst:1615
msgid ""
"In this scenario, you should enclose the body of your impl function inside "
"the ``#ifdef``, like so::"
msgstr ""

#: ../Doc/howto/clinic.rst:1629
msgid ""
"Then, remove those three lines from the ``PyMethodDef`` structure, replacing "
"them with the macro Argument Clinic generated::"
msgstr ""

#: ../Doc/howto/clinic.rst:1634
msgid ""
"(You can find the real name for this macro inside the generated code. Or you "
"can calculate it yourself: it's the name of your function as defined on the "
"first line of your block, but with periods changed to underscores, "
"uppercased, and ``\"_METHODDEF\"`` added to the end.)"
msgstr ""

#: ../Doc/howto/clinic.rst:1639
msgid ""
"Perhaps you're wondering: what if ``HAVE_FUNCTIONNAME`` isn't defined? The "
"``MODULE_FUNCTIONNAME_METHODDEF`` macro won't be defined either!"
msgstr ""

#: ../Doc/howto/clinic.rst:1642
msgid ""
"Here's where Argument Clinic gets very clever.  It actually detects that the "
"Argument Clinic block might be deactivated by the ``#ifdef``.  When that "
"happens, it generates a little extra code that looks like this::"
msgstr ""

#: ../Doc/howto/clinic.rst:1650
msgid ""
"That means the macro always works.  If the function is defined, this turns "
"into the correct structure, including the trailing comma.  If the function "
"is undefined, this turns into nothing."
msgstr ""

#: ../Doc/howto/clinic.rst:1654
msgid ""
"However, this causes one ticklish problem: where should Argument Clinic put "
"this extra code when using the \"block\" output preset?  It can't go in the "
"output block, because that could be deactivated by the ``#ifdef``.  (That's "
"the whole point!)"
msgstr ""

#: ../Doc/howto/clinic.rst:1658
msgid ""
"In this situation, Argument Clinic writes the extra code to the \"buffer\" "
"destination. This may mean that you get a complaint from Argument Clinic::"
msgstr ""

#: ../Doc/howto/clinic.rst:1664
msgid ""
"When this happens, just open your file, find the ``dump buffer`` block that "
"Argument Clinic added to your file (it'll be at the very bottom), then move "
"it above the ``PyMethodDef`` structure where that macro is used."
msgstr ""

#: ../Doc/howto/clinic.rst:1671
msgid "Using Argument Clinic in Python files"
msgstr ""

#: ../Doc/howto/clinic.rst:1673
msgid ""
"It's actually possible to use Argument Clinic to preprocess Python files. "
"There's no point to using Argument Clinic blocks, of course, as the output "
"wouldn't make any sense to the Python interpreter.  But using Argument "
"Clinic to run Python blocks lets you use Python as a Python preprocessor!"
msgstr ""

#: ../Doc/howto/clinic.rst:1678
msgid ""
"Since Python comments are different from C comments, Argument Clinic blocks "
"embedded in Python files look slightly different.  They look like this::"
msgstr ""