python-docs-fr/howto/clinic.po

# Copyright (C) 2001-2018, Python Software Foundation
# For licence information, see README file.
#
msgid ""
msgstr ""
"Project-Id-Version: Python 3\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2020-08-24 09:01+0200\n"
"PO-Revision-Date: 2019-03-26 17:29+0100\n"
"Last-Translator: Julien Palard <julien@palard.fr>\n"
"Language-Team: FRENCH <traductions@lists.afpy.org>\n"
"Language: fr\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Generator: Poedit 2.0.6\n"

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

#: howto/clinic.rst:0
msgid "author"
msgstr "auteur"

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

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

#: 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 ""
"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. "

#: 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 ""
"Argument Clinic est pour le moment considéré comme un outil interne à "
"CPython.  Il n'est pas conçu pour gérer des fichiers à l'extérieur de "
"CPython, et sa compatibilité ascendante n'est pas garantie pour les versions "
"futures. En d'autres termes, si vous êtes mainteneur d'une extension C pour "
"CPython, vous pouvez bien sûr expérimenter avec Argument Clinic sur votre "
"propre code. Mais la version d'Argument Clinic livrée avec la prochaine "
"version de CPython *pourrait* être totalement incompatible et casser tout "
"votre code."

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

#: 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 ""
"Le premier objectif d'Argument Clinic est de prendre en charge toute "
"l'analyse d'arguments à l'intérieur de CPython. Cela signifie que si vous "
"convertissez une fonction pour fonctionner avec Argument Clinic, cette "
"fonction n'a plus du tout besoin d'analyser ses propres arguments. Le code "
"généré par Argument Clinic doit être une « boîte noire » avec en entrée "
"l'appel de CPython, et en sortie l'appel à votre code. Entre les deux, "
"``PyObject *args`` (et éventuellement ``PyObject *kwargs``) sont convertis "
"magiquement dans les variables et types C dont vous avez besoin."

#: 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 ""
"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."

#: 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 ""
"Certainement, personne ne voudrait utiliser Argument Clinic s'il ne réglait "
"pas leur problème -- sans en créer de nouveaux. Il est donc de la première "
"importance qu'Argument Clinic génère du code correct. Il est aussi "
"souhaitable que le code soit aussi plus rapide. Au minimum, il ne doit pas "
"introduire de régression significative sur la vitesse d'exécution. (Au bout "
"du compte, Argument Clinic *devrait* permettre une accélération importante "
"-- on pourrait ré-écrire son générateur de code pour produire du code "
"d'analyse d'argument adapté au mieux, plutôt que d'utiliser la bibliothèque "
"d'analyse d'argument générique. On aurait ainsi l'analyse d'argument la plus "
"rapide possible !)"

#: 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 ""
"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. "

#: 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 ""
"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é !"

#: 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 ""
"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."

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

#: 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 ""
"Argument Clinic est livré avec CPython; vous le trouverez dans ``Tools/"
"clinic/clinic.py``. Si vous exécutez ce script, en spécifiant un fichier C "
"comme argument : "

#: howto/clinic.rst:89
msgid ""
"Argument Clinic will scan over the file looking for lines that look exactly "
"like this:"
msgstr "Argument Clinic va parcourir le fichier en cherchant cette ligne :"

#: howto/clinic.rst:96
msgid ""
"When it finds one, it reads everything up to a line that looks exactly like "
"this:"
msgstr ""
"Lorsqu'il en trouve une, il lit tout ce qui suit, jusqu'à cette ligne :"

#: 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 ""
"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. "

#: 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 ""
"Lorsque *Argument Clinic* analyse l'un de ces blocs, il produit une sortie. "
"Cette sortie est réécrite dans le fichier C immédiatement après le bloc, "
"suivie par un commentaire contenant une somme de contrôle. Le bloc Argument "
"Clinic ressemble maintenant à cela :"

#: 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 ""
"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. "

