# 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: 2023-01-23 09:57+0100\n" "PO-Revision-Date: 2018-07-03 10:48+0200\n" "Last-Translator: Julien Palard \n" "Language-Team: FRENCH \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 1.8.11\n" #: library/optparse.rst:2 msgid ":mod:`optparse` --- Parser for command line options" msgstr "" #: library/optparse.rst:11 msgid "**Source code:** :source:`Lib/optparse.py`" msgstr "**Code source :** :source:`Lib/optparse.py`" #: library/optparse.rst:13 msgid "" "The :mod:`optparse` module is deprecated and will not be developed further; " "development will continue with the :mod:`argparse` module." msgstr "" #: library/optparse.rst:19 msgid "" ":mod:`optparse` is a more convenient, flexible, and powerful library for " "parsing command-line options than the old :mod:`getopt` module. :mod:" "`optparse` uses a more declarative style of command-line parsing: you create " "an instance of :class:`OptionParser`, populate it with options, and parse " "the command line. :mod:`optparse` allows users to specify options in the " "conventional GNU/POSIX syntax, and additionally generates usage and help " "messages for you." msgstr "" #: library/optparse.rst:26 msgid "Here's an example of using :mod:`optparse` in a simple script::" msgstr "" #: library/optparse.rst:39 msgid "" "With these few lines of code, users of your script can now do the \"usual " "thing\" on the command-line, for example::" msgstr "" #: library/optparse.rst:44 msgid "" "As it parses the command line, :mod:`optparse` sets attributes of the " "``options`` object returned by :meth:`parse_args` based on user-supplied " "command-line values. When :meth:`parse_args` returns from parsing this " "command line, ``options.filename`` will be ``\"outfile\"`` and ``options." "verbose`` will be ``False``. :mod:`optparse` supports both long and short " "options, allows short options to be merged together, and allows options to " "be associated with their arguments in a variety of ways. Thus, the " "following command lines are all equivalent to the above example::" msgstr "" #: library/optparse.rst:58 msgid "Additionally, users can run one of the following ::" msgstr "" #: library/optparse.rst:63 msgid "" "and :mod:`optparse` will print out a brief summary of your script's options:" msgstr "" #: library/optparse.rst:74 msgid "" "where the value of *yourscript* is determined at runtime (normally from " "``sys.argv[0]``)." msgstr "" #: library/optparse.rst:81 msgid "Background" msgstr "" #: library/optparse.rst:83 msgid "" ":mod:`optparse` was explicitly designed to encourage the creation of " "programs with straightforward, conventional command-line interfaces. To " "that end, it supports only the most common command-line syntax and semantics " "conventionally used under Unix. If you are unfamiliar with these " "conventions, read this section to acquaint yourself with them." msgstr "" #: library/optparse.rst:93 msgid "Terminology" msgstr "" #: library/optparse.rst:104 msgid "argument" msgstr "argument" #: library/optparse.rst:96 msgid "" "a string entered on the command-line, and passed by the shell to ``execl()`` " "or ``execv()``. In Python, arguments are elements of ``sys.argv[1:]`` " "(``sys.argv[0]`` is the name of the program being executed). Unix shells " "also use the term \"word\"." msgstr "" #: library/optparse.rst:101 msgid "" "It is occasionally desirable to substitute an argument list other than ``sys." "argv[1:]``, so you should read \"argument\" as \"an element of ``sys." "argv[1:]``, or of some other list provided as a substitute for ``sys." "argv[1:]``\"." msgstr "" #: library/optparse.rst:134 msgid "option" msgstr "" #: library/optparse.rst:107 msgid "" "an argument used to supply extra information to guide or customize the " "execution of a program. There are many different syntaxes for options; the " "traditional Unix syntax is a hyphen (\"-\") followed by a single letter, e." "g. ``-x`` or ``-F``. Also, traditional Unix syntax allows multiple options " "to be merged into a single argument, e.g. ``-x -F`` is equivalent to ``-" "xF``. The GNU project introduced ``--`` followed by a series of hyphen-" "separated words, e.g. ``--file`` or ``--dry-run``. These are the only two " "option syntaxes provided by :mod:`optparse`." msgstr "" #: library/optparse.rst:116 msgid "Some other option syntaxes that the world has seen include:" msgstr "" #: library/optparse.rst:118 msgid "" "a hyphen followed by a few letters, e.g. ``-pf`` (this is *not* the same as " "multiple options merged into a single argument)" msgstr "" #: library/optparse.rst:121 msgid "" "a hyphen followed by a whole word, e.g. ``-file`` (this is technically " "equivalent to the previous syntax, but they aren't usually seen in the same " "program)" msgstr "" #: library/optparse.rst:125 msgid "" "a plus sign followed by a single letter, or a few letters, or a word, e.g. " "``+f``, ``+rgb``" msgstr "" #: library/optparse.rst:128 msgid "" "a slash followed by a letter, or a few letters, or a word, e.g. ``/f``, ``/" "file``" msgstr "" #: library/optparse.rst:131 msgid "" "These option syntaxes are not supported by :mod:`optparse`, and they never " "will be. This is deliberate: the first three are non-standard on any " "environment, and the last only makes sense if you're exclusively targeting " "Windows or certain legacy platforms (e.g. VMS, MS-DOS)." msgstr "" #: library/optparse.rst:160 msgid "option argument" msgstr "" #: library/optparse.rst:137 msgid "" "an argument that follows an option, is closely associated with that option, " "and is consumed from the argument list when that option is. With :mod:" "`optparse`, option arguments may either be in a separate argument from their " "option:" msgstr "" #: library/optparse.rst:147 msgid "or included in the same argument:" msgstr "" #: library/optparse.rst:154 msgid "" "Typically, a given option either takes an argument or it doesn't. Lots of " "people want an \"optional option arguments\" feature, meaning that some " "options will take an argument if they see it, and won't if they don't. This " "is somewhat controversial, because it makes parsing ambiguous: if ``-a`` " "takes an optional argument and ``-b`` is another option entirely, how do we " "interpret ``-ab``? Because of this ambiguity, :mod:`optparse` does not " "support this feature." msgstr "" #: library/optparse.rst:165 msgid "positional argument" msgstr "argument positionnel" #: library/optparse.rst:163 msgid "" "something leftover in the argument list after options have been parsed, i.e. " "after options and their arguments have been parsed and removed from the " "argument list." msgstr "" #: library/optparse.rst:171 msgid "required option" msgstr "" #: library/optparse.rst:168 msgid "" "an option that must be supplied on the command-line; note that the phrase " "\"required option\" is self-contradictory in English. :mod:`optparse` " "doesn't prevent you from implementing required options, but doesn't give you " "much help at it either." msgstr "" #: library/optparse.rst:173 msgid "For example, consider this hypothetical command-line::" msgstr "" #: library/optparse.rst:177 msgid "" "``-v`` and ``--report`` are both options. Assuming that ``--report`` takes " "one argument, ``report.txt`` is an option argument. ``foo`` and ``bar`` are " "positional arguments." msgstr "" #: library/optparse.rst:185 msgid "What are options for?" msgstr "" #: library/optparse.rst:187 msgid "" "Options are used to provide extra information to tune or customize the " "execution of a program. In case it wasn't clear, options are usually " "*optional*. A program should be able to run just fine with no options " "whatsoever. (Pick a random program from the Unix or GNU toolsets. Can it " "run without any options at all and still make sense? The main exceptions " "are ``find``, ``tar``, and ``dd``\\ ---all of which are mutant oddballs that " "have been rightly criticized for their non-standard syntax and confusing " "interfaces.)" msgstr "" #: library/optparse.rst:195 msgid "" "Lots of people want their programs to have \"required options\". Think " "about it. If it's required, then it's *not optional*! If there is a piece " "of information that your program absolutely requires in order to run " "successfully, that's what positional arguments are for." msgstr "" #: library/optparse.rst:200 msgid "" "As an example of good command-line interface design, consider the humble " "``cp`` utility, for copying files. It doesn't make much sense to try to " "copy files without supplying a destination and at least one source. Hence, " "``cp`` fails if you run it with no arguments. However, it has a flexible, " "useful syntax that does not require any options at all::" msgstr "" #: library/optparse.rst:209 msgid "" "You can get pretty far with just that. Most ``cp`` implementations provide " "a bunch of options to tweak exactly how the files are copied: you can " "preserve mode and modification time, avoid following symlinks, ask before " "clobbering existing files, etc. But none of this distracts from the core " "mission of ``cp``, which is to copy either one file to another, or several " "files to another directory." msgstr "" #: library/optparse.rst:220 msgid "What are positional arguments for?" msgstr "" #: library/optparse.rst:222 msgid "" "Positional arguments are for those pieces of information that your program " "absolutely, positively requires to run." msgstr "" #: library/optparse.rst:225 msgid "" "A good user interface should have as few absolute requirements as possible. " "If your program requires 17 distinct pieces of information in order to run " "successfully, it doesn't much matter *how* you get that information from the " "user---most people will give up and walk away before they successfully run " "the program. This applies whether the user interface is a command-line, a " "configuration file, or a GUI: if you make that many demands on your users, " "most of them will simply give up." msgstr "" #: library/optparse.rst:233 msgid "" "In short, try to minimize the amount of information that users are " "absolutely required to supply---use sensible defaults whenever possible. Of " "course, you also want to make your programs reasonably flexible. That's " "what options are for. Again, it doesn't matter if they are entries in a " "config file, widgets in the \"Preferences\" dialog of a GUI, or command-line " "options---the more options you implement, the more flexible your program is, " "and the more complicated its implementation becomes. Too much flexibility " "has drawbacks as well, of course; too many options can overwhelm users and " "make your code much harder to maintain." msgstr "" #: library/optparse.rst:246 msgid "Tutorial" msgstr "Tutoriel" #: library/optparse.rst:248 msgid "" "While :mod:`optparse` is quite flexible and powerful, it's also " "straightforward to use in most cases. This section covers the code patterns " "that are common to any :mod:`optparse`\\ -based program." msgstr "" #: library/optparse.rst:252 msgid "" "First, you need to import the OptionParser class; then, early in the main " "program, create an OptionParser instance::" msgstr "" #: library/optparse.rst:259 msgid "Then you can start defining options. The basic syntax is::" msgstr "" #: library/optparse.rst:264 msgid "" "Each option has one or more option strings, such as ``-f`` or ``--file``, " "and several option attributes that tell :mod:`optparse` what to expect and " "what to do when it encounters that option on the command line." msgstr "" #: library/optparse.rst:268 msgid "" "Typically, each option will have one short option string and one long option " "string, e.g.::" msgstr "" #: library/optparse.rst:273 msgid "" "You're free to define as many short option strings and as many long option " "strings as you like (including zero), as long as there is at least one " "option string overall." msgstr "" #: library/optparse.rst:277 msgid "" "The option strings passed to :meth:`OptionParser.add_option` are effectively " "labels for the option defined by that call. For brevity, we will frequently " "refer to *encountering an option* on the command line; in reality, :mod:" "`optparse` encounters *option strings* and looks up options from them." msgstr "" #: library/optparse.rst:283 msgid "" "Once all of your options are defined, instruct :mod:`optparse` to parse your " "program's command line::" msgstr "" #: library/optparse.rst:288 msgid "" "(If you like, you can pass a custom argument list to :meth:`parse_args`, but " "that's rarely necessary: by default it uses ``sys.argv[1:]``.)" msgstr "" #: library/optparse.rst:291 msgid ":meth:`parse_args` returns two values:" msgstr "" #: library/optparse.rst:293 msgid "" "``options``, an object containing values for all of your options---e.g. if " "``--file`` takes a single string argument, then ``options.file`` will be the " "filename supplied by the user, or ``None`` if the user did not supply that " "option" msgstr "" #: library/optparse.rst:298 msgid "" "``args``, the list of positional arguments leftover after parsing options" msgstr "" #: library/optparse.rst:300 msgid "" "This tutorial section only covers the four most important option " "attributes: :attr:`~Option.action`, :attr:`~Option.type`, :attr:`~Option." "dest` (destination), and :attr:`~Option.help`. Of these, :attr:`~Option." "action` is the most fundamental." msgstr "" #: library/optparse.rst:309 msgid "Understanding option actions" msgstr "" #: library/optparse.rst:311 msgid "" "Actions tell :mod:`optparse` what to do when it encounters an option on the " "command line. There is a fixed set of actions hard-coded into :mod:" "`optparse`; adding new actions is an advanced topic covered in section :ref:" "`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store a " "value in some variable---for example, take a string from the command line " "and store it in an attribute of ``options``." msgstr "" #: library/optparse.rst:318 msgid "" "If you don't specify an option action, :mod:`optparse` defaults to ``store``." msgstr "" #: library/optparse.rst:324 msgid "The store action" msgstr "" #: library/optparse.rst:326 msgid "" "The most common option action is ``store``, which tells :mod:`optparse` to " "take the next argument (or the remainder of the current argument), ensure " "that it is of the correct type, and store it to your chosen destination." msgstr "" #: library/optparse.rst:330 msgid "For example::" msgstr "Par exemple ::" #: library/optparse.rst:335 msgid "" "Now let's make up a fake command line and ask :mod:`optparse` to parse it::" msgstr "" #: library/optparse.rst:340 msgid "" "When :mod:`optparse` sees the option string ``-f``, it consumes the next " "argument, ``foo.txt``, and stores it in ``options.filename``. So, after " "this call to :meth:`parse_args`, ``options.filename`` is ``\"foo.txt\"``." msgstr "" #: library/optparse.rst:344 msgid "" "Some other option types supported by :mod:`optparse` are ``int`` and " "``float``. Here's an option that expects an integer argument::" msgstr "" #: library/optparse.rst:349 msgid "" "Note that this option has no long option string, which is perfectly " "acceptable. Also, there's no explicit action, since the default is ``store``." msgstr "" #: library/optparse.rst:352 msgid "" "Let's parse another fake command-line. This time, we'll jam the option " "argument right up against the option: since ``-n42`` (one argument) is " "equivalent to ``-n 42`` (two arguments), the code ::" msgstr "" #: library/optparse.rst:359 msgid "will print ``42``." msgstr "affichera ``42``." #: library/optparse.rst:361 msgid "" "If you don't specify a type, :mod:`optparse` assumes ``string``. Combined " "with the fact that the default action is ``store``, that means our first " "example can be a lot shorter::" msgstr "" #: library/optparse.rst:367 msgid "" "If you don't supply a destination, :mod:`optparse` figures out a sensible " "default from the option strings: if the first long option string is ``--foo-" "bar``, then the default destination is ``foo_bar``. If there are no long " "option strings, :mod:`optparse` looks at the first short option string: the " "default destination for ``-f`` is ``f``." msgstr "" #: library/optparse.rst:373 msgid "" ":mod:`optparse` also includes the built-in ``complex`` type. Adding types " "is covered in section :ref:`optparse-extending-optparse`." msgstr "" #: library/optparse.rst:380 msgid "Handling boolean (flag) options" msgstr "" #: library/optparse.rst:382 msgid "" "Flag options---set a variable to true or false when a particular option is " "seen---are quite common. :mod:`optparse` supports them with two separate " "actions, ``store_true`` and ``store_false``. For example, you might have a " "``verbose`` flag that is turned on with ``-v`` and off with ``-q``::" msgstr "" #: library/optparse.rst:390 msgid "" "Here we have two different options with the same destination, which is " "perfectly OK. (It just means you have to be a bit careful when setting " "default values---see below.)" msgstr "" #: library/optparse.rst:394 msgid "" "When :mod:`optparse` encounters ``-v`` on the command line, it sets " "``options.verbose`` to ``True``; when it encounters ``-q``, ``options." "verbose`` is set to ``False``." msgstr "" #: library/optparse.rst:402 msgid "Other actions" msgstr "" #: library/optparse.rst:404 msgid "Some other actions supported by :mod:`optparse` are:" msgstr "" #: library/optparse.rst:928 msgid "``\"store_const\"``" msgstr "``\"store_const\"``" #: library/optparse.rst:928 msgid "store a constant value, pre-set via :attr:`Option.const`" msgstr "" #: library/optparse.rst:937 msgid "``\"append\"``" msgstr "``\"append\"``" #: library/optparse.rst:937 msgid "append this option's argument to a list" msgstr "" #: library/optparse.rst:943 msgid "``\"count\"``" msgstr "``\"count\"``" #: library/optparse.rst:943 msgid "increment a counter by one" msgstr "" #: library/optparse.rst:946 msgid "``\"callback\"``" msgstr "``\"callback\"``" #: library/optparse.rst:946 msgid "call a specified function" msgstr "" #: library/optparse.rst:418 msgid "" "These are covered in section :ref:`optparse-reference-guide`, and section :" "ref:`optparse-option-callbacks`." msgstr "" #: library/optparse.rst:425 msgid "Default values" msgstr "Valeurs par défaut" #: library/optparse.rst:427 msgid "" "All of the above examples involve setting some variable (the " "\"destination\") when certain command-line options are seen. What happens " "if those options are never seen? Since we didn't supply any defaults, they " "are all set to ``None``. This is usually fine, but sometimes you want more " "control. :mod:`optparse` lets you supply a default value for each " "destination, which is assigned before the command line is parsed." msgstr "" #: library/optparse.rst:434 msgid "" "First, consider the verbose/quiet example. If we want :mod:`optparse` to " "set ``verbose`` to ``True`` unless ``-q`` is seen, then we can do this::" msgstr "" #: library/optparse.rst:440 msgid "" "Since default values apply to the *destination* rather than to any " "particular option, and these two options happen to have the same " "destination, this is exactly equivalent::" msgstr "" #: library/optparse.rst:447 msgid "Consider this::" msgstr "" #: library/optparse.rst:452 msgid "" "Again, the default value for ``verbose`` will be ``True``: the last default " "value supplied for any particular destination is the one that counts." msgstr "" #: library/optparse.rst:455 msgid "" "A clearer way to specify default values is the :meth:`set_defaults` method " "of OptionParser, which you can call at any time before calling :meth:" "`parse_args`::" msgstr "" #: library/optparse.rst:462 msgid "" "As before, the last value specified for a given option destination is the " "one that counts. For clarity, try to use one method or the other of setting " "default values, not both." msgstr "" #: library/optparse.rst:470 msgid "Generating help" msgstr "" #: library/optparse.rst:472 msgid "" ":mod:`optparse`'s ability to generate help and usage text automatically is " "useful for creating user-friendly command-line interfaces. All you have to " "do is supply a :attr:`~Option.help` value for each option, and optionally a " "short usage message for your whole program. Here's an OptionParser " "populated with user-friendly (documented) options::" msgstr "" #: library/optparse.rst:493 msgid "" "If :mod:`optparse` encounters either ``-h`` or ``--help`` on the command-" "line, or if you just call :meth:`parser.print_help`, it prints the following " "to standard output:" msgstr "" #: library/optparse.rst:510 msgid "" "(If the help output is triggered by a help option, :mod:`optparse` exits " "after printing the help text.)" msgstr "" #: library/optparse.rst:513 msgid "" "There's a lot going on here to help :mod:`optparse` generate the best " "possible help message:" msgstr "" #: library/optparse.rst:516 msgid "the script defines its own usage message::" msgstr "" #: library/optparse.rst:520 msgid "" ":mod:`optparse` expands ``%prog`` in the usage string to the name of the " "current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded " "string is then printed before the detailed option help." msgstr "" #: library/optparse.rst:524 msgid "" "If you don't supply a usage string, :mod:`optparse` uses a bland but " "sensible default: ``\"Usage: %prog [options]\"``, which is fine if your " "script doesn't take any positional arguments." msgstr "" #: library/optparse.rst:528 msgid "" "every option defines a help string, and doesn't worry about line-wrapping---" "\\ :mod:`optparse` takes care of wrapping lines and making the help output " "look good." msgstr "" #: library/optparse.rst:532 msgid "" "options that take a value indicate this fact in their automatically " "generated help message, e.g. for the \"mode\" option::" msgstr "" #: library/optparse.rst:537 msgid "" "Here, \"MODE\" is called the meta-variable: it stands for the argument that " "the user is expected to supply to ``-m``/``--mode``. By default, :mod:" "`optparse` converts the destination variable name to uppercase and uses that " "for the meta-variable. Sometimes, that's not what you want---for example, " "the ``--filename`` option explicitly sets ``metavar=\"FILE\"``, resulting in " "this automatically generated option description::" msgstr "" #: library/optparse.rst:546 msgid "" "This is important for more than just saving space, though: the manually " "written help text uses the meta-variable ``FILE`` to clue the user in that " "there's a connection between the semi-formal syntax ``-f FILE`` and the " "informal semantic description \"write output to FILE\". This is a simple but " "effective way to make your help text a lot clearer and more useful for end " "users." msgstr "" #: library/optparse.rst:552 msgid "" "options that have a default value can include ``%default`` in the help " "string---\\ :mod:`optparse` will replace it with :func:`str` of the option's " "default value. If an option has no default value (or the default value is " "``None``), ``%default`` expands to ``none``." msgstr "" #: library/optparse.rst:558 msgid "Grouping Options" msgstr "" #: library/optparse.rst:560 msgid "" "When dealing with many options, it is convenient to group these options for " "better help output. An :class:`OptionParser` can contain several option " "groups, each of which can contain several options." msgstr "" #: library/optparse.rst:564 msgid "An option group is obtained using the class :class:`OptionGroup`:" msgstr "" #: library/optparse.rst:1620 #, fuzzy msgid "where" msgstr "où :" #: library/optparse.rst:570 msgid "" "parser is the :class:`OptionParser` instance the group will be inserted in to" msgstr "" #: library/optparse.rst:572 msgid "title is the group title" msgstr "" #: library/optparse.rst:573 msgid "description, optional, is a long description of the group" msgstr "" #: library/optparse.rst:575 msgid "" ":class:`OptionGroup` inherits from :class:`OptionContainer` (like :class:" "`OptionParser`) and so the :meth:`add_option` method can be used to add an " "option to the group." msgstr "" #: library/optparse.rst:579 msgid "" "Once all the options are declared, using the :class:`OptionParser` method :" "meth:`add_option_group` the group is added to the previously defined parser." msgstr "" #: library/optparse.rst:582 msgid "" "Continuing with the parser defined in the previous section, adding an :class:" "`OptionGroup` to a parser is easy::" msgstr "" #: library/optparse.rst:591 msgid "This would result in the following help output:" msgstr "" #: library/optparse.rst:612 msgid "" "A bit more complete example might involve using more than one group: still " "extending the previous example::" msgstr "" #: library/optparse.rst:629 msgid "that results in the following output:" msgstr "" #: library/optparse.rst:655 msgid "" "Another interesting method, in particular when working programmatically with " "option groups is:" msgstr "" #: library/optparse.rst:660 msgid "" "Return the :class:`OptionGroup` to which the short or long option string " "*opt_str* (e.g. ``'-o'`` or ``'--option'``) belongs. If there's no such :" "class:`OptionGroup`, return ``None``." msgstr "" #: library/optparse.rst:667 msgid "Printing a version string" msgstr "" #: library/optparse.rst:669 msgid "" "Similar to the brief usage string, :mod:`optparse` can also print a version " "string for your program. You have to supply the string as the ``version`` " "argument to OptionParser::" msgstr "" #: library/optparse.rst:675 msgid "" "``%prog`` is expanded just like it is in ``usage``. Apart from that, " "``version`` can contain anything you like. When you supply it, :mod:" "`optparse` automatically adds a ``--version`` option to your parser. If it " "encounters this option on the command line, it expands your ``version`` " "string (by replacing ``%prog``), prints it to stdout, and exits." msgstr "" #: library/optparse.rst:681 msgid "For example, if your script is called ``/usr/bin/foo``:" msgstr "" #: library/optparse.rst:688 msgid "" "The following two methods can be used to print and get the ``version`` " "string:" msgstr "" #: library/optparse.rst:692 msgid "" "Print the version message for the current program (``self.version``) to " "*file* (default stdout). As with :meth:`print_usage`, any occurrence of " "``%prog`` in ``self.version`` is replaced with the name of the current " "program. Does nothing if ``self.version`` is empty or undefined." msgstr "" #: library/optparse.rst:699 msgid "" "Same as :meth:`print_version` but returns the version string instead of " "printing it." msgstr "" #: library/optparse.rst:706 msgid "How :mod:`optparse` handles errors" msgstr "" #: library/optparse.rst:708 msgid "" "There are two broad classes of errors that :mod:`optparse` has to worry " "about: programmer errors and user errors. Programmer errors are usually " "erroneous calls to :func:`OptionParser.add_option`, e.g. invalid option " "strings, unknown option attributes, missing option attributes, etc. These " "are dealt with in the usual way: raise an exception (either :exc:`optparse." "OptionError` or :exc:`TypeError`) and let the program crash." msgstr "" #: library/optparse.rst:715 msgid "" "Handling user errors is much more important, since they are guaranteed to " "happen no matter how stable your code is. :mod:`optparse` can automatically " "detect some user errors, such as bad option arguments (passing ``-n 4x`` " "where ``-n`` takes an integer argument), missing arguments (``-n`` at the " "end of the command line, where ``-n`` takes an argument of any type). Also, " "you can call :func:`OptionParser.error` to signal an application-defined " "error condition::" msgstr "" #: library/optparse.rst:728 msgid "" "In either case, :mod:`optparse` handles the error the same way: it prints " "the program's usage message and an error message to standard error and exits " "with error status 2." msgstr "" #: library/optparse.rst:732 msgid "" "Consider the first example above, where the user passes ``4x`` to an option " "that takes an integer:" msgstr "" #: library/optparse.rst:742 msgid "Or, where the user fails to pass a value at all:" msgstr "" #: library/optparse.rst:751 msgid "" ":mod:`optparse`\\ -generated error messages take care always to mention the " "option involved in the error; be sure to do the same when calling :func:" "`OptionParser.error` from your application code." msgstr "" #: library/optparse.rst:755 msgid "" "If :mod:`optparse`'s default error-handling behaviour does not suit your " "needs, you'll need to subclass OptionParser and override its :meth:" "`~OptionParser.exit` and/or :meth:`~OptionParser.error` methods." msgstr "" #: library/optparse.rst:763 msgid "Putting it all together" msgstr "" #: library/optparse.rst:765 msgid "Here's what :mod:`optparse`\\ -based scripts usually look like::" msgstr "" #: library/optparse.rst:793 msgid "Reference Guide" msgstr "" #: library/optparse.rst:799 msgid "Creating the parser" msgstr "" #: library/optparse.rst:801 msgid "" "The first step in using :mod:`optparse` is to create an OptionParser " "instance." msgstr "" #: library/optparse.rst:805 msgid "" "The OptionParser constructor has no required arguments, but a number of " "optional keyword arguments. You should always pass them as keyword " "arguments, i.e. do not rely on the order in which the arguments are declared." msgstr "" #: library/optparse.rst:814 msgid "``usage`` (default: ``\"%prog [options]\"``)" msgstr "" #: library/optparse.rst:810 msgid "" "The usage summary to print when your program is run incorrectly or with a " "help option. When :mod:`optparse` prints the usage string, it expands " "``%prog`` to ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you passed " "that keyword argument). To suppress a usage message, pass the special " "value :data:`optparse.SUPPRESS_USAGE`." msgstr "" #: library/optparse.rst:821 msgid "``option_list`` (default: ``[]``)" msgstr "" #: library/optparse.rst:817 msgid "" "A list of Option objects to populate the parser with. The options in " "``option_list`` are added after any options in ``standard_option_list`` (a " "class attribute that may be set by OptionParser subclasses), but before any " "version or help options. Deprecated; use :meth:`add_option` after creating " "the parser instead." msgstr "" #: library/optparse.rst:824 msgid "``option_class`` (default: optparse.Option)" msgstr "" #: library/optparse.rst:824 msgid "Class to use when adding options to the parser in :meth:`add_option`." msgstr "" #: library/optparse.rst:830 msgid "``version`` (default: ``None``)" msgstr "" #: library/optparse.rst:827 msgid "" "A version string to print when the user supplies a version option. If you " "supply a true value for ``version``, :mod:`optparse` automatically adds a " "version option with the single option string ``--version``. The substring " "``%prog`` is expanded the same as for ``usage``." msgstr "" #: library/optparse.rst:835 msgid "``conflict_handler`` (default: ``\"error\"``)" msgstr "" #: library/optparse.rst:833 msgid "" "Specifies what to do when options with conflicting option strings are added " "to the parser; see section :ref:`optparse-conflicts-between-options`." msgstr "" #: library/optparse.rst:841 msgid "``description`` (default: ``None``)" msgstr "" #: library/optparse.rst:838 msgid "" "A paragraph of text giving a brief overview of your program. :mod:`optparse` " "reformats this paragraph to fit the current terminal width and prints it " "when the user requests help (after ``usage``, but before the list of " "options)." msgstr "" #: library/optparse.rst:846 msgid "``formatter`` (default: a new :class:`IndentedHelpFormatter`)" msgstr "" #: library/optparse.rst:844 msgid "" "An instance of optparse.HelpFormatter that will be used for printing help " "text. :mod:`optparse` provides two concrete classes for this purpose: " "IndentedHelpFormatter and TitledHelpFormatter." msgstr "" #: library/optparse.rst:850 msgid "``add_help_option`` (default: ``True``)" msgstr "" #: library/optparse.rst:849 msgid "" "If true, :mod:`optparse` will add a help option (with option strings ``-h`` " "and ``--help``) to the parser." msgstr "" #: library/optparse.rst:854 msgid "``prog``" msgstr "``prog``" #: library/optparse.rst:853 msgid "" "The string to use when expanding ``%prog`` in ``usage`` and ``version`` " "instead of ``os.path.basename(sys.argv[0])``." msgstr "" #: library/optparse.rst:856 msgid "``epilog`` (default: ``None``)" msgstr "" #: library/optparse.rst:857 msgid "A paragraph of help text to print after the option help." msgstr "" #: library/optparse.rst:862 msgid "Populating the parser" msgstr "" #: library/optparse.rst:864 msgid "" "There are several ways to populate the parser with options. The preferred " "way is by using :meth:`OptionParser.add_option`, as shown in section :ref:" "`optparse-tutorial`. :meth:`add_option` can be called in one of two ways:" msgstr "" #: library/optparse.rst:868 msgid "pass it an Option instance (as returned by :func:`make_option`)" msgstr "" #: library/optparse.rst:870 msgid "" "pass it any combination of positional and keyword arguments that are " "acceptable to :func:`make_option` (i.e., to the Option constructor), and it " "will create the Option instance for you" msgstr "" #: library/optparse.rst:874 msgid "" "The other alternative is to pass a list of pre-constructed Option instances " "to the OptionParser constructor, as in::" msgstr "" #: library/optparse.rst:885 msgid "" "(:func:`make_option` is a factory function for creating Option instances; " "currently it is an alias for the Option constructor. A future version of :" "mod:`optparse` may split Option into several classes, and :func:" "`make_option` will pick the right class to instantiate. Do not instantiate " "Option directly.)" msgstr "" #: library/optparse.rst:894 msgid "Defining options" msgstr "" #: library/optparse.rst:896 msgid "" "Each Option instance represents a set of synonymous command-line option " "strings, e.g. ``-f`` and ``--file``. You can specify any number of short or " "long option strings, but you must specify at least one overall option string." msgstr "" #: library/optparse.rst:900 msgid "" "The canonical way to create an :class:`Option` instance is with the :meth:" "`add_option` method of :class:`OptionParser`." msgstr "" #: library/optparse.rst:906 msgid "To define an option with only a short option string::" msgstr "" #: library/optparse.rst:910 msgid "And to define an option with only a long option string::" msgstr "" #: library/optparse.rst:914 msgid "" "The keyword arguments define attributes of the new Option object. The most " "important option attribute is :attr:`~Option.action`, and it largely " "determines which other attributes are relevant or required. If you pass " "irrelevant option attributes, or fail to pass required ones, :mod:`optparse` " "raises an :exc:`OptionError` exception explaining your mistake." msgstr "" #: library/optparse.rst:920 msgid "" "An option's *action* determines what :mod:`optparse` does when it encounters " "this option on the command-line. The standard option actions hard-coded " "into :mod:`optparse` are:" msgstr "" #: library/optparse.rst:925 msgid "``\"store\"``" msgstr "``\"store\"``" #: library/optparse.rst:925 msgid "store this option's argument (default)" msgstr "" #: library/optparse.rst:931 msgid "``\"store_true\"``" msgstr "``\"store_true\"``" #: library/optparse.rst:931 #, fuzzy msgid "store ``True``" msgstr "``\"store_true\"``" #: library/optparse.rst:934 msgid "``\"store_false\"``" msgstr "``\"store_false\"``" #: library/optparse.rst:934 #, fuzzy msgid "store ``False``" msgstr "``\"store_false\"``" #: library/optparse.rst:940 msgid "``\"append_const\"``" msgstr "``\"append_const\"``" #: library/optparse.rst:940 msgid "append a constant value to a list, pre-set via :attr:`Option.const`" msgstr "" #: library/optparse.rst:1226 msgid "``\"help\"``" msgstr "``\"help\"``" #: library/optparse.rst:949 msgid "" "print a usage message including all options and the documentation for them" msgstr "" #: library/optparse.rst:951 msgid "" "(If you don't supply an action, the default is ``\"store\"``. For this " "action, you may also supply :attr:`~Option.type` and :attr:`~Option.dest` " "option attributes; see :ref:`optparse-standard-option-actions`.)" msgstr "" #: library/optparse.rst:955 msgid "" "As you can see, most actions involve storing or updating a value somewhere. :" "mod:`optparse` always creates a special object for this, conventionally " "called ``options`` (it happens to be an instance of :class:`optparse." "Values`). Option arguments (and various other values) are stored as " "attributes of this object, according to the :attr:`~Option.dest` " "(destination) option attribute." msgstr "" #: library/optparse.rst:961 msgid "For example, when you call ::" msgstr "" #: library/optparse.rst:965 msgid "" "one of the first things :mod:`optparse` does is create the ``options`` " "object::" msgstr "" #: library/optparse.rst:969 msgid "If one of the options in this parser is defined with ::" msgstr "" #: library/optparse.rst:973 msgid "and the command-line being parsed includes any of the following::" msgstr "" #: library/optparse.rst:980 msgid "" "then :mod:`optparse`, on seeing this option, will do the equivalent of ::" msgstr "" #: library/optparse.rst:984 msgid "" "The :attr:`~Option.type` and :attr:`~Option.dest` option attributes are " "almost as important as :attr:`~Option.action`, but :attr:`~Option.action` is " "the only one that makes sense for *all* options." msgstr "" #: library/optparse.rst:992 msgid "Option attributes" msgstr "" #: library/optparse.rst:994 msgid "" "The following option attributes may be passed as keyword arguments to :meth:" "`OptionParser.add_option`. If you pass an option attribute that is not " "relevant to a particular option, or fail to pass a required option " "attribute, :mod:`optparse` raises :exc:`OptionError`." msgstr "" #: library/optparse.rst:1001 msgid "(default: ``\"store\"``)" msgstr "" #: library/optparse.rst:1003 msgid "" "Determines :mod:`optparse`'s behaviour when this option is seen on the " "command line; the available options are documented :ref:`here `." msgstr "" #: library/optparse.rst:1009 msgid "(default: ``\"string\"``)" msgstr "" #: library/optparse.rst:1011 msgid "" "The argument type expected by this option (e.g., ``\"string\"`` or " "``\"int\"``); the available option types are documented :ref:`here `." msgstr "" #: library/optparse.rst:1067 msgid "(default: derived from option strings)" msgstr "" #: library/optparse.rst:1019 msgid "" "If the option's action implies writing or modifying a value somewhere, this " "tells :mod:`optparse` where to write it: :attr:`~Option.dest` names an " "attribute of the ``options`` object that :mod:`optparse` builds as it parses " "the command line." msgstr "" #: library/optparse.rst:1026 msgid "" "The value to use for this option's destination if the option is not seen on " "the command line. See also :meth:`OptionParser.set_defaults`." msgstr "" #: library/optparse.rst:1031 msgid "(default: 1)" msgstr "" #: library/optparse.rst:1033 msgid "" "How many arguments of type :attr:`~Option.type` should be consumed when this " "option is seen. If > 1, :mod:`optparse` will store a tuple of values to :" "attr:`~Option.dest`." msgstr "" #: library/optparse.rst:1039 msgid "For actions that store a constant value, the constant value to store." msgstr "" #: library/optparse.rst:1043 msgid "" "For options of type ``\"choice\"``, the list of strings the user may choose " "from." msgstr "" #: library/optparse.rst:1048 msgid "" "For options with action ``\"callback\"``, the callable to call when this " "option is seen. See section :ref:`optparse-option-callbacks` for detail on " "the arguments passed to the callable." msgstr "" #: library/optparse.rst:1055 msgid "" "Additional positional and keyword arguments to pass to ``callback`` after " "the four standard callback arguments." msgstr "" #: library/optparse.rst:1060 msgid "" "Help text to print for this option when listing all available options after " "the user supplies a :attr:`~Option.help` option (such as ``--help``). If no " "help text is supplied, the option will be listed without help text. To hide " "this option, use the special value :data:`optparse.SUPPRESS_HELP`." msgstr "" #: library/optparse.rst:1069 msgid "" "Stand-in for the option argument(s) to use when printing help text. See " "section :ref:`optparse-tutorial` for an example." msgstr "" #: library/optparse.rst:1076 msgid "Standard option actions" msgstr "" #: library/optparse.rst:1078 msgid "" "The various option actions all have slightly different requirements and " "effects. Most actions have several relevant option attributes which you may " "specify to guide :mod:`optparse`'s behaviour; a few have required " "attributes, which you must specify for any option using that action." msgstr "" #: library/optparse.rst:1083 msgid "" "``\"store\"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`, :attr:" "`~Option.nargs`, :attr:`~Option.choices`]" msgstr "" #: library/optparse.rst:1086 msgid "" "The option must be followed by an argument, which is converted to a value " "according to :attr:`~Option.type` and stored in :attr:`~Option.dest`. If :" "attr:`~Option.nargs` > 1, multiple arguments will be consumed from the " "command line; all will be converted according to :attr:`~Option.type` and " "stored to :attr:`~Option.dest` as a tuple. See the :ref:`optparse-standard-" "option-types` section." msgstr "" #: library/optparse.rst:1093 msgid "" "If :attr:`~Option.choices` is supplied (a list or tuple of strings), the " "type defaults to ``\"choice\"``." msgstr "" #: library/optparse.rst:1096 msgid "If :attr:`~Option.type` is not supplied, it defaults to ``\"string\"``." msgstr "" #: library/optparse.rst:1098 msgid "" "If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a " "destination from the first long option string (e.g., ``--foo-bar`` implies " "``foo_bar``). If there are no long option strings, :mod:`optparse` derives a " "destination from the first short option string (e.g., ``-f`` implies ``f``)." msgstr "" #: library/optparse.rst:1123 library/optparse.rst:1163 #: library/optparse.rst:1240 msgid "Example::" msgstr "Exemple ::" #: library/optparse.rst:1108 msgid "As it parses the command line ::" msgstr "" #: library/optparse.rst:1112 msgid ":mod:`optparse` will set ::" msgstr "" #: library/optparse.rst:1118 msgid "" "``\"store_const\"`` [required: :attr:`~Option.const`; relevant: :attr:" "`~Option.dest`]" msgstr "" #: library/optparse.rst:1121 msgid "The value :attr:`~Option.const` is stored in :attr:`~Option.dest`." msgstr "" #: library/optparse.rst:1132 msgid "If ``--noisy`` is seen, :mod:`optparse` will set ::" msgstr "" #: library/optparse.rst:1136 msgid "``\"store_true\"`` [relevant: :attr:`~Option.dest`]" msgstr "" #: library/optparse.rst:1138 msgid "" "A special case of ``\"store_const\"`` that stores ``True`` to :attr:`~Option." "dest`." msgstr "" #: library/optparse.rst:1141 msgid "``\"store_false\"`` [relevant: :attr:`~Option.dest`]" msgstr "" #: library/optparse.rst:1143 msgid "Like ``\"store_true\"``, but stores ``False``." msgstr "" #: library/optparse.rst:1150 msgid "" "``\"append\"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`, :attr:" "`~Option.nargs`, :attr:`~Option.choices`]" msgstr "" #: library/optparse.rst:1153 msgid "" "The option must be followed by an argument, which is appended to the list " "in :attr:`~Option.dest`. If no default value for :attr:`~Option.dest` is " "supplied, an empty list is automatically created when :mod:`optparse` first " "encounters this option on the command-line. If :attr:`~Option.nargs` > 1, " "multiple arguments are consumed, and a tuple of length :attr:`~Option.nargs` " "is appended to :attr:`~Option.dest`." msgstr "" #: library/optparse.rst:1160 msgid "" "The defaults for :attr:`~Option.type` and :attr:`~Option.dest` are the same " "as for the ``\"store\"`` action." msgstr "" #: library/optparse.rst:1167 msgid "" "If ``-t3`` is seen on the command-line, :mod:`optparse` does the equivalent " "of::" msgstr "" #: library/optparse.rst:1173 msgid "If, a little later on, ``--tracks=4`` is seen, it does::" msgstr "" #: library/optparse.rst:1177 msgid "" "The ``append`` action calls the ``append`` method on the current value of " "the option. This means that any default value specified must have an " "``append`` method. It also means that if the default value is non-empty, " "the default elements will be present in the parsed value for the option, " "with any values from the command line appended after those default values::" msgstr "" #: library/optparse.rst:1188 msgid "" "``\"append_const\"`` [required: :attr:`~Option.const`; relevant: :attr:" "`~Option.dest`]" msgstr "" #: library/optparse.rst:1191 msgid "" "Like ``\"store_const\"``, but the value :attr:`~Option.const` is appended " "to :attr:`~Option.dest`; as with ``\"append\"``, :attr:`~Option.dest` " "defaults to ``None``, and an empty list is automatically created the first " "time the option is encountered." msgstr "" #: library/optparse.rst:1196 msgid "``\"count\"`` [relevant: :attr:`~Option.dest`]" msgstr "" #: library/optparse.rst:1198 msgid "" "Increment the integer stored at :attr:`~Option.dest`. If no default value " "is supplied, :attr:`~Option.dest` is set to zero before being incremented " "the first time." msgstr "" #: library/optparse.rst:1206 msgid "" "The first time ``-v`` is seen on the command line, :mod:`optparse` does the " "equivalent of::" msgstr "" #: library/optparse.rst:1212 msgid "Every subsequent occurrence of ``-v`` results in ::" msgstr "" #: library/optparse.rst:1216 msgid "" "``\"callback\"`` [required: :attr:`~Option.callback`; relevant: :attr:" "`~Option.type`, :attr:`~Option.nargs`, :attr:`~Option.callback_args`, :attr:" "`~Option.callback_kwargs`]" msgstr "" #: library/optparse.rst:1220 msgid "" "Call the function specified by :attr:`~Option.callback`, which is called " "as ::" msgstr "" #: library/optparse.rst:1224 msgid "See section :ref:`optparse-option-callbacks` for more detail." msgstr "" #: library/optparse.rst:1228 msgid "" "Prints a complete help message for all the options in the current option " "parser. The help message is constructed from the ``usage`` string passed to " "OptionParser's constructor and the :attr:`~Option.help` string passed to " "every option." msgstr "" #: library/optparse.rst:1233 msgid "" "If no :attr:`~Option.help` string is supplied for an option, it will still " "be listed in the help message. To omit an option entirely, use the special " "value :data:`optparse.SUPPRESS_HELP`." msgstr "" #: library/optparse.rst:1237 msgid "" ":mod:`optparse` automatically adds a :attr:`~Option.help` option to all " "OptionParsers, so you do not normally need to create one." msgstr "" #: library/optparse.rst:1255 msgid "" "If :mod:`optparse` sees either ``-h`` or ``--help`` on the command line, it " "will print something like the following help message to stdout (assuming " "``sys.argv[0]`` is ``\"foo.py\"``):" msgstr "" #: library/optparse.rst:1268 msgid "" "After printing the help message, :mod:`optparse` terminates your process " "with ``sys.exit(0)``." msgstr "" #: library/optparse.rst:1271 msgid "``\"version\"``" msgstr "``\"version\"``" #: library/optparse.rst:1273 msgid "" "Prints the version number supplied to the OptionParser to stdout and exits. " "The version number is actually formatted and printed by the " "``print_version()`` method of OptionParser. Generally only relevant if the " "``version`` argument is supplied to the OptionParser constructor. As with :" "attr:`~Option.help` options, you will rarely create ``version`` options, " "since :mod:`optparse` automatically adds them when needed." msgstr "" #: library/optparse.rst:1284 msgid "Standard option types" msgstr "" #: library/optparse.rst:1286 msgid "" ":mod:`optparse` has five built-in option types: ``\"string\"``, ``\"int\"``, " "``\"choice\"``, ``\"float\"`` and ``\"complex\"``. If you need to add new " "option types, see section :ref:`optparse-extending-optparse`." msgstr "" #: library/optparse.rst:1290 msgid "" "Arguments to string options are not checked or converted in any way: the " "text on the command line is stored in the destination (or passed to the " "callback) as-is." msgstr "" #: library/optparse.rst:1293 msgid "Integer arguments (type ``\"int\"``) are parsed as follows:" msgstr "" #: library/optparse.rst:1295 msgid "if the number starts with ``0x``, it is parsed as a hexadecimal number" msgstr "" #: library/optparse.rst:1297 msgid "if the number starts with ``0``, it is parsed as an octal number" msgstr "" #: library/optparse.rst:1299 msgid "if the number starts with ``0b``, it is parsed as a binary number" msgstr "" #: library/optparse.rst:1301 msgid "otherwise, the number is parsed as a decimal number" msgstr "" #: library/optparse.rst:1304 msgid "" "The conversion is done by calling :func:`int` with the appropriate base (2, " "8, 10, or 16). If this fails, so will :mod:`optparse`, although with a more " "useful error message." msgstr "" #: library/optparse.rst:1308 msgid "" "``\"float\"`` and ``\"complex\"`` option arguments are converted directly " "with :func:`float` and :func:`complex`, with similar error-handling." msgstr "" #: library/optparse.rst:1311 msgid "" "``\"choice\"`` options are a subtype of ``\"string\"`` options. The :attr:" "`~Option.choices` option attribute (a sequence of strings) defines the set " "of allowed option arguments. :func:`optparse.check_choice` compares user-" "supplied option arguments against this master list and raises :exc:" "`OptionValueError` if an invalid string is given." msgstr "" #: library/optparse.rst:1321 msgid "Parsing arguments" msgstr "Analyse des arguments" #: library/optparse.rst:1323 msgid "" "The whole point of creating and populating an OptionParser is to call its :" "meth:`parse_args` method::" msgstr "" #: library/optparse.rst:1328 msgid "where the input parameters are" msgstr "" #: library/optparse.rst:1345 library/optparse.rst:1664 msgid "``args``" msgstr "``args``" #: library/optparse.rst:1331 msgid "the list of arguments to process (default: ``sys.argv[1:]``)" msgstr "" #: library/optparse.rst:1336 msgid "``values``" msgstr "``values``" #: library/optparse.rst:1334 msgid "" "an :class:`optparse.Values` object to store option arguments in (default: a " "new instance of :class:`Values`) -- if you give an existing object, the " "option defaults will not be initialized on it" msgstr "" #: library/optparse.rst:1338 msgid "and the return values are" msgstr "" #: library/optparse.rst:1342 msgid "``options``" msgstr "``options``" #: library/optparse.rst:1341 msgid "" "the same object that was passed in as ``values``, or the optparse.Values " "instance created by :mod:`optparse`" msgstr "" #: library/optparse.rst:1345 msgid "the leftover positional arguments after all options have been processed" msgstr "" #: library/optparse.rst:1347 msgid "" "The most common usage is to supply neither keyword argument. If you supply " "``values``, it will be modified with repeated :func:`setattr` calls (roughly " "one for every option argument stored to an option destination) and returned " "by :meth:`parse_args`." msgstr "" #: library/optparse.rst:1352 msgid "" "If :meth:`parse_args` encounters any errors in the argument list, it calls " "the OptionParser's :meth:`error` method with an appropriate end-user error " "message. This ultimately terminates your process with an exit status of 2 " "(the traditional Unix exit status for command-line errors)." msgstr "" #: library/optparse.rst:1361 msgid "Querying and manipulating your option parser" msgstr "" #: library/optparse.rst:1363 msgid "" "The default behavior of the option parser can be customized slightly, and " "you can also poke around your option parser and see what's there. " "OptionParser provides several methods to help you out:" msgstr "" #: library/optparse.rst:1369 msgid "" "Set parsing to stop on the first non-option. For example, if ``-a`` and ``-" "b`` are both simple options that take no arguments, :mod:`optparse` normally " "accepts this syntax::" msgstr "" #: library/optparse.rst:1375 msgid "and treats it as equivalent to ::" msgstr "" #: library/optparse.rst:1379 msgid "" "To disable this feature, call :meth:`disable_interspersed_args`. This " "restores traditional Unix syntax, where option parsing stops with the first " "non-option argument." msgstr "" #: library/optparse.rst:1383 msgid "" "Use this if you have a command processor which runs another command which " "has options of its own and you want to make sure these options don't get " "confused. For example, each command might have a different set of options." msgstr "" #: library/optparse.rst:1389 msgid "" "Set parsing to not stop on the first non-option, allowing interspersing " "switches with command arguments. This is the default behavior." msgstr "" #: library/optparse.rst:1394 msgid "" "Returns the Option instance with the option string *opt_str*, or ``None`` if " "no options have that option string." msgstr "" #: library/optparse.rst:1399 msgid "" "Return ``True`` if the OptionParser has an option with option string " "*opt_str* (e.g., ``-q`` or ``--verbose``)." msgstr "" #: library/optparse.rst:1404 msgid "" "If the :class:`OptionParser` has an option corresponding to *opt_str*, that " "option is removed. If that option provided any other option strings, all of " "those option strings become invalid. If *opt_str* does not occur in any " "option belonging to this :class:`OptionParser`, raises :exc:`ValueError`." msgstr "" #: library/optparse.rst:1413 msgid "Conflicts between options" msgstr "" #: library/optparse.rst:1415 msgid "" "If you're not careful, it's easy to define options with conflicting option " "strings::" msgstr "" #: library/optparse.rst:1422 msgid "" "(This is particularly true if you've defined your own OptionParser subclass " "with some standard options.)" msgstr "" #: library/optparse.rst:1425 msgid "" "Every time you add an option, :mod:`optparse` checks for conflicts with " "existing options. If it finds any, it invokes the current conflict-handling " "mechanism. You can set the conflict-handling mechanism either in the " "constructor::" msgstr "" #: library/optparse.rst:1431 msgid "or with a separate call::" msgstr "" #: library/optparse.rst:1435 msgid "The available conflict handlers are:" msgstr "" #: library/optparse.rst:1439 msgid "``\"error\"`` (default)" msgstr "" #: library/optparse.rst:1438 msgid "" "assume option conflicts are a programming error and raise :exc:" "`OptionConflictError`" msgstr "" #: library/optparse.rst:1443 msgid "``\"resolve\"``" msgstr "``\"resolve\"``" #: library/optparse.rst:1442 msgid "resolve option conflicts intelligently (see below)" msgstr "" #: library/optparse.rst:1445 msgid "" "As an example, let's define an :class:`OptionParser` that resolves conflicts " "intelligently and add conflicting options to it::" msgstr "" #: library/optparse.rst:1452 msgid "" "At this point, :mod:`optparse` detects that a previously added option is " "already using the ``-n`` option string. Since ``conflict_handler`` is " "``\"resolve\"``, it resolves the situation by removing ``-n`` from the " "earlier option's list of option strings. Now ``--dry-run`` is the only way " "for the user to activate that option. If the user asks for help, the help " "message will reflect that::" msgstr "" #: library/optparse.rst:1463 msgid "" "It's possible to whittle away the option strings for a previously added " "option until there are none left, and the user has no way of invoking that " "option from the command-line. In that case, :mod:`optparse` removes that " "option completely, so it doesn't show up in help text or anywhere else. " "Carrying on with our existing OptionParser::" msgstr "" #: library/optparse.rst:1471 msgid "" "At this point, the original ``-n``/``--dry-run`` option is no longer " "accessible, so :mod:`optparse` removes it, leaving this help text::" msgstr "" #: library/optparse.rst:1483 msgid "Cleanup" msgstr "Nettoyage" #: library/optparse.rst:1485 msgid "" "OptionParser instances have several cyclic references. This should not be a " "problem for Python's garbage collector, but you may wish to break the cyclic " "references explicitly by calling :meth:`~OptionParser.destroy` on your " "OptionParser once you are done with it. This is particularly useful in long-" "running applications where large object graphs are reachable from your " "OptionParser." msgstr "" #: library/optparse.rst:1496 msgid "Other methods" msgstr "" #: library/optparse.rst:1498 msgid "OptionParser supports several other public methods:" msgstr "" #: library/optparse.rst:1502 msgid "" "Set the usage string according to the rules described above for the " "``usage`` constructor keyword argument. Passing ``None`` sets the default " "usage string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage " "message." msgstr "" #: library/optparse.rst:1508 msgid "" "Print the usage message for the current program (``self.usage``) to *file* " "(default stdout). Any occurrence of the string ``%prog`` in ``self.usage`` " "is replaced with the name of the current program. Does nothing if ``self." "usage`` is empty or not defined." msgstr "" #: library/optparse.rst:1515 msgid "" "Same as :meth:`print_usage` but returns the usage string instead of printing " "it." msgstr "" #: library/optparse.rst:1520 msgid "" "Set default values for several option destinations at once. Using :meth:" "`set_defaults` is the preferred way to set default values for options, since " "multiple options can share the same destination. For example, if several " "\"mode\" options all set the same destination, any one of them can set the " "default, and the last one wins::" msgstr "" #: library/optparse.rst:1533 msgid "To avoid this confusion, use :meth:`set_defaults`::" msgstr "" #: library/optparse.rst:1545 msgid "Option Callbacks" msgstr "" #: library/optparse.rst:1547 msgid "" "When :mod:`optparse`'s built-in actions and types aren't quite enough for " "your needs, you have two choices: extend :mod:`optparse` or define a " "callback option. Extending :mod:`optparse` is more general, but overkill for " "a lot of simple cases. Quite often a simple callback is all you need." msgstr "" #: library/optparse.rst:1552 msgid "There are two steps to defining a callback option:" msgstr "" #: library/optparse.rst:1554 msgid "define the option itself using the ``\"callback\"`` action" msgstr "" #: library/optparse.rst:1556 msgid "" "write the callback; this is a function (or method) that takes at least four " "arguments, as described below" msgstr "" #: library/optparse.rst:1563 msgid "Defining a callback option" msgstr "" #: library/optparse.rst:1565 msgid "" "As always, the easiest way to define a callback option is by using the :meth:" "`OptionParser.add_option` method. Apart from :attr:`~Option.action`, the " "only option attribute you must specify is ``callback``, the function to " "call::" msgstr "" #: library/optparse.rst:1571 msgid "" "``callback`` is a function (or other callable object), so you must have " "already defined ``my_callback()`` when you create this callback option. In " "this simple case, :mod:`optparse` doesn't even know if ``-c`` takes any " "arguments, which usually means that the option takes no arguments---the mere " "presence of ``-c`` on the command-line is all it needs to know. In some " "circumstances, though, you might want your callback to consume an arbitrary " "number of command-line arguments. This is where writing callbacks gets " "tricky; it's covered later in this section." msgstr "" #: library/optparse.rst:1580 msgid "" ":mod:`optparse` always passes four particular arguments to your callback, " "and it will only pass additional arguments if you specify them via :attr:" "`~Option.callback_args` and :attr:`~Option.callback_kwargs`. Thus, the " "minimal callback function signature is::" msgstr "" #: library/optparse.rst:1587 msgid "The four arguments to a callback are described below." msgstr "" #: library/optparse.rst:1589 msgid "" "There are several other option attributes that you can supply when you " "define a callback option:" msgstr "" #: library/optparse.rst:1596 msgid ":attr:`~Option.type`" msgstr ":attr:`~Option.type`" #: library/optparse.rst:1593 msgid "" "has its usual meaning: as with the ``\"store\"`` or ``\"append\"`` actions, " "it instructs :mod:`optparse` to consume one argument and convert it to :attr:" "`~Option.type`. Rather than storing the converted value(s) anywhere, " "though, :mod:`optparse` passes it to your callback function." msgstr "" #: library/optparse.rst:1602 msgid ":attr:`~Option.nargs`" msgstr ":attr:`~Option.nargs`" #: library/optparse.rst:1599 msgid "" "also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will " "consume :attr:`~Option.nargs` arguments, each of which must be convertible " "to :attr:`~Option.type`. It then passes a tuple of converted values to your " "callback." msgstr "" #: library/optparse.rst:1605 msgid ":attr:`~Option.callback_args`" msgstr ":attr:`~Option.callback_args`" #: library/optparse.rst:1605 msgid "a tuple of extra positional arguments to pass to the callback" msgstr "" #: library/optparse.rst:1609 msgid ":attr:`~Option.callback_kwargs`" msgstr ":attr:`~Option.callback_kwargs`" #: library/optparse.rst:1608 msgid "a dictionary of extra keyword arguments to pass to the callback" msgstr "" #: library/optparse.rst:1614 msgid "How callbacks are called" msgstr "" #: library/optparse.rst:1616 msgid "All callbacks are called as follows::" msgstr "" #: library/optparse.rst:1623 msgid "``option``" msgstr "``option``" #: library/optparse.rst:1623 msgid "is the Option instance that's calling the callback" msgstr "" #: library/optparse.rst:1630 msgid "``opt_str``" msgstr "``opt_str``" #: library/optparse.rst:1626 msgid "" "is the option string seen on the command-line that's triggering the " "callback. (If an abbreviated long option was used, ``opt_str`` will be the " "full, canonical option string---e.g. if the user puts ``--foo`` on the " "command-line as an abbreviation for ``--foobar``, then ``opt_str`` will be " "``\"--foobar\"``.)" msgstr "" #: library/optparse.rst:1637 msgid "``value``" msgstr "``value``" #: library/optparse.rst:1633 msgid "" "is the argument to this option seen on the command-line. :mod:`optparse` " "will only expect an argument if :attr:`~Option.type` is set; the type of " "``value`` will be the type implied by the option's type. If :attr:`~Option." "type` for this option is ``None`` (no argument expected), then ``value`` " "will be ``None``. If :attr:`~Option.nargs` > 1, ``value`` will be a tuple " "of values of the appropriate type." msgstr "" #: library/optparse.rst:1660 msgid "``parser``" msgstr "``parser``" #: library/optparse.rst:1640 msgid "" "is the OptionParser instance driving the whole thing, mainly useful because " "you can access some other interesting data through its instance attributes:" msgstr "" #: library/optparse.rst:1647 msgid "``parser.largs``" msgstr "``parser.largs``" #: library/optparse.rst:1644 msgid "" "the current list of leftover arguments, ie. arguments that have been " "consumed but are neither options nor option arguments. Feel free to modify " "``parser.largs``, e.g. by adding more arguments to it. (This list will " "become ``args``, the second return value of :meth:`parse_args`.)" msgstr "" #: library/optparse.rst:1653 msgid "``parser.rargs``" msgstr "``parser.rargs``" #: library/optparse.rst:1650 msgid "" "the current list of remaining arguments, ie. with ``opt_str`` and ``value`` " "(if applicable) removed, and only the arguments following them still there. " "Feel free to modify ``parser.rargs``, e.g. by consuming more arguments." msgstr "" #: library/optparse.rst:1660 msgid "``parser.values``" msgstr "``parser.values``" #: library/optparse.rst:1656 msgid "" "the object where option values are by default stored (an instance of " "optparse.OptionValues). This lets callbacks use the same mechanism as the " "rest of :mod:`optparse` for storing option values; you don't need to mess " "around with globals or closures. You can also access or modify the value(s) " "of any options already encountered on the command-line." msgstr "" #: library/optparse.rst:1663 msgid "" "is a tuple of arbitrary positional arguments supplied via the :attr:`~Option." "callback_args` option attribute." msgstr "" #: library/optparse.rst:1669 msgid "``kwargs``" msgstr "``kwargs``" #: library/optparse.rst:1667 msgid "" "is a dictionary of arbitrary keyword arguments supplied via :attr:`~Option." "callback_kwargs`." msgstr "" #: library/optparse.rst:1674 msgid "Raising errors in a callback" msgstr "" #: library/optparse.rst:1676 msgid "" "The callback function should raise :exc:`OptionValueError` if there are any " "problems with the option or its argument(s). :mod:`optparse` catches this " "and terminates the program, printing the error message you supply to " "stderr. Your message should be clear, concise, accurate, and mention the " "option at fault. Otherwise, the user will have a hard time figuring out what " "they did wrong." msgstr "" #: library/optparse.rst:1686 msgid "Callback example 1: trivial callback" msgstr "" #: library/optparse.rst:1688 msgid "" "Here's an example of a callback option that takes no arguments, and simply " "records that the option was seen::" msgstr "" #: library/optparse.rst:1696 msgid "Of course, you could do that with the ``\"store_true\"`` action." msgstr "" #: library/optparse.rst:1702 msgid "Callback example 2: check option order" msgstr "" #: library/optparse.rst:1704 msgid "" "Here's a slightly more interesting example: record the fact that ``-a`` is " "seen, but blow up if it comes after ``-b`` in the command-line. ::" msgstr "" #: library/optparse.rst:1719 msgid "Callback example 3: check option order (generalized)" msgstr "" #: library/optparse.rst:1721 msgid "" "If you want to re-use this callback for several similar options (set a flag, " "but blow up if ``-b`` has already been seen), it needs a bit of work: the " "error message and the flag that it sets must be generalized. ::" msgstr "" #: library/optparse.rst:1738 msgid "Callback example 4: check arbitrary condition" msgstr "" #: library/optparse.rst:1740 msgid "" "Of course, you could put any condition in there---you're not limited to " "checking the values of already-defined options. For example, if you have " "options that should not be called when the moon is full, all you have to do " "is this::" msgstr "" #: library/optparse.rst:1753 msgid "" "(The definition of ``is_moon_full()`` is left as an exercise for the reader.)" msgstr "" #: library/optparse.rst:1759 msgid "Callback example 5: fixed arguments" msgstr "" #: library/optparse.rst:1761 msgid "" "Things get slightly more interesting when you define callback options that " "take a fixed number of arguments. Specifying that a callback option takes " "arguments is similar to defining a ``\"store\"`` or ``\"append\"`` option: " "if you define :attr:`~Option.type`, then the option takes one argument that " "must be convertible to that type; if you further define :attr:`~Option." "nargs`, then the option takes :attr:`~Option.nargs` arguments." msgstr "" #: library/optparse.rst:1768 msgid "" "Here's an example that just emulates the standard ``\"store\"`` action::" msgstr "" #: library/optparse.rst:1777 msgid "" "Note that :mod:`optparse` takes care of consuming 3 arguments and converting " "them to integers for you; all you have to do is store them. (Or whatever; " "obviously you don't need a callback for this example.)" msgstr "" #: library/optparse.rst:1785 msgid "Callback example 6: variable arguments" msgstr "" #: library/optparse.rst:1787 msgid "" "Things get hairy when you want an option to take a variable number of " "arguments. For this case, you must write a callback, as :mod:`optparse` " "doesn't provide any built-in capabilities for it. And you have to deal with " "certain intricacies of conventional Unix command-line parsing that :mod:" "`optparse` normally handles for you. In particular, callbacks should " "implement the conventional rules for bare ``--`` and ``-`` arguments:" msgstr "" #: library/optparse.rst:1794 msgid "either ``--`` or ``-`` can be option arguments" msgstr "" #: library/optparse.rst:1796 msgid "" "bare ``--`` (if not the argument to some option): halt command-line " "processing and discard the ``--``" msgstr "" #: library/optparse.rst:1799 msgid "" "bare ``-`` (if not the argument to some option): halt command-line " "processing but keep the ``-`` (append it to ``parser.largs``)" msgstr "" #: library/optparse.rst:1802 msgid "" "If you want an option that takes a variable number of arguments, there are " "several subtle, tricky issues to worry about. The exact implementation you " "choose will be based on which trade-offs you're willing to make for your " "application (which is why :mod:`optparse` doesn't support this sort of thing " "directly)." msgstr "" #: library/optparse.rst:1808 msgid "" "Nevertheless, here's a stab at a callback for an option with variable " "arguments::" msgstr "" #: library/optparse.rst:1842 msgid "Extending :mod:`optparse`" msgstr "" #: library/optparse.rst:1844 msgid "" "Since the two major controlling factors in how :mod:`optparse` interprets " "command-line options are the action and type of each option, the most likely " "direction of extension is to add new actions and new types." msgstr "" #: library/optparse.rst:1852 msgid "Adding new types" msgstr "" #: library/optparse.rst:1854 msgid "" "To add new types, you need to define your own subclass of :mod:`optparse`'s :" "class:`Option` class. This class has a couple of attributes that define :" "mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option." "TYPE_CHECKER`." msgstr "" #: library/optparse.rst:1860 msgid "" "A tuple of type names; in your subclass, simply define a new tuple :attr:" "`TYPES` that builds on the standard one." msgstr "" #: library/optparse.rst:1865 msgid "" "A dictionary mapping type names to type-checking functions. A type-checking " "function has the following signature::" msgstr "" #: library/optparse.rst:1870 msgid "" "where ``option`` is an :class:`Option` instance, ``opt`` is an option string " "(e.g., ``-f``), and ``value`` is the string from the command line that must " "be checked and converted to your desired type. ``check_mytype()`` should " "return an object of the hypothetical type ``mytype``. The value returned by " "a type-checking function will wind up in the OptionValues instance returned " "by :meth:`OptionParser.parse_args`, or be passed to a callback as the " "``value`` parameter." msgstr "" #: library/optparse.rst:1878 msgid "" "Your type-checking function should raise :exc:`OptionValueError` if it " "encounters any problems. :exc:`OptionValueError` takes a single string " "argument, which is passed as-is to :class:`OptionParser`'s :meth:`error` " "method, which in turn prepends the program name and the string ``\"error:" "\"`` and prints everything to stderr before terminating the process." msgstr "" #: library/optparse.rst:1884 msgid "" "Here's a silly example that demonstrates adding a ``\"complex\"`` option " "type to parse Python-style complex numbers on the command line. (This is " "even sillier than it used to be, because :mod:`optparse` 1.3 added built-in " "support for complex numbers, but never mind.)" msgstr "" #: library/optparse.rst:1889 msgid "First, the necessary imports::" msgstr "" #: library/optparse.rst:1894 msgid "" "You need to define your type-checker first, since it's referred to later (in " "the :attr:`~Option.TYPE_CHECKER` class attribute of your Option subclass)::" msgstr "" #: library/optparse.rst:1904 msgid "Finally, the Option subclass::" msgstr "" #: library/optparse.rst:1911 msgid "" "(If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would " "end up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:" "`optparse`'s Option class. This being Python, nothing stops you from doing " "that except good manners and common sense.)" msgstr "" #: library/optparse.rst:1916 msgid "" "That's it! Now you can write a script that uses the new option type just " "like any other :mod:`optparse`\\ -based script, except you have to instruct " "your OptionParser to use MyOption instead of Option::" msgstr "" #: library/optparse.rst:1923 msgid "" "Alternately, you can build your own option list and pass it to OptionParser; " "if you don't use :meth:`add_option` in the above way, you don't need to tell " "OptionParser which option class to use::" msgstr "" #: library/optparse.rst:1934 msgid "Adding new actions" msgstr "" #: library/optparse.rst:1936 msgid "" "Adding new actions is a bit trickier, because you have to understand that :" "mod:`optparse` has a couple of classifications for actions:" msgstr "" #: library/optparse.rst:1942 msgid "\"store\" actions" msgstr "" #: library/optparse.rst:1940 msgid "" "actions that result in :mod:`optparse` storing a value to an attribute of " "the current OptionValues instance; these options require a :attr:`~Option." "dest` attribute to be supplied to the Option constructor." msgstr "" #: library/optparse.rst:1948 msgid "\"typed\" actions" msgstr "" #: library/optparse.rst:1945 msgid "" "actions that take a value from the command line and expect it to be of a " "certain type; or rather, a string that can be converted to a certain type. " "These options require a :attr:`~Option.type` attribute to the Option " "constructor." msgstr "" #: library/optparse.rst:1950 msgid "" "These are overlapping sets: some default \"store\" actions are " "``\"store\"``, ``\"store_const\"``, ``\"append\"``, and ``\"count\"``, while " "the default \"typed\" actions are ``\"store\"``, ``\"append\"``, and " "``\"callback\"``." msgstr "" #: library/optparse.rst:1954 msgid "" "When you add an action, you need to categorize it by listing it in at least " "one of the following class attributes of Option (all are lists of strings):" msgstr "" #: library/optparse.rst:1959 msgid "All actions must be listed in ACTIONS." msgstr "" #: library/optparse.rst:1963 msgid "\"store\" actions are additionally listed here." msgstr "" #: library/optparse.rst:1967 msgid "\"typed\" actions are additionally listed here." msgstr "" #: library/optparse.rst:1971 msgid "" "Actions that always take a type (i.e. whose options always take a value) are " "additionally listed here. The only effect of this is that :mod:`optparse` " "assigns the default type, ``\"string\"``, to options with no explicit type " "whose action is listed in :attr:`ALWAYS_TYPED_ACTIONS`." msgstr "" #: library/optparse.rst:1976 msgid "" "In order to actually implement your new action, you must override Option's :" "meth:`take_action` method and add a case that recognizes your action." msgstr "" #: library/optparse.rst:1979 msgid "" "For example, let's add an ``\"extend\"`` action. This is similar to the " "standard ``\"append\"`` action, but instead of taking a single value from " "the command-line and appending it to an existing list, ``\"extend\"`` will " "take multiple values in a single comma-delimited string, and extend an " "existing list with them. That is, if ``--names`` is an ``\"extend\"`` " "option of type ``\"string\"``, the command line ::" msgstr "" #: library/optparse.rst:1988 msgid "would result in a list ::" msgstr "" #: library/optparse.rst:1992 msgid "Again we define a subclass of Option::" msgstr "" #: library/optparse.rst:2009 msgid "Features of note:" msgstr "" #: library/optparse.rst:2011 msgid "" "``\"extend\"`` both expects a value on the command-line and stores that " "value somewhere, so it goes in both :attr:`~Option.STORE_ACTIONS` and :attr:" "`~Option.TYPED_ACTIONS`." msgstr "" #: library/optparse.rst:2015 msgid "" "to ensure that :mod:`optparse` assigns the default type of ``\"string\"`` to " "``\"extend\"`` actions, we put the ``\"extend\"`` action in :attr:`~Option." "ALWAYS_TYPED_ACTIONS` as well." msgstr "" #: library/optparse.rst:2019 msgid "" ":meth:`MyOption.take_action` implements just this one new action, and passes " "control back to :meth:`Option.take_action` for the standard :mod:`optparse` " "actions." msgstr "" #: library/optparse.rst:2023 msgid "" "``values`` is an instance of the optparse_parser.Values class, which " "provides the very useful :meth:`ensure_value` method. :meth:`ensure_value` " "is essentially :func:`getattr` with a safety valve; it is called as ::" msgstr "" #: library/optparse.rst:2029 msgid "" "If the ``attr`` attribute of ``values`` doesn't exist or is ``None``, then " "ensure_value() first sets it to ``value``, and then returns 'value. This is " "very handy for actions like ``\"extend\"``, ``\"append\"``, and " "``\"count\"``, all of which accumulate data in a variable and expect that " "variable to be of a certain type (a list for the first two, an integer for " "the latter). Using :meth:`ensure_value` means that scripts using your " "action don't have to worry about setting a default value for the option " "destinations in question; they can just leave the default as ``None`` and :" "meth:`ensure_value` will take care of getting it right when it's needed." msgstr ""