#: 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 ""
"Vous ne devez jamais modifier la sortie d'un bloc Argument Clinic. Changez "
"plutôt l'entrée jusqu'à obtenir la sortie souhaitée (c'est précisément le "
"but de la somme de contrôle, détecter si la sortie a été changée. En effet, "
"ces modifications seront perdues après que Argument Clinic a écrit une "
"nouvelle sortie)."

#: howto/clinic.rst:129
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 :"

#: howto/clinic.rst:131
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*."

#: howto/clinic.rst:132
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*."

#: howto/clinic.rst:133
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*. "

#: howto/clinic.rst:134
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."

#: howto/clinic.rst:135
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."

#: 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 ""
"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)"

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

#: 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 ""
"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."

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

#: howto/clinic.rst:156
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."

#: 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 ""
"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()``."

#: howto/clinic.rst:164
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 :"

#: 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 ""
"ou s'il y a de multiples appels à :c:func:`PyArg_ParseTuple`, choisissez une "
"fonction différente. Argument Clinic gère tous ces scénarios, mais se sont "
"des sujets trop avancés pour notre première fonction."

#: 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 ""
"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."

#: howto/clinic.rst:188
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 ::"

#: 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 ""
"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*)."

#: 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 ""
"Si l'ancienne *docstring* commençait par une ligne qui ressemble à une "
"signature de fonction, supprimez cette ligne. (Elle n'est plus nécessaire "
"pour la *docstring*. Dans le futur, quand vous utiliserez ``help()`` pour "
"une fonction native, la première ligne sera construite automatiquement à "
"partir de la signature de la fonction.)"

#: howto/clinic.rst:205 howto/clinic.rst:226 howto/clinic.rst:250
#: howto/clinic.rst:308 howto/clinic.rst:348 howto/clinic.rst:375
#: howto/clinic.rst:481 howto/clinic.rst:533
msgid "Sample::"
msgstr "Échantillon ::"

#: 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 ""
"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*."

#: 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 ""
"Dans notre exemple, la *docstring* est seulement composée d'une ligne de "
"résumé, donc le code ne change pas à cette étape."

#: 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 ""
"Au dessus de la *docstring*, entrez le nom de la fonction, suivi d'une ligne "
"vide. Ce doit être le nom de la fonction en Python et être le chemin complet "
"jusqu'à la fonction. Il doit commencer par le nom du module, suivi de tous "
"les sous-modules, puis, si la fonction est une méthode de classe, inclure "
"aussi le nom de la classe."

#: 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 ""
"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)."

#: 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 ""
"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`"

#: 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 ""
"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."

#: 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 ""
"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*."

#: howto/clinic.rst:270
msgid "The general form of these parameter lines is as follows:"
msgstr "La forme générale de ces paramètres est la suivante :"

#: howto/clinic.rst:276
msgid "If the parameter has a default value, add that after the converter:"
msgstr ""
"Si le paramètre a une valeur par défaut, ajoutez ceci après le "
"convertisseur :"

#: 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 ""
"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."

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

#: 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 ""
"Que fait le « convertisseur » ? Il établit à la fois le type de variable "
"utilisé en C et la méthode pour convertir la valeur Python en valeur C lors "
"de l'exécution.  Pour le moment, vous allez utiliser ce qui s'appelle un « "
"convertisseur hérité » -- une syntaxe de convenance qui facilite le portage "
"de vieux code dans Argument Clinic."

#: 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 ""
"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`.)"

#: howto/clinic.rst:305
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. "

#: 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 ""
"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."

#: 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 ""
"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."

#: howto/clinic.rst:333
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é.)"

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

#: 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 ""
"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."

#: 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 ""
"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.)"

#: 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 ""
"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."

#: 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 ""
"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."

#: 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 ""
"Enregistrez puis fermez le fichier, puis exécutez ``Tools/clinic/clinic.py`` "
"dessus. Avec un peu de chance tout a fonctionné, votre bloc a maintenant une "
"sortie, et un fichier ``.c.h`` a été généré ! Ré-ouvrez le fichier dans "
"votre éditeur pour voir ::"

#: 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 ""
"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."

#: 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 ""
"Pour plus de visibilité, la plupart du code a été écrit dans un fichier ``.c."
"h``. Vous devez l'inclure dans votre fichier ``.c`` original, typiquement "
"juste après le bloc du module *clinic* ::"

#: howto/clinic.rst:421
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."

#: 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 ""
"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."

#: 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 ""
"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."

#: 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 ""
"(Argument Clinic génère toujours ses chaînes de format avec ``:`` suivi du "
"nom de la fonction. Si la chaîne de format du code existant termine par ``;"
"``, pour fournir une aide sur l'utilisation, ce changement n'a aucun effet, "
"ne vous en souciez pas.)"

#: 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 ""
"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."

#: 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 ""
"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 ::"

#: 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 ""
"Cette structure statique doit être *exactement* la même que la structure "
"statique :c:type:`PyMethodDef` existante pour ce module natif."

#: 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 ""
"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."

#: 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 ""
"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."

#: howto/clinic.rst:468
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 ::"

#: 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 ""
"Argument Clinic génère une ligne de contrôle et la fonction prototype juste "
"au dessus. Vous devez écrire les accolades d'ouverture (et de fermeture) "
"pour la fonction,  et l’implémentation à l'intérieur."

#: 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 ""
"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.)"

#: 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 ""
"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."

#: 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 ""
"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."

#: howto/clinic.rst:546
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 !"

#: howto/clinic.rst:549
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 !"

#: howto/clinic.rst:552
msgid "Advanced Topics"
msgstr "Sujets avancés"

#: howto/clinic.rst:554
msgid ""
"Now that you've had some experience working with Argument Clinic, it's time "
"for some advanced topics."
msgstr ""
"Maintenant que vous avez un peu d'expérience avec Argument Clinic, c'est le "
"moment pour des sujets avancés."

#: howto/clinic.rst:559
msgid "Symbolic default values"
msgstr "Valeurs par défaut"

#: 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 ""
"La valeur par défaut que vous fournissez pour un paramètre ne peut pas être "
"n'importe quelle expression. Actuellement, ce qui est géré :"

#: howto/clinic.rst:564
msgid "Numeric constants (integer and float)"
msgstr "Constantes numériques (entier ou nombre flottant)"

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

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

#: howto/clinic.rst:567
msgid ""
"Simple symbolic constants like ``sys.maxsize``, which must start with the "
"name of the module"
msgstr ""
"Constantes symboliques simples comme ``sys.maxsize``, qui doivent commencer "
"par le nom du module"

#: howto/clinic.rst:570
msgid ""
"In case you're curious, this is implemented in  ``from_builtin()`` in ``Lib/"
"inspect.py``."
msgstr ""
"Si par curiosité vous voulez lire l'implémentation, c'est ``from_builtin()`` "
"dans ``Lib/inspect.py``."

#: howto/clinic.rst:573
msgid ""
"(In the future, this may need to get even more elaborate, to allow full "
"expressions like ``CONSTANT - 1``.)"
msgstr ""
"(Dans le futur, il est possible que l'on ait besoin de l'améliorer, pour "
"autoriser les expressions complètes comme ``CONSTANT - 1``.)"

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

#: 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 ""

#: 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 ""
"Par exemple, si nous voulons renommer les noms de fonction C générés pour "
"``pickle.Pickler.dump``, ça ressemblerait à ça ::"

#: 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 ""
"La fonction de base sera maintenant nommée ``pickler_dumper()``, et la "
"fonction *impl* serait maintenant nommé ``pickler_dumper_impl()``."

#: 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 ""
"De même, vous pouvez avoir un problème quand vous souhaiterez donner à un "
"paramètre un nom spécifique à Python, mais ce nom peut être gênant en C. "
"Argument Clinic vous permet de donner à un paramètre des noms différents en "
"Python et en C ::"

#: 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 ""

#: howto/clinic.rst:617
msgid "You can use this to rename the ``self`` parameter too!"
msgstr "Vous pouvez utiliser ceci pour renommer aussi le paramètre ``self``"

#: howto/clinic.rst:621
msgid "Converting functions using PyArg_UnpackTuple"
msgstr "Conversion des fonctions en utilisant *PyArg_UnpackTuple*"

#: 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 ""

#: howto/clinic.rst:629
msgid ""
"Currently the generated code will use :c:func:`PyArg_ParseTuple`, but this "
"will change soon."
msgstr ""
"Actuellement, le code généré utilise :c:func:`PyArg_ParseTuple`, mais cela "
"va bientôt changer."

#: howto/clinic.rst:633
msgid "Optional Groups"
msgstr "Groupes optionnels"

#: 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 ""

#: 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 ""

#: 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 ""

#: 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 ""

#: 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 ""

#: howto/clinic.rst:700
msgid "Notes:"
msgstr "Notes :"

#: 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 ""

#: 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 ""
"S'il n'y a pas d'arguments requis, les groupes optionnels se comportent "
"comme s'ils étaient à droite des arguments requis."

#: howto/clinic.rst:716
msgid ""
"In the case of ambiguity, the argument parsing code favors parameters on the "
"left (before the required parameters)."
msgstr ""

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

#: howto/clinic.rst:721
msgid ""
"Optional groups are *only* intended for legacy code.  Please do not use "
"optional groups for new code."
msgstr ""
"Les groupes optionnels sont *seulement* destinés au code hérité. Ne les "
"utilisez pas dans du nouveau code."

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

#: 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 ""

#: 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 ""

#: howto/clinic.rst:739
msgid ""
"The proper converters are far easier to read and clearer in their intent."
msgstr ""

#: 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 ""

#: 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 ""

#: 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 ""

#: 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 ""

#: howto/clinic.rst:756
msgid ""
"All arguments to Argument Clinic converters are keyword-only. All Argument "
"Clinic converters accept the following arguments:"
msgstr ""

#: howto/clinic.rst:764 howto/clinic.rst:1252
msgid "``c_default``"
msgstr ""

#: 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 ""

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

#: 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 ""

#: howto/clinic.rst:771
msgid ""
"In addition, some converters accept additional arguments.  Here is a list of "
"these arguments, along with their meanings:"
msgstr ""

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

#: 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 ""

#: howto/clinic.rst:780
msgid "To accept ``None``, add ``NoneType`` to this set."
msgstr ""

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

#: 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 ""

#: howto/clinic.rst:790 howto/clinic.rst:1266
msgid "``converter``"
msgstr ""

#: 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 ""

#: howto/clinic.rst:795
msgid "``encoding``"
msgstr "``encoding``"

#: 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 ""

#: howto/clinic.rst:799
msgid "``subclass_of``"
msgstr ""

#: 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 ""

#: howto/clinic.rst:804 howto/clinic.rst:1238
msgid "``type``"
msgstr "``type``"

#: 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 ""

#: howto/clinic.rst:810
msgid "``zeroes``"
msgstr ""

#: 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 ""

#: 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 ""

#: 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 ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: howto/clinic.rst:841
msgid "``unsigned_long_long(bitwise=True)``"
msgstr ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: howto/clinic.rst:881
msgid ""
"One advantage of real converters is that they're more flexible than legacy "
"converters.  For example, the ``unsigned_int`` converter (and all the "
"``unsigned_`` converters) can be specified without ``bitwise=True``.  Their "
"default behavior performs range checking on the value, and they won't accept "
"negative numbers.  You just can't do that with a legacy converter!"
msgstr ""

#: howto/clinic.rst:887
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 ""

#: howto/clinic.rst:893
msgid "Py_buffer"
msgstr ""

#: howto/clinic.rst:895
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 ""

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

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

#: howto/clinic.rst:908
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 ""

#: howto/clinic.rst:916
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 ""

#: howto/clinic.rst:922
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 ""

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

#: howto/clinic.rst:937
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 ""

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

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

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

#: howto/clinic.rst:961
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 ""

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

#: howto/clinic.rst:971
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 ""

#: howto/clinic.rst:976
msgid "Consider the following example:"
msgstr "Examinons l'exemple suivant :"

#: howto/clinic.rst:982
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 ""

#: howto/clinic.rst:987
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 ""

#: howto/clinic.rst:995
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 ""

#: howto/clinic.rst:1000
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 ""

#: howto/clinic.rst:1009
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 ""

#: howto/clinic.rst:1014
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 ""

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

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

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

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

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

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

#: howto/clinic.rst:1029
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 ""

#: howto/clinic.rst:1035
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 ""

#: howto/clinic.rst:1039
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 ""

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

#: howto/clinic.rst:1048
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 ""

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

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

#: howto/clinic.rst:1076
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 ""

#: howto/clinic.rst:1081
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 ""

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

#: howto/clinic.rst:1089
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 ""

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

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

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

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

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

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

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

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

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

#: howto/clinic.rst:1119
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 ""

#: howto/clinic.rst:1123
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 ""

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

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

#: howto/clinic.rst:1132
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 ""

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

#: howto/clinic.rst:1143
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 ""

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

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

#: howto/clinic.rst:1160
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 ""

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

#: howto/clinic.rst:1172
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 ""

#: howto/clinic.rst:1188
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 ""

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

#: howto/clinic.rst:1213
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 ""

#: howto/clinic.rst:1219
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 ""

#: howto/clinic.rst:1225
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 ""

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

#: howto/clinic.rst:1236
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 ""

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

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

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

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

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

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

#: howto/clinic.rst:1255
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 ""

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

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

#: howto/clinic.rst:1269
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 ""

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

#: howto/clinic.rst:1274
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 ""

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

#: howto/clinic.rst:1290
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 ""

#: howto/clinic.rst:1296
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 ""

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

#: howto/clinic.rst:1304
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 ""

#: howto/clinic.rst:1308
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 ""

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

#: howto/clinic.rst:1318
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 ""

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

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

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

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

#: howto/clinic.rst:1342
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 ""

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

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

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

#: howto/clinic.rst:1352
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 ""

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

#: howto/clinic.rst:1361
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 ""

#: howto/clinic.rst:1367
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 ""

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

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

#: howto/clinic.rst:1379
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 ""

#: howto/clinic.rst:1394
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 ""

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

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

#: howto/clinic.rst:1411 howto/clinic.rst:1486 howto/clinic.rst:1564
msgid "``block``"
msgstr ""

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

#: howto/clinic.rst:1417 howto/clinic.rst:1513 howto/clinic.rst:1567
msgid "``buffer``"
msgstr ""

#: howto/clinic.rst:1414
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 ""

#: howto/clinic.rst:1428 howto/clinic.rst:1499 howto/clinic.rst:1593
msgid "``file``"
msgstr ""

#: howto/clinic.rst:1420
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 ""

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

#: howto/clinic.rst:1433 howto/clinic.rst:1526 howto/clinic.rst:1597
msgid "``two-pass``"
msgstr ""

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

#: howto/clinic.rst:1437 howto/clinic.rst:1560
msgid "``suppress``"
msgstr ""

#: howto/clinic.rst:1436
msgid "The text is suppressed—thrown away."
msgstr ""

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

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

#: howto/clinic.rst:1447
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 ""

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

#: howto/clinic.rst:1458
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 ""

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

#: howto/clinic.rst:1471
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 ""

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

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

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

#: howto/clinic.rst:1489
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 ""

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

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

#: howto/clinic.rst:1502
msgid ""
"Save up 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 ""

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

#: howto/clinic.rst:1516
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 ""

#: howto/clinic.rst:1523
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 ""

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

#: howto/clinic.rst:1529
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 ""

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#: howto/clinic.rst:1591
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 ""

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

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

#: howto/clinic.rst:1605
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 ""

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

#: howto/clinic.rst:1616
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 ""

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

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

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

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

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

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

#: howto/clinic.rst:1635
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 ""

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

#: howto/clinic.rst:1644
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 ""

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

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

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

#: howto/clinic.rst:1685
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 ""

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

#: howto/clinic.rst:1693
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 ""

#: howto/clinic.rst:1701
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 ""

#: howto/clinic.rst:1705
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 ""

#: howto/clinic.rst:1709
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 ""

#: howto/clinic.rst:1717
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 ""

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

#: howto/clinic.rst:1726
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 ""

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