forked from AFPy/python-docs-fr
13517 lines
476 KiB
Plaintext
13517 lines
476 KiB
Plaintext
# SOME DESCRIPTIVE TITLE.
|
||
# Copyright (C) 2001-2016, Python Software Foundation
|
||
# This file is distributed under the same license as the Python package.
|
||
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
|
||
#
|
||
#, fuzzy
|
||
msgid ""
|
||
msgstr ""
|
||
"Project-Id-Version: Python 3.6\n"
|
||
"Report-Msgid-Bugs-To: \n"
|
||
"POT-Creation-Date: 2016-10-17 21:44+0200\n"
|
||
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
||
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
||
"Language-Team: LANGUAGE <LL@li.org>\n"
|
||
"MIME-Version: 1.0\n"
|
||
"Content-Type: text/plain; charset=UTF-8\n"
|
||
"Content-Transfer-Encoding: 8bit\n"
|
||
|
||
#: ../Doc/howto/argparse.rst:3
|
||
msgid "Argparse Tutorial"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:5
|
||
msgid "Tshepang Lekhonkhobe"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:9
|
||
msgid ""
|
||
"This tutorial is intended to be a gentle introduction to :mod:`argparse`, "
|
||
"the recommended command-line parsing module in the Python standard library."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:14
|
||
msgid ""
|
||
"There are two other modules that fulfill the same task, namely :mod:`getopt` "
|
||
"(an equivalent for :c:func:`getopt` from the C language) and the deprecated :"
|
||
"mod:`optparse`. Note also that :mod:`argparse` is based on :mod:`optparse`, "
|
||
"and therefore very similar in terms of usage."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:22
|
||
msgid "Concepts"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:24
|
||
msgid ""
|
||
"Let's show the sort of functionality that we are going to explore in this "
|
||
"introductory tutorial by making use of the :command:`ls` command:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:46
|
||
msgid "A few concepts we can learn from the four commands:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:48
|
||
msgid ""
|
||
"The :command:`ls` command is useful when run without any options at all. It "
|
||
"defaults to displaying the contents of the current directory."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:51
|
||
msgid ""
|
||
"If we want beyond what it provides by default, we tell it a bit more. In "
|
||
"this case, we want it to display a different directory, ``pypy``. What we "
|
||
"did is specify what is known as a positional argument. It's named so because "
|
||
"the program should know what to do with the value, solely based on where it "
|
||
"appears on the command line. This concept is more relevant to a command "
|
||
"like :command:`cp`, whose most basic usage is ``cp SRC DEST``. The first "
|
||
"position is *what you want copied,* and the second position is *where you "
|
||
"want it copied to*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:60
|
||
msgid ""
|
||
"Now, say we want to change behaviour of the program. In our example, we "
|
||
"display more info for each file instead of just showing the file names. The "
|
||
"``-l`` in that case is known as an optional argument."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:64
|
||
msgid ""
|
||
"That's a snippet of the help text. It's very useful in that you can come "
|
||
"across a program you have never used before, and can figure out how it works "
|
||
"simply by reading its help text."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:70
|
||
msgid "The basics"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:72
|
||
msgid "Let us start with a very simple example which does (almost) nothing::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:78 ../Doc/howto/argparse.rst:186
|
||
#: ../Doc/howto/argparse.rst:207
|
||
msgid "Following is a result of running the code:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:95 ../Doc/howto/argparse.rst:252
|
||
#: ../Doc/howto/argparse.rst:296
|
||
msgid "Here is what is happening:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:97
|
||
msgid ""
|
||
"Running the script without any options results in nothing displayed to "
|
||
"stdout. Not so useful."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:100
|
||
msgid ""
|
||
"The second one starts to display the usefulness of the :mod:`argparse` "
|
||
"module. We have done almost nothing, but already we get a nice help message."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:103
|
||
msgid ""
|
||
"The ``--help`` option, which can also be shortened to ``-h``, is the only "
|
||
"option we get for free (i.e. no need to specify it). Specifying anything "
|
||
"else results in an error. But even then, we do get a useful usage message, "
|
||
"also for free."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:110
|
||
msgid "Introducing Positional arguments"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:112
|
||
msgid "An example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:120
|
||
msgid "And running the code:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:138
|
||
msgid "Here is what's happening:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:140
|
||
msgid ""
|
||
"We've added the :meth:`add_argument` method, which is what we use to specify "
|
||
"which command-line options the program is willing to accept. In this case, "
|
||
"I've named it ``echo`` so that it's in line with its function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:144
|
||
msgid "Calling our program now requires us to specify an option."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:146
|
||
msgid ""
|
||
"The :meth:`parse_args` method actually returns some data from the options "
|
||
"specified, in this case, ``echo``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:149
|
||
msgid ""
|
||
"The variable is some form of 'magic' that :mod:`argparse` performs for free "
|
||
"(i.e. no need to specify which variable that value is stored in). You will "
|
||
"also notice that its name matches the string argument given to the method, "
|
||
"``echo``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:154
|
||
msgid ""
|
||
"Note however that, although the help display looks nice and all, it "
|
||
"currently is not as helpful as it can be. For example we see that we got "
|
||
"``echo`` as a positional argument, but we don't know what it does, other "
|
||
"than by guessing or by reading the source code. So, let's make it a bit more "
|
||
"useful::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:165
|
||
msgid "And we get:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:178
|
||
msgid "Now, how about doing something even more useful::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:196
|
||
msgid ""
|
||
"That didn't go so well. That's because :mod:`argparse` treats the options we "
|
||
"give it as strings, unless we tell it otherwise. So, let's tell :mod:"
|
||
"`argparse` to treat that input as an integer::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:217
|
||
msgid ""
|
||
"That went well. The program now even helpfully quits on bad illegal input "
|
||
"before proceeding."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:222
|
||
msgid "Introducing Optional arguments"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:224
|
||
msgid ""
|
||
"So far we, have been playing with positional arguments. Let us have a look "
|
||
"on how to add optional ones::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:234 ../Doc/howto/argparse.rst:280
|
||
#: ../Doc/howto/argparse.rst:396 ../Doc/howto/argparse.rst:430
|
||
msgid "And the output:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:254
|
||
msgid ""
|
||
"The program is written so as to display something when ``--verbosity`` is "
|
||
"specified and display nothing when not."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:257
|
||
msgid ""
|
||
"To show that the option is actually optional, there is no error when running "
|
||
"the program without it. Note that by default, if an optional argument isn't "
|
||
"used, the relevant variable, in this case :attr:`args.verbosity`, is given "
|
||
"``None`` as a value, which is the reason it fails the truth test of the :"
|
||
"keyword:`if` statement."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:263
|
||
msgid "The help message is a bit different."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:265
|
||
msgid ""
|
||
"When using the ``--verbosity`` option, one must also specify some value, any "
|
||
"value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:268
|
||
msgid ""
|
||
"The above example accepts arbitrary integer values for ``--verbosity``, but "
|
||
"for our simple program, only two values are actually useful, ``True`` or "
|
||
"``False``. Let's modify the code accordingly::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:298
|
||
msgid ""
|
||
"The option is now more of a flag than something that requires a value. We "
|
||
"even changed the name of the option to match that idea. Note that we now "
|
||
"specify a new keyword, ``action``, and give it the value ``\"store_true\"``. "
|
||
"This means that, if the option is specified, assign the value ``True`` to :"
|
||
"data:`args.verbose`. Not specifying it implies ``False``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:305
|
||
msgid ""
|
||
"It complains when you specify a value, in true spirit of what flags actually "
|
||
"are."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:308
|
||
msgid "Notice the different help text."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:312
|
||
msgid "Short options"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:314
|
||
msgid ""
|
||
"If you are familiar with command line usage, you will notice that I haven't "
|
||
"yet touched on the topic of short versions of the options. It's quite "
|
||
"simple::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:326
|
||
msgid "And here goes:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:339
|
||
msgid "Note that the new ability is also reflected in the help text."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:343
|
||
msgid "Combining Positional and Optional arguments"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:345
|
||
msgid "Our program keeps growing in complexity::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:360
|
||
msgid "And now the output:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:374
|
||
msgid "We've brought back a positional argument, hence the complaint."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:376
|
||
msgid "Note that the order does not matter."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:378
|
||
msgid ""
|
||
"How about we give this program of ours back the ability to have multiple "
|
||
"verbosity values, and actually get to use them::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:412
|
||
msgid ""
|
||
"These all look good except the last one, which exposes a bug in our program. "
|
||
"Let's fix it by restricting the values the ``--verbosity`` option can "
|
||
"accept::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:448
|
||
msgid ""
|
||
"Note that the change also reflects both in the error message as well as the "
|
||
"help string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:451
|
||
msgid ""
|
||
"Now, let's use a different approach of playing with verbosity, which is "
|
||
"pretty common. It also matches the way the CPython executable handles its "
|
||
"own verbosity argument (check the output of ``python --help``)::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:470
|
||
msgid ""
|
||
"We have introduced another action, \"count\", to count the number of "
|
||
"occurrences of a specific optional arguments:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:498
|
||
msgid ""
|
||
"Yes, it's now more of a flag (similar to ``action=\"store_true\"``) in the "
|
||
"previous version of our script. That should explain the complaint."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:501
|
||
msgid "It also behaves similar to \"store_true\" action."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:503
|
||
msgid ""
|
||
"Now here's a demonstration of what the \"count\" action gives. You've "
|
||
"probably seen this sort of usage before."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:506
|
||
msgid ""
|
||
"And if you don't specify the ``-v`` flag, that flag is considered to have "
|
||
"``None`` value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:509
|
||
msgid ""
|
||
"As should be expected, specifying the long form of the flag, we should get "
|
||
"the same output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:512
|
||
msgid ""
|
||
"Sadly, our help output isn't very informative on the new ability our script "
|
||
"has acquired, but that can always be fixed by improving the documentation "
|
||
"for our script (e.g. via the ``help`` keyword argument)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:516
|
||
msgid "That last output exposes a bug in our program."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:519
|
||
msgid "Let's fix::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:538
|
||
msgid "And this is what it gives:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:553
|
||
msgid ""
|
||
"First output went well, and fixes the bug we had before. That is, we want "
|
||
"any value >= 2 to be as verbose as possible."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:556
|
||
msgid "Third output not so good."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:558
|
||
msgid "Let's fix that bug::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:575
|
||
msgid ""
|
||
"We've just introduced yet another keyword, ``default``. We've set it to "
|
||
"``0`` in order to make it comparable to the other int values. Remember that "
|
||
"by default, if an optional argument isn't specified, it gets the ``None`` "
|
||
"value, and that cannot be compared to an int value (hence the :exc:"
|
||
"`TypeError` exception)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:582
|
||
msgid "And:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:589
|
||
msgid ""
|
||
"You can go quite far just with what we've learned so far, and we have only "
|
||
"scratched the surface. The :mod:`argparse` module is very powerful, and "
|
||
"we'll explore a bit more of it before we end this tutorial."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:596
|
||
msgid "Getting a little more advanced"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:598
|
||
msgid ""
|
||
"What if we wanted to expand our tiny program to perform other powers, not "
|
||
"just squares::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:615 ../Doc/howto/argparse.rst:653
|
||
msgid "Output:"
|
||
msgstr "Sortie :"
|
||
|
||
#: ../Doc/howto/argparse.rst:636
|
||
msgid ""
|
||
"Notice that so far we've been using verbosity level to *change* the text "
|
||
"that gets displayed. The following example instead uses verbosity level to "
|
||
"display *more* text instead::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:667
|
||
msgid "Conflicting options"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:669
|
||
msgid ""
|
||
"So far, we have been working with two methods of an :class:`argparse."
|
||
"ArgumentParser` instance. Let's introduce a third one, :meth:"
|
||
"`add_mutually_exclusive_group`. It allows for us to specify options that "
|
||
"conflict with each other. Let's also change the rest of the program so that "
|
||
"the new functionality makes more sense: we'll introduce the ``--quiet`` "
|
||
"option, which will be the opposite of the ``--verbose`` one::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:695
|
||
msgid ""
|
||
"Our program is now simpler, and we've lost some functionality for the sake "
|
||
"of demonstration. Anyways, here's the output:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:713
|
||
msgid ""
|
||
"That should be easy to follow. I've added that last output so you can see "
|
||
"the sort of flexibility you get, i.e. mixing long form options with short "
|
||
"form ones."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:717
|
||
msgid ""
|
||
"Before we conclude, you probably want to tell your users the main purpose of "
|
||
"your program, just in case they don't know::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:738
|
||
msgid ""
|
||
"Note that slight difference in the usage text. Note the ``[-v | -q]``, which "
|
||
"tells us that we can either use ``-v`` or ``-q``, but not both at the same "
|
||
"time:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:760
|
||
msgid "Conclusion"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:762
|
||
msgid ""
|
||
"The :mod:`argparse` module offers a lot more than shown here. Its docs are "
|
||
"quite detailed and thorough, and full of examples. Having gone through this "
|
||
"tutorial, you should easily digest them without feeling overwhelmed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:3
|
||
msgid "Argument Clinic How-To"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:5
|
||
msgid "Larry Hastings"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:0 ../Doc/howto/cporting.rst:0
|
||
#: ../Doc/howto/curses.rst:0 ../Doc/howto/descriptor.rst:11
|
||
#: ../Doc/howto/pyporting.rst:0 ../Doc/howto/regex.rst:0
|
||
#: ../Doc/howto/sockets.rst:0
|
||
msgid "Abstract"
|
||
msgstr "Résumé"
|
||
|
||
#: ../Doc/howto/clinic.rst:10
|
||
msgid ""
|
||
"Argument Clinic is a preprocessor for CPython C files. Its purpose is to "
|
||
"automate all the boilerplate involved with writing argument parsing code for "
|
||
"\"builtins\". This document shows you how to convert your first C function "
|
||
"to work with Argument Clinic, and then introduces some advanced topics on "
|
||
"Argument Clinic usage."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:17
|
||
msgid ""
|
||
"Currently Argument Clinic is considered internal-only for CPython. Its use "
|
||
"is not supported for files outside CPython, and no guarantees are made "
|
||
"regarding backwards compatibility for future versions. In other words: if "
|
||
"you maintain an external C extension for CPython, you're welcome to "
|
||
"experiment with Argument Clinic in your own code. But the version of "
|
||
"Argument Clinic that ships with CPython 3.5 *could* be totally incompatible "
|
||
"and break all your code."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:27
|
||
msgid "The Goals Of Argument Clinic"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:29
|
||
msgid ""
|
||
"Argument Clinic's primary goal is to take over responsibility for all "
|
||
"argument parsing code inside CPython. This means that, when you convert a "
|
||
"function to work with Argument Clinic, that function should no longer do any "
|
||
"of its own argument parsing--the code generated by Argument Clinic should be "
|
||
"a \"black box\" to you, where CPython calls in at the top, and your code "
|
||
"gets called at the bottom, with ``PyObject *args`` (and maybe ``PyObject "
|
||
"*kwargs``) magically converted into the C variables and types you need."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:39
|
||
msgid ""
|
||
"In order for Argument Clinic to accomplish its primary goal, it must be easy "
|
||
"to use. Currently, working with CPython's argument parsing library is a "
|
||
"chore, requiring maintaining redundant information in a surprising number of "
|
||
"places. When you use Argument Clinic, you don't have to repeat yourself."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:45
|
||
msgid ""
|
||
"Obviously, no one would want to use Argument Clinic unless it's solving "
|
||
"their problem--and without creating new problems of its own. So it's "
|
||
"paramount that Argument Clinic generate correct code. It'd be nice if the "
|
||
"code was faster, too, but at the very least it should not introduce a major "
|
||
"speed regression. (Eventually Argument Clinic *should* make a major speedup "
|
||
"possible--we could rewrite its code generator to produce tailor-made "
|
||
"argument parsing code, rather than calling the general-purpose CPython "
|
||
"argument parsing library. That would make for the fastest argument parsing "
|
||
"possible!)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:57
|
||
msgid ""
|
||
"Additionally, Argument Clinic must be flexible enough to work with any "
|
||
"approach to argument parsing. Python has some functions with some very "
|
||
"strange parsing behaviors; Argument Clinic's goal is to support all of them."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:62
|
||
msgid ""
|
||
"Finally, the original motivation for Argument Clinic was to provide "
|
||
"introspection \"signatures\" for CPython builtins. It used to be, the "
|
||
"introspection query functions would throw an exception if you passed in a "
|
||
"builtin. With Argument Clinic, that's a thing of the past!"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:68
|
||
msgid ""
|
||
"One idea you should keep in mind, as you work with Argument Clinic: the more "
|
||
"information you give it, the better job it'll be able to do. Argument Clinic "
|
||
"is admittedly relatively simple right now. But as it evolves it will get "
|
||
"more sophisticated, and it should be able to do many interesting and smart "
|
||
"things with all the information you give it."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:78
|
||
msgid "Basic Concepts And Usage"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:80
|
||
msgid ""
|
||
"Argument Clinic ships with CPython; you'll find it in ``Tools/clinic/clinic."
|
||
"py``. If you run that script, specifying a C file as an argument::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:85
|
||
msgid ""
|
||
"Argument Clinic will scan over the file looking for lines that look exactly "
|
||
"like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:90
|
||
msgid ""
|
||
"When it finds one, it reads everything up to a line that looks exactly like "
|
||
"this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:95
|
||
msgid ""
|
||
"Everything in between these two lines is input for Argument Clinic. All of "
|
||
"these lines, including the beginning and ending comment lines, are "
|
||
"collectively called an Argument Clinic \"block\"."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:99
|
||
msgid ""
|
||
"When Argument Clinic parses one of these blocks, it generates output. This "
|
||
"output is rewritten into the C file immediately after the block, followed by "
|
||
"a comment containing a checksum. The Argument Clinic block now looks like "
|
||
"this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:110
|
||
msgid ""
|
||
"If you run Argument Clinic on the same file a second time, Argument Clinic "
|
||
"will discard the old output and write out the new output with a fresh "
|
||
"checksum line. However, if the input hasn't changed, the output won't "
|
||
"change either."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:114
|
||
msgid ""
|
||
"You should never modify the output portion of an Argument Clinic block. "
|
||
"Instead, change the input until it produces the output you want. (That's "
|
||
"the purpose of the checksum--to detect if someone changed the output, as "
|
||
"these edits would be lost the next time Argument Clinic writes out fresh "
|
||
"output.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:119
|
||
msgid ""
|
||
"For the sake of clarity, here's the terminology we'll use with Argument "
|
||
"Clinic:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:121
|
||
msgid ""
|
||
"The first line of the comment (``/*[clinic input]``) is the *start line*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:122
|
||
msgid ""
|
||
"The last line of the initial comment (``[clinic start generated code]*/``) "
|
||
"is the *end line*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:123
|
||
msgid ""
|
||
"The last line (``/*[clinic end generated code: checksum=...]*/``) is the "
|
||
"*checksum line*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:124
|
||
msgid "In between the start line and the end line is the *input*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:125
|
||
msgid "In between the end line and the checksum line is the *output*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:126
|
||
msgid ""
|
||
"All the text collectively, from the start line to the checksum line "
|
||
"inclusively, is the *block*. (A block that hasn't been successfully "
|
||
"processed by Argument Clinic yet doesn't have output or a checksum line, but "
|
||
"it's still considered a block.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:133
|
||
msgid "Converting Your First Function"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:135
|
||
msgid ""
|
||
"The best way to get a sense of how Argument Clinic works is to convert a "
|
||
"function to work with it. Here, then, are the bare minimum steps you'd need "
|
||
"to follow to convert a function to work with Argument Clinic. Note that for "
|
||
"code you plan to check in to CPython, you really should take the conversion "
|
||
"farther, using some of the advanced concepts you'll see later on in the "
|
||
"document (like \"return converters\" and \"self converters\"). But we'll "
|
||
"keep it simple for this walkthrough so you can learn."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:144
|
||
msgid "Let's dive in!"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:146
|
||
msgid ""
|
||
"Make sure you're working with a freshly updated checkout of the CPython "
|
||
"trunk."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:149
|
||
msgid ""
|
||
"Find a Python builtin that calls either :c:func:`PyArg_ParseTuple` or :c:"
|
||
"func:`PyArg_ParseTupleAndKeywords`, and hasn't been converted to work with "
|
||
"Argument Clinic yet. For my example I'm using ``_pickle.Pickler.dump()``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:154
|
||
msgid ""
|
||
"If the call to the ``PyArg_Parse`` function uses any of the following format "
|
||
"units:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:166
|
||
msgid ""
|
||
"or if it has multiple calls to :c:func:`PyArg_ParseTuple`, you should choose "
|
||
"a different function. Argument Clinic *does* support all of these "
|
||
"scenarios. But these are advanced topics--let's do something simpler for "
|
||
"your first function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:171
|
||
msgid ""
|
||
"Also, if the function has multiple calls to :c:func:`PyArg_ParseTuple` or :c:"
|
||
"func:`PyArg_ParseTupleAndKeywords` where it supports different types for the "
|
||
"same argument, or if the function uses something besides PyArg_Parse "
|
||
"functions to parse its arguments, it probably isn't suitable for conversion "
|
||
"to Argument Clinic. Argument Clinic doesn't support generic functions or "
|
||
"polymorphic parameters."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:178
|
||
msgid "Add the following boilerplate above the function, creating our block::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:183
|
||
msgid ""
|
||
"Cut the docstring and paste it in between the ``[clinic]`` lines, removing "
|
||
"all the junk that makes it a properly quoted C string. When you're done you "
|
||
"should have just the text, based at the left margin, with no line wider than "
|
||
"80 characters. (Argument Clinic will preserve indents inside the docstring.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:189
|
||
msgid ""
|
||
"If the old docstring had a first line that looked like a function signature, "
|
||
"throw that line away. (The docstring doesn't need it anymore--when you use "
|
||
"``help()`` on your builtin in the future, the first line will be built "
|
||
"automatically based on the function's signature.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:195 ../Doc/howto/clinic.rst:216
|
||
#: ../Doc/howto/clinic.rst:240 ../Doc/howto/clinic.rst:294
|
||
#: ../Doc/howto/clinic.rst:334 ../Doc/howto/clinic.rst:361
|
||
#: ../Doc/howto/clinic.rst:470 ../Doc/howto/clinic.rst:522
|
||
msgid "Sample::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:201
|
||
msgid ""
|
||
"If your docstring doesn't have a \"summary\" line, Argument Clinic will "
|
||
"complain. So let's make sure it has one. The \"summary\" line should be a "
|
||
"paragraph consisting of a single 80-column line at the beginning of the "
|
||
"docstring."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:206
|
||
msgid ""
|
||
"(Our example docstring consists solely of a summary line, so the sample code "
|
||
"doesn't have to change for this step.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:209
|
||
msgid ""
|
||
"Above the docstring, enter the name of the function, followed by a blank "
|
||
"line. This should be the Python name of the function, and should be the "
|
||
"full dotted path to the function--it should start with the name of the "
|
||
"module, include any sub-modules, and if the function is a method on a class "
|
||
"it should include the class name too."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:224
|
||
msgid ""
|
||
"If this is the first time that module or class has been used with Argument "
|
||
"Clinic in this C file, you must declare the module and/or class. Proper "
|
||
"Argument Clinic hygiene prefers declaring these in a separate block "
|
||
"somewhere near the top of the C file, in the same way that include files and "
|
||
"statics go at the top. (In our sample code we'll just show the two blocks "
|
||
"next to each other.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:232
|
||
msgid ""
|
||
"The name of the class and module should be the same as the one seen by "
|
||
"Python. Check the name defined in the :c:type:`PyModuleDef` or :c:type:"
|
||
"`PyTypeObject` as appropriate."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:236
|
||
msgid ""
|
||
"When you declare a class, you must also specify two aspects of its type in "
|
||
"C: the type declaration you'd use for a pointer to an instance of this "
|
||
"class, and a pointer to the :c:type:`PyTypeObject` for this class."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:256
|
||
msgid ""
|
||
"Declare each of the parameters to the function. Each parameter should get "
|
||
"its own line. All the parameter lines should be indented from the function "
|
||
"name and the docstring."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:260
|
||
msgid "The general form of these parameter lines is as follows::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:264
|
||
msgid "If the parameter has a default value, add that after the converter::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:269
|
||
msgid ""
|
||
"Argument Clinic's support for \"default values\" is quite sophisticated; "
|
||
"please see :ref:`the section below on default values <default_values>` for "
|
||
"more information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:273
|
||
msgid "Add a blank line below the parameters."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:275
|
||
msgid ""
|
||
"What's a \"converter\"? It establishes both the type of the variable used "
|
||
"in C, and the method to convert the Python value into a C value at runtime. "
|
||
"For now you're going to use what's called a \"legacy converter\"--a "
|
||
"convenience syntax intended to make porting old code into Argument Clinic "
|
||
"easier."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:282
|
||
msgid ""
|
||
"For each parameter, copy the \"format unit\" for that parameter from the "
|
||
"``PyArg_Parse()`` format argument and specify *that* as its converter, as a "
|
||
"quoted string. (\"format unit\" is the formal name for the one-to-three "
|
||
"character substring of the ``format`` parameter that tells the argument "
|
||
"parsing function what the type of the variable is and how to convert it. "
|
||
"For more on format units please see :ref:`arg-parsing`.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:291
|
||
msgid ""
|
||
"For multicharacter format units like ``z#``, use the entire two-or-three "
|
||
"character string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:309
|
||
msgid ""
|
||
"If your function has ``|`` in the format string, meaning some parameters "
|
||
"have default values, you can ignore it. Argument Clinic infers which "
|
||
"parameters are optional based on whether or not they have default values."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:314
|
||
msgid ""
|
||
"If your function has ``$`` in the format string, meaning it takes keyword-"
|
||
"only arguments, specify ``*`` on a line by itself before the first keyword-"
|
||
"only argument, indented the same as the parameter lines."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:319
|
||
msgid "(``_pickle.Pickler.dump`` has neither, so our sample is unchanged.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:322
|
||
msgid ""
|
||
"If the existing C function calls :c:func:`PyArg_ParseTuple` (as opposed to :"
|
||
"c:func:`PyArg_ParseTupleAndKeywords`), then all its arguments are positional-"
|
||
"only."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:326
|
||
msgid ""
|
||
"To mark all parameters as positional-only in Argument Clinic, add a ``/`` on "
|
||
"a line by itself after the last parameter, indented the same as the "
|
||
"parameter lines."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:330
|
||
msgid ""
|
||
"Currently this is all-or-nothing; either all parameters are positional-only, "
|
||
"or none of them are. (In the future Argument Clinic may relax this "
|
||
"restriction.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:350
|
||
msgid ""
|
||
"It's helpful to write a per-parameter docstring for each parameter. But per-"
|
||
"parameter docstrings are optional; you can skip this step if you prefer."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:354
|
||
msgid ""
|
||
"Here's how to add a per-parameter docstring. The first line of the per-"
|
||
"parameter docstring must be indented further than the parameter definition. "
|
||
"The left margin of this first line establishes the left margin for the whole "
|
||
"per-parameter docstring; all the text you write will be outdented by this "
|
||
"amount. You can write as much text as you like, across multiple lines if "
|
||
"you wish."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:378
|
||
msgid ""
|
||
"Save and close the file, then run ``Tools/clinic/clinic.py`` on it. With "
|
||
"luck everything worked and your block now has output! Reopen the file in "
|
||
"your text editor to see::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:406
|
||
msgid ""
|
||
"Obviously, if Argument Clinic didn't produce any output, it's because it "
|
||
"found an error in your input. Keep fixing your errors and retrying until "
|
||
"Argument Clinic processes your file without complaint."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:410
|
||
msgid ""
|
||
"Double-check that the argument-parsing code Argument Clinic generated looks "
|
||
"basically the same as the existing code."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:413
|
||
msgid ""
|
||
"First, ensure both places use the same argument-parsing function. The "
|
||
"existing code must call either :c:func:`PyArg_ParseTuple` or :c:func:"
|
||
"`PyArg_ParseTupleAndKeywords`; ensure that the code generated by Argument "
|
||
"Clinic calls the *exact* same function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:419
|
||
msgid ""
|
||
"Second, the format string passed in to :c:func:`PyArg_ParseTuple` or :c:func:"
|
||
"`PyArg_ParseTupleAndKeywords` should be *exactly* the same as the hand-"
|
||
"written one in the existing function, up to the colon or semi-colon."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:424
|
||
msgid ""
|
||
"(Argument Clinic always generates its format strings with a ``:`` followed "
|
||
"by the name of the function. If the existing code's format string ends with "
|
||
"``;``, to provide usage help, this change is harmless--don't worry about it.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:429
|
||
msgid ""
|
||
"Third, for parameters whose format units require two arguments (like a "
|
||
"length variable, or an encoding string, or a pointer to a conversion "
|
||
"function), ensure that the second argument is *exactly* the same between the "
|
||
"two invocations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:434
|
||
msgid ""
|
||
"Fourth, inside the output portion of the block you'll find a preprocessor "
|
||
"macro defining the appropriate static :c:type:`PyMethodDef` structure for "
|
||
"this builtin::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:441
|
||
msgid ""
|
||
"This static structure should be *exactly* the same as the existing static :c:"
|
||
"type:`PyMethodDef` structure for this builtin."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:444
|
||
msgid ""
|
||
"If any of these items differ in *any way*, adjust your Argument Clinic "
|
||
"function specification and rerun ``Tools/clinic/clinic.py`` until they *are* "
|
||
"the same."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:449
|
||
msgid ""
|
||
"Notice that the last line of its output is the declaration of your \"impl\" "
|
||
"function. This is where the builtin's implementation goes. Delete the "
|
||
"existing prototype of the function you're modifying, but leave the opening "
|
||
"curly brace. Now delete its argument parsing code and the declarations of "
|
||
"all the variables it dumps the arguments into. Notice how the Python "
|
||
"arguments are now arguments to this impl function; if the implementation "
|
||
"used different names for these variables, fix it."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:457
|
||
msgid ""
|
||
"Let's reiterate, just because it's kind of weird. Your code should now look "
|
||
"like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:466
|
||
msgid ""
|
||
"Argument Clinic generated the checksum line and the function prototype just "
|
||
"above it. You should write the opening (and closing) curly braces for the "
|
||
"function, and the implementation inside."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:511
|
||
msgid ""
|
||
"Remember the macro with the :c:type:`PyMethodDef` structure for this "
|
||
"function? Find the existing :c:type:`PyMethodDef` structure for this "
|
||
"function and replace it with a reference to the macro. (If the builtin is "
|
||
"at module scope, this will probably be very near the end of the file; if the "
|
||
"builtin is a class method, this will probably be below but relatively near "
|
||
"to the implementation.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:518
|
||
msgid ""
|
||
"Note that the body of the macro contains a trailing comma. So when you "
|
||
"replace the existing static :c:type:`PyMethodDef` structure with the macro, "
|
||
"*don't* add a comma to the end."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:531
|
||
msgid ""
|
||
"Compile, then run the relevant portions of the regression-test suite. This "
|
||
"change should not introduce any new compile-time warnings or errors, and "
|
||
"there should be no externally-visible change to Python's behavior."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:535
|
||
msgid ""
|
||
"Well, except for one difference: ``inspect.signature()`` run on your "
|
||
"function should now provide a valid signature!"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:538
|
||
msgid ""
|
||
"Congratulations, you've ported your first function to work with Argument "
|
||
"Clinic!"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:541
|
||
msgid "Advanced Topics"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:543
|
||
msgid ""
|
||
"Now that you've had some experience working with Argument Clinic, it's time "
|
||
"for some advanced topics."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:548
|
||
msgid "Symbolic default values"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:550
|
||
msgid ""
|
||
"The default value you provide for a parameter can't be any arbitrary "
|
||
"expression. Currently the following are explicitly supported:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:553
|
||
msgid "Numeric constants (integer and float)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:554
|
||
msgid "String constants"
|
||
msgstr "Chaînes constantes"
|
||
|
||
#: ../Doc/howto/clinic.rst:555
|
||
msgid "``True``, ``False``, and ``None``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:556
|
||
msgid ""
|
||
"Simple symbolic constants like ``sys.maxsize``, which must start with the "
|
||
"name of the module"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:559
|
||
msgid ""
|
||
"In case you're curious, this is implemented in ``from_builtin()`` in ``Lib/"
|
||
"inspect.py``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:562
|
||
msgid ""
|
||
"(In the future, this may need to get even more elaborate, to allow full "
|
||
"expressions like ``CONSTANT - 1``.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:567
|
||
msgid "Renaming the C functions and variables generated by Argument Clinic"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:569
|
||
msgid ""
|
||
"Argument Clinic automatically names the functions it generates for you. "
|
||
"Occasionally this may cause a problem, if the generated name collides with "
|
||
"the name of an existing C function. There's an easy solution: override the "
|
||
"names used for the C functions. Just add the keyword ``\"as\"`` to your "
|
||
"function declaration line, followed by the function name you wish to use. "
|
||
"Argument Clinic will use that function name for the base (generated) "
|
||
"function, then add ``\"_impl\"`` to the end and use that for the name of the "
|
||
"impl function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:577
|
||
msgid ""
|
||
"For example, if we wanted to rename the C function names generated for "
|
||
"``pickle.Pickler.dump``, it'd look like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:585
|
||
msgid ""
|
||
"The base function would now be named ``pickler_dumper()``, and the impl "
|
||
"function would now be named ``pickler_dumper_impl()``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:589
|
||
msgid ""
|
||
"Similarly, you may have a problem where you want to give a parameter a "
|
||
"specific Python name, but that name may be inconvenient in C. Argument "
|
||
"Clinic allows you to give a parameter different names in Python and in C, "
|
||
"using the same ``\"as\"`` syntax::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:603
|
||
msgid ""
|
||
"Here, the name used in Python (in the signature and the ``keywords`` array) "
|
||
"would be ``file``, but the C variable would be named ``file_obj``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:606
|
||
msgid "You can use this to rename the ``self`` parameter too!"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:610
|
||
msgid "Converting functions using PyArg_UnpackTuple"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:612
|
||
msgid ""
|
||
"To convert a function parsing its arguments with :c:func:"
|
||
"`PyArg_UnpackTuple`, simply write out all the arguments, specifying each as "
|
||
"an ``object``. You may specify the ``type`` argument to cast the type as "
|
||
"appropriate. All arguments should be marked positional-only (add a ``/`` on "
|
||
"a line by itself after the last argument)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:618
|
||
msgid ""
|
||
"Currently the generated code will use :c:func:`PyArg_ParseTuple`, but this "
|
||
"will change soon."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:622
|
||
msgid "Optional Groups"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:624
|
||
msgid ""
|
||
"Some legacy functions have a tricky approach to parsing their arguments: "
|
||
"they count the number of positional arguments, then use a ``switch`` "
|
||
"statement to call one of several different :c:func:`PyArg_ParseTuple` calls "
|
||
"depending on how many positional arguments there are. (These functions "
|
||
"cannot accept keyword-only arguments.) This approach was used to simulate "
|
||
"optional arguments back before :c:func:`PyArg_ParseTupleAndKeywords` was "
|
||
"created."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:631
|
||
msgid ""
|
||
"While functions using this approach can often be converted to use :c:func:"
|
||
"`PyArg_ParseTupleAndKeywords`, optional arguments, and default values, it's "
|
||
"not always possible. Some of these legacy functions have behaviors :c:func:"
|
||
"`PyArg_ParseTupleAndKeywords` doesn't directly support. The most obvious "
|
||
"example is the builtin function ``range()``, which has an optional argument "
|
||
"on the *left* side of its required argument! Another example is ``curses."
|
||
"window.addch()``, which has a group of two arguments that must always be "
|
||
"specified together. (The arguments are called ``x`` and ``y``; if you call "
|
||
"the function passing in ``x``, you must also pass in ``y``--and if you don't "
|
||
"pass in ``x`` you may not pass in ``y`` either.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:643
|
||
msgid ""
|
||
"In any case, the goal of Argument Clinic is to support argument parsing for "
|
||
"all existing CPython builtins without changing their semantics. Therefore "
|
||
"Argument Clinic supports this alternate approach to parsing, using what are "
|
||
"called *optional groups*. Optional groups are groups of arguments that must "
|
||
"all be passed in together. They can be to the left or the right of the "
|
||
"required arguments. They can *only* be used with positional-only parameters."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:651
|
||
msgid ""
|
||
"Optional groups are *only* intended for use when converting functions that "
|
||
"make multiple calls to :c:func:`PyArg_ParseTuple`! Functions that use *any* "
|
||
"other approach for parsing arguments should *almost never* be converted to "
|
||
"Argument Clinic using optional groups. Functions using optional groups "
|
||
"currently cannot have accurate signatures in Python, because Python just "
|
||
"doesn't understand the concept. Please avoid using optional groups wherever "
|
||
"possible."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:660
|
||
msgid ""
|
||
"To specify an optional group, add a ``[`` on a line by itself before the "
|
||
"parameters you wish to group together, and a ``]`` on a line by itself after "
|
||
"these parameters. As an example, here's how ``curses.window.addch`` uses "
|
||
"optional groups to make the first two parameters and the last parameter "
|
||
"optional::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:689
|
||
msgid "Notes:"
|
||
msgstr "Notes : "
|
||
|
||
#: ../Doc/howto/clinic.rst:691
|
||
msgid ""
|
||
"For every optional group, one additional parameter will be passed into the "
|
||
"impl function representing the group. The parameter will be an int named "
|
||
"``group_{direction}_{number}``, where ``{direction}`` is either ``right`` or "
|
||
"``left`` depending on whether the group is before or after the required "
|
||
"parameters, and ``{number}`` is a monotonically increasing number (starting "
|
||
"at 1) indicating how far away the group is from the required parameters. "
|
||
"When the impl is called, this parameter will be set to zero if this group "
|
||
"was unused, and set to non-zero if this group was used. (By used or unused, "
|
||
"I mean whether or not the parameters received arguments in this invocation.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:702
|
||
msgid ""
|
||
"If there are no required arguments, the optional groups will behave as if "
|
||
"they're to the right of the required arguments."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:705
|
||
msgid ""
|
||
"In the case of ambiguity, the argument parsing code favors parameters on the "
|
||
"left (before the required parameters)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:708
|
||
msgid "Optional groups can only contain positional-only parameters."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:710
|
||
msgid ""
|
||
"Optional groups are *only* intended for legacy code. Please do not use "
|
||
"optional groups for new code."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:715
|
||
msgid "Using real Argument Clinic converters, instead of \"legacy converters\""
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:717
|
||
msgid ""
|
||
"To save time, and to minimize how much you need to learn to achieve your "
|
||
"first port to Argument Clinic, the walkthrough above tells you to use "
|
||
"\"legacy converters\". \"Legacy converters\" are a convenience, designed "
|
||
"explicitly to make porting existing code to Argument Clinic easier. And to "
|
||
"be clear, their use is acceptable when porting code for Python 3.4."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:724
|
||
msgid ""
|
||
"However, in the long term we probably want all our blocks to use Argument "
|
||
"Clinic's real syntax for converters. Why? A couple reasons:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:728
|
||
msgid ""
|
||
"The proper converters are far easier to read and clearer in their intent."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:729
|
||
msgid ""
|
||
"There are some format units that are unsupported as \"legacy converters\", "
|
||
"because they require arguments, and the legacy converter syntax doesn't "
|
||
"support specifying arguments."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:732
|
||
msgid ""
|
||
"In the future we may have a new argument parsing library that isn't "
|
||
"restricted to what :c:func:`PyArg_ParseTuple` supports; this flexibility "
|
||
"won't be available to parameters using legacy converters."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:736
|
||
msgid ""
|
||
"Therefore, if you don't mind a little extra effort, please use the normal "
|
||
"converters instead of legacy converters."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:739
|
||
msgid ""
|
||
"In a nutshell, the syntax for Argument Clinic (non-legacy) converters looks "
|
||
"like a Python function call. However, if there are no explicit arguments to "
|
||
"the function (all functions take their default values), you may omit the "
|
||
"parentheses. Thus ``bool`` and ``bool()`` are exactly the same converters."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:745
|
||
msgid ""
|
||
"All arguments to Argument Clinic converters are keyword-only. All Argument "
|
||
"Clinic converters accept the following arguments:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:753 ../Doc/howto/clinic.rst:1223
|
||
msgid "``c_default``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:749
|
||
msgid ""
|
||
"The default value for this parameter when defined in C. Specifically, this "
|
||
"will be the initializer for the variable declared in the \"parse function"
|
||
"\". See :ref:`the section on default values <default_values>` for how to "
|
||
"use this. Specified as a string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:758
|
||
msgid "``annotation``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:756
|
||
msgid ""
|
||
"The annotation value for this parameter. Not currently supported, because "
|
||
"PEP 8 mandates that the Python library may not use annotations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:760
|
||
msgid ""
|
||
"In addition, some converters accept additional arguments. Here is a list of "
|
||
"these arguments, along with their meanings:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:769
|
||
msgid "``accept``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:764
|
||
msgid ""
|
||
"A set of Python types (and possibly pseudo-types); this restricts the "
|
||
"allowable Python argument to values of these types. (This is not a general-"
|
||
"purpose facility; as a rule it only supports specific lists of types as "
|
||
"shown in the legacy converter table.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:769
|
||
msgid "To accept ``None``, add ``NoneType`` to this set."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:774
|
||
msgid "``bitwise``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:772
|
||
msgid ""
|
||
"Only supported for unsigned integers. The native integer value of this "
|
||
"Python argument will be written to the parameter without any range checking, "
|
||
"even for negative values."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:779 ../Doc/howto/clinic.rst:1237
|
||
msgid "``converter``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:777
|
||
msgid ""
|
||
"Only supported by the ``object`` converter. Specifies the name of a :ref:`C "
|
||
"\"converter function\" <o_ampersand>` to use to convert this object to a "
|
||
"native type."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:784
|
||
msgid "``encoding``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:782
|
||
msgid ""
|
||
"Only supported for strings. Specifies the encoding to use when converting "
|
||
"this string from a Python str (Unicode) value into a C ``char *`` value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:788
|
||
msgid "``subclass_of``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:787
|
||
msgid ""
|
||
"Only supported for the ``object`` converter. Requires that the Python value "
|
||
"be a subclass of a Python type, as expressed in C."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:793 ../Doc/howto/clinic.rst:1209
|
||
msgid "``type``"
|
||
msgstr "``type``"
|
||
|
||
#: ../Doc/howto/clinic.rst:791
|
||
msgid ""
|
||
"Only supported for the ``object`` and ``self`` converters. Specifies the C "
|
||
"type that will be used to declare the variable. Default value is ``"
|
||
"\"PyObject *\"``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:799
|
||
msgid "``zeroes``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:796
|
||
msgid ""
|
||
"Only supported for strings. If true, embedded NUL bytes (``'\\\\0'``) are "
|
||
"permitted inside the value. The length of the string will be passed in to "
|
||
"the impl function, just after the string parameter, as a parameter named "
|
||
"``<parameter_name>_length``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:801
|
||
msgid ""
|
||
"Please note, not every possible combination of arguments will work. Usually "
|
||
"these arguments are implemented by specific ``PyArg_ParseTuple`` *format "
|
||
"units*, with specific behavior. For example, currently you cannot call "
|
||
"``unsigned_short`` without also specifying ``bitwise=True``. Although it's "
|
||
"perfectly reasonable to think this would work, these semantics don't map to "
|
||
"any existing format unit. So Argument Clinic doesn't support it. (Or, at "
|
||
"least, not yet.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:809
|
||
msgid ""
|
||
"Below is a table showing the mapping of legacy converters into real Argument "
|
||
"Clinic converters. On the left is the legacy converter, on the right is the "
|
||
"text you'd replace it with."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:814
|
||
msgid "``'B'``"
|
||
msgstr "``'B'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:814
|
||
msgid "``unsigned_char(bitwise=True)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:815
|
||
msgid "``'b'``"
|
||
msgstr "``'b'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:815
|
||
msgid "``unsigned_char``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:816
|
||
msgid "``'c'``"
|
||
msgstr "``'c'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:816
|
||
msgid "``char``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:817
|
||
msgid "``'C'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:817
|
||
msgid "``int(accept={str})``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:818
|
||
msgid "``'d'``"
|
||
msgstr "``'d'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:818
|
||
msgid "``double``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:819
|
||
msgid "``'D'``"
|
||
msgstr "``'D'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:819
|
||
msgid "``Py_complex``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:820
|
||
msgid "``'es'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:820
|
||
msgid "``str(encoding='name_of_encoding')``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:821
|
||
msgid "``'es#'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:821
|
||
msgid "``str(encoding='name_of_encoding', zeroes=True)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:822
|
||
msgid "``'et'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:822
|
||
msgid "``str(encoding='name_of_encoding', accept={bytes, bytearray, str})``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:823
|
||
msgid "``'et#'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:823
|
||
msgid ""
|
||
"``str(encoding='name_of_encoding', accept={bytes, bytearray, str}, "
|
||
"zeroes=True)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:824
|
||
msgid "``'f'``"
|
||
msgstr "``'f'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:824
|
||
msgid "``float``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:825
|
||
msgid "``'h'``"
|
||
msgstr "``'h'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:825
|
||
msgid "``short``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:826
|
||
msgid "``'H'``"
|
||
msgstr "``'H'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:826
|
||
msgid "``unsigned_short(bitwise=True)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:827
|
||
msgid "``'i'``"
|
||
msgstr "``'i'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:827
|
||
msgid "``int``"
|
||
msgstr "``int``"
|
||
|
||
#: ../Doc/howto/clinic.rst:828
|
||
msgid "``'I'``"
|
||
msgstr "``'I'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:828
|
||
msgid "``unsigned_int(bitwise=True)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:829
|
||
msgid "``'k'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:829
|
||
msgid "``unsigned_long(bitwise=True)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:830
|
||
msgid "``'K'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:830
|
||
msgid "``unsigned_long_long(bitwise=True)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:831
|
||
msgid "``'l'``"
|
||
msgstr "``'l'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:831
|
||
msgid "``long``"
|
||
msgstr "``long``"
|
||
|
||
#: ../Doc/howto/clinic.rst:832
|
||
msgid "``'L'``"
|
||
msgstr "``'L'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:832
|
||
msgid "``long long``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:833
|
||
msgid "``'n'``"
|
||
msgstr "``'n'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:833
|
||
msgid "``Py_ssize_t``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:834
|
||
msgid "``'O'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:834
|
||
msgid "``object``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:835
|
||
msgid "``'O!'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:835
|
||
msgid "``object(subclass_of='&PySomething_Type')``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:836
|
||
msgid "``'O&'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:836
|
||
msgid "``object(converter='name_of_c_function')``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:837
|
||
msgid "``'p'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:837
|
||
msgid "``bool``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:838
|
||
msgid "``'S'``"
|
||
msgstr "``'S'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:838
|
||
msgid "``PyBytesObject``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:839
|
||
msgid "``'s'``"
|
||
msgstr "``'s'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:839
|
||
msgid "``str``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:840
|
||
msgid "``'s#'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:840
|
||
msgid "``str(zeroes=True)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:841
|
||
msgid "``'s*'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:841
|
||
msgid "``Py_buffer(accept={buffer, str})``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:842
|
||
msgid "``'U'``"
|
||
msgstr "``'U'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:842
|
||
msgid "``unicode``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:843
|
||
msgid "``'u'``"
|
||
msgstr "``'u'``"
|
||
|
||
#: ../Doc/howto/clinic.rst:843
|
||
msgid "``Py_UNICODE``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:844
|
||
msgid "``'u#'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:844
|
||
msgid "``Py_UNICODE(zeroes=True)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:845
|
||
msgid "``'w*'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:845
|
||
msgid "``Py_buffer(accept={rwbuffer})``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:846
|
||
msgid "``'Y'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:846
|
||
msgid "``PyByteArrayObject``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:847
|
||
msgid "``'y'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:847
|
||
msgid "``str(accept={bytes})``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:848
|
||
msgid "``'y#'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:848
|
||
msgid "``str(accept={robuffer}, zeroes=True)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:849
|
||
msgid "``'y*'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:849
|
||
msgid "``Py_buffer``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:850
|
||
msgid "``'Z'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:850
|
||
msgid "``Py_UNICODE(accept={str, NoneType})``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:851
|
||
msgid "``'Z#'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:851
|
||
msgid "``Py_UNICODE(accept={str, NoneType}, zeroes=True)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:852
|
||
msgid "``'z'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:852
|
||
msgid "``str(accept={str, NoneType})``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:853
|
||
msgid "``'z#'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:853
|
||
msgid "``str(accept={str, NoneType}, zeroes=True)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:854
|
||
msgid "``'z*'``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:854
|
||
msgid "``Py_buffer(accept={buffer, str, NoneType})``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:857
|
||
msgid ""
|
||
"As an example, here's our sample ``pickle.Pickler.dump`` using the proper "
|
||
"converter::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:870
|
||
msgid ""
|
||
"Argument Clinic will show you all the converters it has available. For each "
|
||
"converter it'll show you all the parameters it accepts, along with the "
|
||
"default value for each parameter. Just run ``Tools/clinic/clinic.py --"
|
||
"converters`` to see the full list."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:876
|
||
msgid "Py_buffer"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:878
|
||
msgid ""
|
||
"When using the ``Py_buffer`` converter (or the ``'s*'``, ``'w*'``, ``'*y'``, "
|
||
"or ``'z*'`` legacy converters), you *must* not call :c:func:"
|
||
"`PyBuffer_Release` on the provided buffer. Argument Clinic generates code "
|
||
"that does it for you (in the parsing function)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:886
|
||
msgid "Advanced converters"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:888
|
||
msgid ""
|
||
"Remember those format units you skipped for your first time because they "
|
||
"were advanced? Here's how to handle those too."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:891
|
||
msgid ""
|
||
"The trick is, all those format units take arguments--either conversion "
|
||
"functions, or types, or strings specifying an encoding. (But \"legacy "
|
||
"converters\" don't support arguments. That's why we skipped them for your "
|
||
"first function.) The argument you specified to the format unit is now an "
|
||
"argument to the converter; this argument is either ``converter`` (for "
|
||
"``O&``), ``subclass_of`` (for ``O!``), or ``encoding`` (for all the format "
|
||
"units that start with ``e``)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:899
|
||
msgid ""
|
||
"When using ``subclass_of``, you may also want to use the other custom "
|
||
"argument for ``object()``: ``type``, which lets you set the type actually "
|
||
"used for the parameter. For example, if you want to ensure that the object "
|
||
"is a subclass of ``PyUnicode_Type``, you probably want to use the converter "
|
||
"``object(type='PyUnicodeObject *', subclass_of='&PyUnicode_Type')``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:905
|
||
msgid ""
|
||
"One possible problem with using Argument Clinic: it takes away some possible "
|
||
"flexibility for the format units starting with ``e``. When writing a "
|
||
"``PyArg_Parse`` call by hand, you could theoretically decide at runtime what "
|
||
"encoding string to pass in to :c:func:`PyArg_ParseTuple`. But now this "
|
||
"string must be hard-coded at Argument-Clinic-preprocessing-time. This "
|
||
"limitation is deliberate; it made supporting this format unit much easier, "
|
||
"and may allow for future optimizations. This restriction doesn't seem "
|
||
"unreasonable; CPython itself always passes in static hard-coded encoding "
|
||
"strings for parameters whose format units start with ``e``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:918
|
||
msgid "Parameter default values"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:920
|
||
msgid ""
|
||
"Default values for parameters can be any of a number of values. At their "
|
||
"simplest, they can be string, int, or float literals::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:927
|
||
msgid "They can also use any of Python's built-in constants::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:933
|
||
msgid ""
|
||
"There's also special support for a default value of ``NULL``, and for simple "
|
||
"expressions, documented in the following sections."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:938
|
||
msgid "The ``NULL`` default value"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:940
|
||
msgid ""
|
||
"For string and object parameters, you can set them to ``None`` to indicate "
|
||
"that there's no default. However, that means the C variable will be "
|
||
"initialized to ``Py_None``. For convenience's sakes, there's a special "
|
||
"value called ``NULL`` for just this reason: from Python's perspective it "
|
||
"behaves like a default value of ``None``, but the C variable is initialized "
|
||
"with ``NULL``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:948
|
||
msgid "Expressions specified as default values"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:950
|
||
msgid ""
|
||
"The default value for a parameter can be more than just a literal value. It "
|
||
"can be an entire expression, using math operators and looking up attributes "
|
||
"on objects. However, this support isn't exactly simple, because of some non-"
|
||
"obvious semantics."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:955
|
||
msgid "Consider the following example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:959
|
||
msgid ""
|
||
"``sys.maxsize`` can have different values on different platforms. Therefore "
|
||
"Argument Clinic can't simply evaluate that expression locally and hard-code "
|
||
"it in C. So it stores the default in such a way that it will get evaluated "
|
||
"at runtime, when the user asks for the function's signature."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:964
|
||
msgid ""
|
||
"What namespace is available when the expression is evaluated? It's "
|
||
"evaluated in the context of the module the builtin came from. So, if your "
|
||
"module has an attribute called \"``max_widgets``\", you may simply use it::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:970
|
||
msgid ""
|
||
"If the symbol isn't found in the current module, it fails over to looking in "
|
||
"``sys.modules``. That's how it can find ``sys.maxsize`` for example. "
|
||
"(Since you don't know in advance what modules the user will load into their "
|
||
"interpreter, it's best to restrict yourself to modules that are preloaded by "
|
||
"Python itself.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:975
|
||
msgid ""
|
||
"Evaluating default values only at runtime means Argument Clinic can't "
|
||
"compute the correct equivalent C default value. So you need to tell it "
|
||
"explicitly. When you use an expression, you must also specify the equivalent "
|
||
"expression in C, using the ``c_default`` parameter to the converter::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:982
|
||
msgid ""
|
||
"Another complication: Argument Clinic can't know in advance whether or not "
|
||
"the expression you supply is valid. It parses it to make sure it looks "
|
||
"legal, but it can't *actually* know. You must be very careful when using "
|
||
"expressions to specify values that are guaranteed to be valid at runtime!"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:987
|
||
msgid ""
|
||
"Finally, because expressions must be representable as static C values, there "
|
||
"are many restrictions on legal expressions. Here's a list of Python "
|
||
"features you're not permitted to use:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:991
|
||
msgid "Function calls."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:992
|
||
msgid "Inline if statements (``3 if foo else 5``)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:993
|
||
msgid "Automatic sequence unpacking (``*[1, 2, 3]``)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:994
|
||
msgid "List/set/dict comprehensions and generator expressions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:995
|
||
msgid "Tuple/list/set/dict literals."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1000
|
||
msgid "Using a return converter"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1002
|
||
msgid ""
|
||
"By default the impl function Argument Clinic generates for you returns "
|
||
"``PyObject *``. But your C function often computes some C type, then "
|
||
"converts it into the ``PyObject *`` at the last moment. Argument Clinic "
|
||
"handles converting your inputs from Python types into native C types--why "
|
||
"not have it convert your return value from a native C type into a Python "
|
||
"type too?"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1008
|
||
msgid ""
|
||
"That's what a \"return converter\" does. It changes your impl function to "
|
||
"return some C type, then adds code to the generated (non-impl) function to "
|
||
"handle converting that value into the appropriate ``PyObject *``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1012
|
||
msgid ""
|
||
"The syntax for return converters is similar to that of parameter converters. "
|
||
"You specify the return converter like it was a return annotation on the "
|
||
"function itself. Return converters behave much the same as parameter "
|
||
"converters; they take arguments, the arguments are all keyword-only, and if "
|
||
"you're not changing any of the default arguments you can omit the "
|
||
"parentheses."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1018
|
||
msgid ""
|
||
"(If you use both ``\"as\"`` *and* a return converter for your function, the "
|
||
"``\"as\"`` should come before the return converter.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1021
|
||
msgid ""
|
||
"There's one additional complication when using return converters: how do you "
|
||
"indicate an error has occurred? Normally, a function returns a valid (non-"
|
||
"``NULL``) pointer for success, and ``NULL`` for failure. But if you use an "
|
||
"integer return converter, all integers are valid. How can Argument Clinic "
|
||
"detect an error? Its solution: each return converter implicitly looks for a "
|
||
"special value that indicates an error. If you return that value, and an "
|
||
"error has been set (``PyErr_Occurred()`` returns a true value), then the "
|
||
"generated code will propagate the error. Otherwise it will encode the value "
|
||
"you return like normal."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1030
|
||
msgid "Currently Argument Clinic supports only a few return converters::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1043
|
||
msgid ""
|
||
"None of these take parameters. For the first three, return -1 to indicate "
|
||
"error. For ``DecodeFSDefault``, the return type is ``char *``; return a "
|
||
"NULL pointer to indicate an error."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1047
|
||
msgid ""
|
||
"(There's also an experimental ``NoneType`` converter, which lets you return "
|
||
"``Py_None`` on success or ``NULL`` on failure, without having to increment "
|
||
"the reference count on ``Py_None``. I'm not sure it adds enough clarity to "
|
||
"be worth using.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1052
|
||
msgid ""
|
||
"To see all the return converters Argument Clinic supports, along with their "
|
||
"parameters (if any), just run ``Tools/clinic/clinic.py --converters`` for "
|
||
"the full list."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1058
|
||
msgid "Cloning existing functions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1060
|
||
msgid ""
|
||
"If you have a number of functions that look similar, you may be able to use "
|
||
"Clinic's \"clone\" feature. When you clone an existing function, you reuse:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1064
|
||
msgid "its parameters, including"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1066
|
||
msgid "their names,"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1068
|
||
msgid "their converters, with all parameters,"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1070
|
||
msgid "their default values,"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1072
|
||
msgid "their per-parameter docstrings,"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1074
|
||
msgid ""
|
||
"their *kind* (whether they're positional only, positional or keyword, or "
|
||
"keyword only), and"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1077
|
||
msgid "its return converter."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1079
|
||
msgid ""
|
||
"The only thing not copied from the original function is its docstring; the "
|
||
"syntax allows you to specify a new docstring."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1082
|
||
msgid "Here's the syntax for cloning a function::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1090
|
||
msgid ""
|
||
"(The functions can be in different modules or classes. I wrote ``module."
|
||
"class`` in the sample just to illustrate that you must use the full path to "
|
||
"*both* functions.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1094
|
||
msgid ""
|
||
"Sorry, there's no syntax for partially-cloning a function, or cloning a "
|
||
"function then modifying it. Cloning is an all-or nothing proposition."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1097
|
||
msgid ""
|
||
"Also, the function you are cloning from must have been previously defined in "
|
||
"the current file."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1101
|
||
msgid "Calling Python code"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1103
|
||
msgid ""
|
||
"The rest of the advanced topics require you to write Python code which lives "
|
||
"inside your C file and modifies Argument Clinic's runtime state. This is "
|
||
"simple: you simply define a Python block."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1107
|
||
msgid ""
|
||
"A Python block uses different delimiter lines than an Argument Clinic "
|
||
"function block. It looks like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1114
|
||
msgid ""
|
||
"All the code inside the Python block is executed at the time it's parsed. "
|
||
"All text written to stdout inside the block is redirected into the \"output"
|
||
"\" after the block."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1118
|
||
msgid ""
|
||
"As an example, here's a Python block that adds a static integer variable to "
|
||
"the C code::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1129
|
||
msgid "Using a \"self converter\""
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1131
|
||
msgid ""
|
||
"Argument Clinic automatically adds a \"self\" parameter for you using a "
|
||
"default converter. It automatically sets the ``type`` of this parameter to "
|
||
"the \"pointer to an instance\" you specified when you declared the type. "
|
||
"However, you can override Argument Clinic's converter and specify one "
|
||
"yourself. Just add your own ``self`` parameter as the first parameter in a "
|
||
"block, and ensure that its converter is an instance of ``self_converter`` or "
|
||
"a subclass thereof."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1140
|
||
msgid ""
|
||
"What's the point? This lets you override the type of ``self``, or give it a "
|
||
"different default name."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1143
|
||
msgid ""
|
||
"How do you specify the custom type you want to cast ``self`` to? If you only "
|
||
"have one or two functions with the same type for ``self``, you can directly "
|
||
"use Argument Clinic's existing ``self`` converter, passing in the type you "
|
||
"want to use as the ``type`` parameter::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1159
|
||
msgid ""
|
||
"On the other hand, if you have a lot of functions that will use the same "
|
||
"type for ``self``, it's best to create your own converter, subclassing "
|
||
"``self_converter`` but overwriting the ``type`` member::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1182
|
||
msgid "Writing a custom converter"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1184
|
||
msgid ""
|
||
"As we hinted at in the previous section... you can write your own "
|
||
"converters! A converter is simply a Python class that inherits from "
|
||
"``CConverter``. The main purpose of a custom converter is if you have a "
|
||
"parameter using the ``O&`` format unit--parsing this parameter means calling "
|
||
"a :c:func:`PyArg_ParseTuple` \"converter function\"."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1190
|
||
msgid ""
|
||
"Your converter class should be named ``*something*_converter``. If the name "
|
||
"follows this convention, then your converter class will be automatically "
|
||
"registered with Argument Clinic; its name will be the name of your class "
|
||
"with the ``_converter`` suffix stripped off. (This is accomplished with a "
|
||
"metaclass.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1196
|
||
msgid ""
|
||
"You shouldn't subclass ``CConverter.__init__``. Instead, you should write a "
|
||
"``converter_init()`` function. ``converter_init()`` always accepts a "
|
||
"``self`` parameter; after that, all additional parameters *must* be keyword-"
|
||
"only. Any arguments passed in to the converter in Argument Clinic will be "
|
||
"passed along to your ``converter_init()``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1203
|
||
msgid ""
|
||
"There are some additional members of ``CConverter`` you may wish to specify "
|
||
"in your subclass. Here's the current list:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1207
|
||
msgid ""
|
||
"The C type to use for this variable. ``type`` should be a Python string "
|
||
"specifying the type, e.g. ``int``. If this is a pointer type, the type "
|
||
"string should end with ``' *'``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1213
|
||
msgid "``default``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1212
|
||
msgid ""
|
||
"The Python default value for this parameter, as a Python value. Or the magic "
|
||
"value ``unspecified`` if there is no default."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1218
|
||
msgid "``py_default``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1216
|
||
msgid ""
|
||
"``default`` as it should appear in Python code, as a string. Or ``None`` if "
|
||
"there is no default."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1221
|
||
msgid ""
|
||
"``default`` as it should appear in C code, as a string. Or ``None`` if there "
|
||
"is no default."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1234
|
||
msgid "``c_ignored_default``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1226
|
||
msgid ""
|
||
"The default value used to initialize the C variable when there is no "
|
||
"default, but not specifying a default may result in an \"uninitialized "
|
||
"variable\" warning. This can easily happen when using option groups--"
|
||
"although properly-written code will never actually use this value, the "
|
||
"variable does get passed in to the impl, and the C compiler will complain "
|
||
"about the \"use\" of the uninitialized value. This value should always be a "
|
||
"non-empty string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1237
|
||
msgid "The name of the C converter function, as a string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1242
|
||
msgid "``impl_by_reference``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1240
|
||
msgid ""
|
||
"A boolean value. If true, Argument Clinic will add a ``&`` in front of the "
|
||
"name of the variable when passing it into the impl function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1248
|
||
msgid "``parse_by_reference``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1245
|
||
msgid ""
|
||
"A boolean value. If true, Argument Clinic will add a ``&`` in front of the "
|
||
"name of the variable when passing it into :c:func:`PyArg_ParseTuple`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1250
|
||
msgid ""
|
||
"Here's the simplest example of a custom converter, from ``Modules/zlibmodule."
|
||
"c``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1261
|
||
msgid ""
|
||
"This block adds a converter to Argument Clinic named ``ssize_t``. "
|
||
"Parameters declared as ``ssize_t`` will be declared as type ``Py_ssize_t``, "
|
||
"and will be parsed by the ``'O&'`` format unit, which will call the "
|
||
"``ssize_t_converter`` converter function. ``ssize_t`` variables "
|
||
"automatically support default values."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1267
|
||
msgid ""
|
||
"More sophisticated custom converters can insert custom C code to handle "
|
||
"initialization and cleanup. You can see more examples of custom converters "
|
||
"in the CPython source tree; grep the C files for the string ``CConverter``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1273
|
||
msgid "Writing a custom return converter"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1275
|
||
msgid ""
|
||
"Writing a custom return converter is much like writing a custom converter. "
|
||
"Except it's somewhat simpler, because return converters are themselves much "
|
||
"simpler."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1279
|
||
msgid ""
|
||
"Return converters must subclass ``CReturnConverter``. There are no examples "
|
||
"yet of custom return converters, because they are not widely used yet. If "
|
||
"you wish to write your own return converter, please read ``Tools/clinic/"
|
||
"clinic.py``, specifically the implementation of ``CReturnConverter`` and all "
|
||
"its subclasses."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1287
|
||
msgid "METH_O and METH_NOARGS"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1289
|
||
msgid ""
|
||
"To convert a function using ``METH_O``, make sure the function's single "
|
||
"argument is using the ``object`` converter, and mark the arguments as "
|
||
"positional-only::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1301
|
||
msgid ""
|
||
"To convert a function using ``METH_NOARGS``, just don't specify any "
|
||
"arguments."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1304
|
||
msgid ""
|
||
"You can still use a self converter, a return converter, and specify a "
|
||
"``type`` argument to the object converter for ``METH_O``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1308
|
||
msgid "tp_new and tp_init functions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1310
|
||
msgid ""
|
||
"You can convert ``tp_new`` and ``tp_init`` functions. Just name them "
|
||
"``__new__`` or ``__init__`` as appropriate. Notes:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1313
|
||
msgid ""
|
||
"The function name generated for ``__new__`` doesn't end in ``__new__`` like "
|
||
"it would by default. It's just the name of the class, converted into a "
|
||
"valid C identifier."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1317
|
||
msgid "No ``PyMethodDef`` ``#define`` is generated for these functions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1319
|
||
msgid "``__init__`` functions return ``int``, not ``PyObject *``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1321
|
||
msgid "Use the docstring as the class docstring."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1323
|
||
msgid ""
|
||
"Although ``__new__`` and ``__init__`` functions must always accept both the "
|
||
"``args`` and ``kwargs`` objects, when converting you may specify any "
|
||
"signature for these functions that you like. (If your function doesn't "
|
||
"support keywords, the parsing function generated will throw an exception if "
|
||
"it receives any.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1330
|
||
msgid "Changing and redirecting Clinic's output"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1332
|
||
msgid ""
|
||
"It can be inconvenient to have Clinic's output interspersed with your "
|
||
"conventional hand-edited C code. Luckily, Clinic is configurable: you can "
|
||
"buffer up its output for printing later (or earlier!), or write its output "
|
||
"to a separate file. You can also add a prefix or suffix to every line of "
|
||
"Clinic's generated output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1338
|
||
msgid ""
|
||
"While changing Clinic's output in this manner can be a boon to readability, "
|
||
"it may result in Clinic code using types before they are defined, or your "
|
||
"code attempting to use Clinic-generated code before it is defined. These "
|
||
"problems can be easily solved by rearranging the declarations in your file, "
|
||
"or moving where Clinic's generated code goes. (This is why the default "
|
||
"behavior of Clinic is to output everything into the current block; while "
|
||
"many people consider this hampers readability, it will never require "
|
||
"rearranging your code to fix definition-before-use problems.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1347
|
||
msgid "Let's start with defining some terminology:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1372
|
||
msgid "*field*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1350
|
||
msgid ""
|
||
"A field, in this context, is a subsection of Clinic's output. For example, "
|
||
"the ``#define`` for the ``PyMethodDef`` structure is a field, called "
|
||
"``methoddef_define``. Clinic has seven different fields it can output per "
|
||
"function definition::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1363
|
||
msgid ""
|
||
"All the names are of the form ``\"<a>_<b>\"``, where ``\"<a>\"`` is the "
|
||
"semantic object represented (the parsing function, the impl function, the "
|
||
"docstring, or the methoddef structure) and ``\"<b>\"`` represents what kind "
|
||
"of statement the field is. Field names that end in ``\"_prototype\"`` "
|
||
"represent forward declarations of that thing, without the actual body/data "
|
||
"of the thing; field names that end in ``\"_definition\"`` represent the "
|
||
"actual definition of the thing, with the body/data of the thing. (``"
|
||
"\"methoddef\"`` is special, it's the only one that ends with ``\"_define"
|
||
"\"``, representing that it's a preprocessor #define.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1406
|
||
msgid "*destination*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1375
|
||
msgid ""
|
||
"A destination is a place Clinic can write output to. There are five built-"
|
||
"in destinations:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1380 ../Doc/howto/clinic.rst:1449
|
||
#: ../Doc/howto/clinic.rst:1523
|
||
msgid "``block``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1379
|
||
msgid ""
|
||
"The default destination: printed in the output section of the current Clinic "
|
||
"block."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1386 ../Doc/howto/clinic.rst:1476
|
||
#: ../Doc/howto/clinic.rst:1526
|
||
msgid "``buffer``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1383
|
||
msgid ""
|
||
"A text buffer where you can save text for later. Text sent here is appended "
|
||
"to the end of any existing text. It's an error to have any text left in the "
|
||
"buffer when Clinic finishes processing a file."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1397 ../Doc/howto/clinic.rst:1462
|
||
#: ../Doc/howto/clinic.rst:1552
|
||
msgid "``file``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1389
|
||
msgid ""
|
||
"A separate \"clinic file\" that will be created automatically by Clinic. The "
|
||
"filename chosen for the file is ``{basename}.clinic{extension}``, where "
|
||
"``basename`` and ``extension`` were assigned the output from ``os.path."
|
||
"splitext()`` run on the current file. (Example: the ``file`` destination "
|
||
"for ``_pickle.c`` would be written to ``_pickle.clinic.c``.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1396
|
||
msgid ""
|
||
"**Important: When using a** ``file`` **destination, you** *must check in* "
|
||
"**the generated file!**"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1402 ../Doc/howto/clinic.rst:1489
|
||
#: ../Doc/howto/clinic.rst:1556
|
||
msgid "``two-pass``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1400
|
||
msgid ""
|
||
"A buffer like ``buffer``. However, a two-pass buffer can only be written "
|
||
"once, and it prints out all text sent to it during all of processing, even "
|
||
"from Clinic blocks *after* the"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1406 ../Doc/howto/clinic.rst:1519
|
||
msgid "``suppress``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1405
|
||
msgid "The text is suppressed--thrown away."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1408
|
||
msgid "Clinic defines five new directives that let you reconfigure its output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1410
|
||
msgid "The first new directive is ``dump``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1414
|
||
msgid ""
|
||
"This dumps the current contents of the named destination into the output of "
|
||
"the current block, and empties it. This only works with ``buffer`` and "
|
||
"``two-pass`` destinations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1418
|
||
msgid ""
|
||
"The second new directive is ``output``. The most basic form of ``output`` "
|
||
"is like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1423
|
||
msgid ""
|
||
"This tells Clinic to output *field* to *destination*. ``output`` also "
|
||
"supports a special meta-destination, called ``everything``, which tells "
|
||
"Clinic to output *all* fields to that *destination*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1427
|
||
msgid "``output`` has a number of other functions::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1434
|
||
msgid ""
|
||
"``output push`` and ``output pop`` allow you to push and pop configurations "
|
||
"on an internal configuration stack, so that you can temporarily modify the "
|
||
"output configuration, then easily restore the previous configuration. "
|
||
"Simply push before your change to save the current configuration, then pop "
|
||
"when you wish to restore the previous configuration."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1441
|
||
msgid ""
|
||
"``output preset`` sets Clinic's output to one of several built-in preset "
|
||
"configurations, as follows:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1445
|
||
msgid ""
|
||
"Clinic's original starting configuration. Writes everything immediately "
|
||
"after the input block."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1448
|
||
msgid ""
|
||
"Suppress the ``parser_prototype`` and ``docstring_prototype``, write "
|
||
"everything else to ``block``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1452
|
||
msgid ""
|
||
"Designed to write everything to the \"clinic file\" that it can. You then "
|
||
"``#include`` this file near the top of your file. You may need to rearrange "
|
||
"your file to make this work, though usually this just means creating forward "
|
||
"declarations for various ``typedef`` and ``PyTypeObject`` definitions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1458
|
||
msgid ""
|
||
"Suppress the ``parser_prototype`` and ``docstring_prototype``, write the "
|
||
"``impl_definition`` to ``block``, and write everything else to ``file``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1462
|
||
msgid "The default filename is ``\"{dirname}/clinic/{basename}.h\"``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1465
|
||
msgid ""
|
||
"Save up all most of the output from Clinic, to be written into your file "
|
||
"near the end. For Python files implementing modules or builtin types, it's "
|
||
"recommended that you dump the buffer just above the static structures for "
|
||
"your module or builtin type; these are normally very near the end. Using "
|
||
"``buffer`` may require even more editing than ``file``, if your file has "
|
||
"static ``PyMethodDef`` arrays defined in the middle of the file."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1474
|
||
msgid ""
|
||
"Suppress the ``parser_prototype``, ``impl_prototype``, and "
|
||
"``docstring_prototype``, write the ``impl_definition`` to ``block``, and "
|
||
"write everything else to ``file``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1479
|
||
msgid ""
|
||
"Similar to the ``buffer`` preset, but writes forward declarations to the "
|
||
"``two-pass`` buffer, and definitions to the ``buffer``. This is similar to "
|
||
"the ``buffer`` preset, but may require less editing than ``buffer``. Dump "
|
||
"the ``two-pass`` buffer near the top of your file, and dump the ``buffer`` "
|
||
"near the end just like you would when using the ``buffer`` preset."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1486
|
||
msgid ""
|
||
"Suppresses the ``impl_prototype``, write the ``impl_definition`` to "
|
||
"``block``, write ``docstring_prototype``, ``methoddef_define``, and "
|
||
"``parser_prototype`` to ``two-pass``, write everything else to ``buffer``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1500
|
||
msgid "``partial-buffer``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1492
|
||
msgid ""
|
||
"Similar to the ``buffer`` preset, but writes more things to ``block``, only "
|
||
"writing the really big chunks of generated code to ``buffer``. This avoids "
|
||
"the definition-before-use problem of ``buffer`` completely, at the small "
|
||
"cost of having slightly more stuff in the block's output. Dump the "
|
||
"``buffer`` near the end, just like you would when using the ``buffer`` "
|
||
"preset."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1499
|
||
msgid ""
|
||
"Suppresses the ``impl_prototype``, write the ``docstring_definition`` and "
|
||
"``parser_definition`` to ``buffer``, write everything else to ``block``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1502
|
||
msgid "The third new directive is ``destination``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1506
|
||
msgid "This performs an operation on the destination named ``name``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1508
|
||
msgid "There are two defined subcommands: ``new`` and ``clear``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1510
|
||
msgid "The ``new`` subcommand works like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1514
|
||
msgid ""
|
||
"This creates a new destination with name ``<name>`` and type ``<type>``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1516
|
||
msgid "There are five destination types:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1519
|
||
msgid "Throws the text away."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1522
|
||
msgid ""
|
||
"Writes the text to the current block. This is what Clinic originally did."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1526
|
||
msgid "A simple text buffer, like the \"buffer\" builtin destination above."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1529
|
||
msgid ""
|
||
"A text file. The file destination takes an extra argument, a template to "
|
||
"use for building the filename, like so:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1532
|
||
msgid "destination <name> new <type> <file_template>"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1534
|
||
msgid ""
|
||
"The template can use three strings internally that will be replaced by bits "
|
||
"of the filename:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1537
|
||
msgid "{path}"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1538
|
||
msgid "The full path to the file, including directory and full filename."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1539
|
||
msgid "{dirname}"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1540
|
||
msgid "The name of the directory the file is in."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1541
|
||
msgid "{basename}"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1542
|
||
msgid "Just the name of the file, not including the directory."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1544
|
||
msgid "{basename_root}"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1544
|
||
msgid ""
|
||
"Basename with the extension clipped off (everything up to but not including "
|
||
"the last '.')."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1548
|
||
msgid "{basename_extension}"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1547
|
||
msgid ""
|
||
"The last '.' and everything after it. If the basename does not contain a "
|
||
"period, this will be the empty string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1550
|
||
msgid ""
|
||
"If there are no periods in the filename, {basename} and {filename} are the "
|
||
"same, and {extension} is empty. \"{basename}{extension}\" is always exactly "
|
||
"the same as \"{filename}\".\""
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1555
|
||
msgid "A two-pass buffer, like the \"two-pass\" builtin destination above."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1558
|
||
msgid "The ``clear`` subcommand works like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1562
|
||
msgid ""
|
||
"It removes all the accumulated text up to this point in the destination. (I "
|
||
"don't know what you'd need this for, but I thought maybe it'd be useful "
|
||
"while someone's experimenting.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1566
|
||
msgid "The fourth new directive is ``set``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1571
|
||
msgid ""
|
||
"``set`` lets you set two internal variables in Clinic. ``line_prefix`` is a "
|
||
"string that will be prepended to every line of Clinic's output; "
|
||
"``line_suffix`` is a string that will be appended to every line of Clinic's "
|
||
"output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1575
|
||
msgid "Both of these support two format strings:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1578
|
||
msgid "``{block comment start}``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1578
|
||
msgid ""
|
||
"Turns into the string ``/*``, the start-comment text sequence for C files."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1581
|
||
msgid "``{block comment end}``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1581
|
||
msgid ""
|
||
"Turns into the string ``*/``, the end-comment text sequence for C files."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1583
|
||
msgid ""
|
||
"The final new directive is one you shouldn't need to use directly, called "
|
||
"``preserve``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1588
|
||
msgid ""
|
||
"This tells Clinic that the current contents of the output should be kept, "
|
||
"unmodified. This is used internally by Clinic when dumping output into "
|
||
"``file`` files; wrapping it in a Clinic block lets Clinic use its existing "
|
||
"checksum functionality to ensure the file was not modified by hand before it "
|
||
"gets overwritten."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1595
|
||
msgid "The #ifdef trick"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1597
|
||
msgid ""
|
||
"If you're converting a function that isn't available on all platforms, "
|
||
"there's a trick you can use to make life a little easier. The existing code "
|
||
"probably looks like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1608
|
||
msgid ""
|
||
"And then in the ``PyMethodDef`` structure at the bottom the existing code "
|
||
"will have::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1615
|
||
msgid ""
|
||
"In this scenario, you should enclose the body of your impl function inside "
|
||
"the ``#ifdef``, like so::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1629
|
||
msgid ""
|
||
"Then, remove those three lines from the ``PyMethodDef`` structure, replacing "
|
||
"them with the macro Argument Clinic generated::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1634
|
||
msgid ""
|
||
"(You can find the real name for this macro inside the generated code. Or you "
|
||
"can calculate it yourself: it's the name of your function as defined on the "
|
||
"first line of your block, but with periods changed to underscores, "
|
||
"uppercased, and ``\"_METHODDEF\"`` added to the end.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1639
|
||
msgid ""
|
||
"Perhaps you're wondering: what if ``HAVE_FUNCTIONNAME`` isn't defined? The "
|
||
"``MODULE_FUNCTIONNAME_METHODDEF`` macro won't be defined either!"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1642
|
||
msgid ""
|
||
"Here's where Argument Clinic gets very clever. It actually detects that the "
|
||
"Argument Clinic block might be deactivated by the ``#ifdef``. When that "
|
||
"happens, it generates a little extra code that looks like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1650
|
||
msgid ""
|
||
"That means the macro always works. If the function is defined, this turns "
|
||
"into the correct structure, including the trailing comma. If the function "
|
||
"is undefined, this turns into nothing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1654
|
||
msgid ""
|
||
"However, this causes one ticklish problem: where should Argument Clinic put "
|
||
"this extra code when using the \"block\" output preset? It can't go in the "
|
||
"output block, because that could be deactivated by the ``#ifdef``. (That's "
|
||
"the whole point!)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1658
|
||
msgid ""
|
||
"In this situation, Argument Clinic writes the extra code to the \"buffer\" "
|
||
"destination. This may mean that you get a complaint from Argument Clinic::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1664
|
||
msgid ""
|
||
"When this happens, just open your file, find the ``dump buffer`` block that "
|
||
"Argument Clinic added to your file (it'll be at the very bottom), then move "
|
||
"it above the ``PyMethodDef`` structure where that macro is used."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1671
|
||
msgid "Using Argument Clinic in Python files"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1673
|
||
msgid ""
|
||
"It's actually possible to use Argument Clinic to preprocess Python files. "
|
||
"There's no point to using Argument Clinic blocks, of course, as the output "
|
||
"wouldn't make any sense to the Python interpreter. But using Argument "
|
||
"Clinic to run Python blocks lets you use Python as a Python preprocessor!"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/clinic.rst:1678
|
||
msgid ""
|
||
"Since Python comments are different from C comments, Argument Clinic blocks "
|
||
"embedded in Python files look slightly different. They look like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:7
|
||
msgid "Porting Extension Modules to Python 3"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:9
|
||
msgid "Benjamin Peterson"
|
||
msgstr "Benjamin Peterson"
|
||
|
||
#: ../Doc/howto/cporting.rst:14
|
||
msgid ""
|
||
"Although changing the C-API was not one of Python 3's objectives, the many "
|
||
"Python-level changes made leaving Python 2's API intact impossible. In "
|
||
"fact, some changes such as :func:`int` and :func:`long` unification are more "
|
||
"obvious on the C level. This document endeavors to document "
|
||
"incompatibilities and how they can be worked around."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:23
|
||
msgid "Conditional compilation"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:25
|
||
msgid ""
|
||
"The easiest way to compile only some code for Python 3 is to check if :c:"
|
||
"macro:`PY_MAJOR_VERSION` is greater than or equal to 3. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:32
|
||
msgid ""
|
||
"API functions that are not present can be aliased to their equivalents "
|
||
"within conditional blocks."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:37
|
||
msgid "Changes to Object APIs"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:39
|
||
msgid ""
|
||
"Python 3 merged together some types with similar functions while cleanly "
|
||
"separating others."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:44
|
||
msgid "str/unicode Unification"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:46
|
||
msgid ""
|
||
"Python 3's :func:`str` type is equivalent to Python 2's :func:`unicode`; the "
|
||
"C functions are called ``PyUnicode_*`` for both. The old 8-bit string type "
|
||
"has become :func:`bytes`, with C functions called ``PyBytes_*``. Python 2.6 "
|
||
"and later provide a compatibility header, :file:`bytesobject.h`, mapping "
|
||
"``PyBytes`` names to ``PyString`` ones. For best compatibility with Python "
|
||
"3, :c:type:`PyUnicode` should be used for textual data and :c:type:`PyBytes` "
|
||
"for binary data. It's also important to remember that :c:type:`PyBytes` "
|
||
"and :c:type:`PyUnicode` in Python 3 are not interchangeable like :c:type:"
|
||
"`PyString` and :c:type:`PyUnicode` are in Python 2. The following example "
|
||
"shows best practices with regards to :c:type:`PyUnicode`, :c:type:"
|
||
"`PyString`, and :c:type:`PyBytes`. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:95
|
||
msgid "long/int Unification"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:97
|
||
msgid ""
|
||
"Python 3 has only one integer type, :func:`int`. But it actually "
|
||
"corresponds to Python 2's :func:`long` type--the :func:`int` type used in "
|
||
"Python 2 was removed. In the C-API, ``PyInt_*`` functions are replaced by "
|
||
"their ``PyLong_*`` equivalents."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:104
|
||
msgid "Module initialization and state"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:106
|
||
msgid ""
|
||
"Python 3 has a revamped extension module initialization system. (See :pep:"
|
||
"`3121`.) Instead of storing module state in globals, they should be stored "
|
||
"in an interpreter specific structure. Creating modules that act correctly "
|
||
"in both Python 2 and Python 3 is tricky. The following simple example "
|
||
"demonstrates how. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:197
|
||
msgid "CObject replaced with Capsule"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:199
|
||
msgid ""
|
||
"The :c:type:`Capsule` object was introduced in Python 3.1 and 2.7 to "
|
||
"replace :c:type:`CObject`. CObjects were useful, but the :c:type:`CObject` "
|
||
"API was problematic: it didn't permit distinguishing between valid CObjects, "
|
||
"which allowed mismatched CObjects to crash the interpreter, and some of its "
|
||
"APIs relied on undefined behavior in C. (For further reading on the "
|
||
"rationale behind Capsules, please see :issue:`5630`.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:206
|
||
msgid ""
|
||
"If you're currently using CObjects, and you want to migrate to 3.1 or newer, "
|
||
"you'll need to switch to Capsules. :c:type:`CObject` was deprecated in 3.1 "
|
||
"and 2.7 and completely removed in Python 3.2. If you only support 2.7, or "
|
||
"3.1 and above, you can simply switch to :c:type:`Capsule`. If you need to "
|
||
"support Python 3.0, or versions of Python earlier than 2.7, you'll have to "
|
||
"support both CObjects and Capsules. (Note that Python 3.0 is no longer "
|
||
"supported, and it is not recommended for production use.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:216
|
||
msgid ""
|
||
"The following example header file :file:`capsulethunk.h` may solve the "
|
||
"problem for you. Simply write your code against the :c:type:`Capsule` API "
|
||
"and include this header file after :file:`Python.h`. Your code will "
|
||
"automatically use Capsules in versions of Python with Capsules, and switch "
|
||
"to CObjects when Capsules are unavailable."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:223
|
||
msgid ""
|
||
":file:`capsulethunk.h` simulates Capsules using CObjects. However, :c:type:"
|
||
"`CObject` provides no place to store the capsule's \"name\". As a result "
|
||
"the simulated :c:type:`Capsule` objects created by :file:`capsulethunk.h` "
|
||
"behave slightly differently from real Capsules. Specifically:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:228
|
||
msgid "The name parameter passed in to :c:func:`PyCapsule_New` is ignored."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:230
|
||
msgid ""
|
||
"The name parameter passed in to :c:func:`PyCapsule_IsValid` and :c:func:"
|
||
"`PyCapsule_GetPointer` is ignored, and no error checking of the name is "
|
||
"performed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:234
|
||
msgid ":c:func:`PyCapsule_GetName` always returns NULL."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:236
|
||
msgid ""
|
||
":c:func:`PyCapsule_SetName` always raises an exception and returns failure. "
|
||
"(Since there's no way to store a name in a CObject, noisy failure of :c:func:"
|
||
"`PyCapsule_SetName` was deemed preferable to silent failure here. If this "
|
||
"is inconvenient, feel free to modify your local copy as you see fit.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:243
|
||
msgid ""
|
||
"You can find :file:`capsulethunk.h` in the Python source distribution as :"
|
||
"source:`Doc/includes/capsulethunk.h`. We also include it here for your "
|
||
"convenience:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:252
|
||
msgid "Other options"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/cporting.rst:254
|
||
msgid ""
|
||
"If you are writing a new extension module, you might consider `Cython "
|
||
"<http://cython.org/>`_. It translates a Python-like language to C. The "
|
||
"extension modules it creates are compatible with Python 3 and Python 2."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:5
|
||
msgid "Curses Programming with Python"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:7
|
||
msgid "A.M. Kuchling, Eric S. Raymond"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:8
|
||
msgid "2.04"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:13
|
||
msgid ""
|
||
"This document describes how to use the :mod:`curses` extension module to "
|
||
"control text-mode displays."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:18
|
||
msgid "What is curses?"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:20
|
||
msgid ""
|
||
"The curses library supplies a terminal-independent screen-painting and "
|
||
"keyboard-handling facility for text-based terminals; such terminals include "
|
||
"VT100s, the Linux console, and the simulated terminal provided by various "
|
||
"programs. Display terminals support various control codes to perform common "
|
||
"operations such as moving the cursor, scrolling the screen, and erasing "
|
||
"areas. Different terminals use widely differing codes, and often have their "
|
||
"own minor quirks."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:28
|
||
msgid ""
|
||
"In a world of graphical displays, one might ask \"why bother\"? It's true "
|
||
"that character-cell display terminals are an obsolete technology, but there "
|
||
"are niches in which being able to do fancy things with them are still "
|
||
"valuable. One niche is on small-footprint or embedded Unixes that don't run "
|
||
"an X server. Another is tools such as OS installers and kernel "
|
||
"configurators that may have to run before any graphical support is available."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:36
|
||
msgid ""
|
||
"The curses library provides fairly basic functionality, providing the "
|
||
"programmer with an abstraction of a display containing multiple non-"
|
||
"overlapping windows of text. The contents of a window can be changed in "
|
||
"various ways---adding text, erasing it, changing its appearance---and the "
|
||
"curses library will figure out what control codes need to be sent to the "
|
||
"terminal to produce the right output. curses doesn't provide many user-"
|
||
"interface concepts such as buttons, checkboxes, or dialogs; if you need such "
|
||
"features, consider a user interface library such as `Urwid <https://pypi."
|
||
"python.org/pypi/urwid/>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:46
|
||
msgid ""
|
||
"The curses library was originally written for BSD Unix; the later System V "
|
||
"versions of Unix from AT&T added many enhancements and new functions. BSD "
|
||
"curses is no longer maintained, having been replaced by ncurses, which is an "
|
||
"open-source implementation of the AT&T interface. If you're using an open-"
|
||
"source Unix such as Linux or FreeBSD, your system almost certainly uses "
|
||
"ncurses. Since most current commercial Unix versions are based on System V "
|
||
"code, all the functions described here will probably be available. The "
|
||
"older versions of curses carried by some proprietary Unixes may not support "
|
||
"everything, though."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:56
|
||
msgid ""
|
||
"The Windows version of Python doesn't include the :mod:`curses` module. A "
|
||
"ported version called `UniCurses <https://pypi.python.org/pypi/UniCurses>`_ "
|
||
"is available. You could also try `the Console module <http://effbot.org/"
|
||
"zone/console-index.htm>`_ written by Fredrik Lundh, which doesn't use the "
|
||
"same API as curses but provides cursor-addressable text output and full "
|
||
"support for mouse and keyboard input."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:66
|
||
msgid "The Python curses module"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:68
|
||
msgid ""
|
||
"Thy Python module is a fairly simple wrapper over the C functions provided "
|
||
"by curses; if you're already familiar with curses programming in C, it's "
|
||
"really easy to transfer that knowledge to Python. The biggest difference is "
|
||
"that the Python interface makes things simpler by merging different C "
|
||
"functions such as :c:func:`addstr`, :c:func:`mvaddstr`, and :c:func:"
|
||
"`mvwaddstr` into a single :meth:`~curses.window.addstr` method. You'll see "
|
||
"this covered in more detail later."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:76
|
||
msgid ""
|
||
"This HOWTO is an introduction to writing text-mode programs with curses and "
|
||
"Python. It doesn't attempt to be a complete guide to the curses API; for "
|
||
"that, see the Python library guide's section on ncurses, and the C manual "
|
||
"pages for ncurses. It will, however, give you the basic ideas."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:83
|
||
msgid "Starting and ending a curses application"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:85
|
||
msgid ""
|
||
"Before doing anything, curses must be initialized. This is done by calling "
|
||
"the :func:`~curses.initscr` function, which will determine the terminal "
|
||
"type, send any required setup codes to the terminal, and create various "
|
||
"internal data structures. If successful, :func:`initscr` returns a window "
|
||
"object representing the entire screen; this is usually called ``stdscr`` "
|
||
"after the name of the corresponding C variable. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:96
|
||
msgid ""
|
||
"Usually curses applications turn off automatic echoing of keys to the "
|
||
"screen, in order to be able to read keys and only display them under certain "
|
||
"circumstances. This requires calling the :func:`~curses.noecho` function. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:103
|
||
msgid ""
|
||
"Applications will also commonly need to react to keys instantly, without "
|
||
"requiring the Enter key to be pressed; this is called cbreak mode, as "
|
||
"opposed to the usual buffered input mode. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:109
|
||
msgid ""
|
||
"Terminals usually return special keys, such as the cursor keys or navigation "
|
||
"keys such as Page Up and Home, as a multibyte escape sequence. While you "
|
||
"could write your application to expect such sequences and process them "
|
||
"accordingly, curses can do it for you, returning a special value such as :"
|
||
"const:`curses.KEY_LEFT`. To get curses to do the job, you'll have to enable "
|
||
"keypad mode. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:118
|
||
msgid ""
|
||
"Terminating a curses application is much easier than starting one. You'll "
|
||
"need to call::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:125
|
||
msgid ""
|
||
"to reverse the curses-friendly terminal settings. Then call the :func:"
|
||
"`~curses.endwin` function to restore the terminal to its original operating "
|
||
"mode. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:131
|
||
msgid ""
|
||
"A common problem when debugging a curses application is to get your terminal "
|
||
"messed up when the application dies without restoring the terminal to its "
|
||
"previous state. In Python this commonly happens when your code is buggy and "
|
||
"raises an uncaught exception. Keys are no longer echoed to the screen when "
|
||
"you type them, for example, which makes using the shell difficult."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:137
|
||
msgid ""
|
||
"In Python you can avoid these complications and make debugging much easier "
|
||
"by importing the :func:`curses.wrapper` function and using it like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:156
|
||
msgid ""
|
||
"The :func:`~curses.wrapper` function takes a callable object and does the "
|
||
"initializations described above, also initializing colors if color support "
|
||
"is present. :func:`wrapper` then runs your provided callable. Once the "
|
||
"callable returns, :func:`wrapper` will restore the original state of the "
|
||
"terminal. The callable is called inside a :keyword:`try`...\\ :keyword:"
|
||
"`except` that catches exceptions, restores the state of the terminal, and "
|
||
"then re-raises the exception. Therefore your terminal won't be left in a "
|
||
"funny state on exception and you'll be able to read the exception's message "
|
||
"and traceback."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:168
|
||
msgid "Windows and Pads"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:170
|
||
msgid ""
|
||
"Windows are the basic abstraction in curses. A window object represents a "
|
||
"rectangular area of the screen, and supports methods to display text, erase "
|
||
"it, allow the user to input strings, and so forth."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:174
|
||
msgid ""
|
||
"The ``stdscr`` object returned by the :func:`~curses.initscr` function is a "
|
||
"window object that covers the entire screen. Many programs may need only "
|
||
"this single window, but you might wish to divide the screen into smaller "
|
||
"windows, in order to redraw or clear them separately. The :func:`~curses."
|
||
"newwin` function creates a new window of a given size, returning the new "
|
||
"window object. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:185
|
||
msgid ""
|
||
"Note that the coordinate system used in curses is unusual. Coordinates are "
|
||
"always passed in the order *y,x*, and the top-left corner of a window is "
|
||
"coordinate (0,0). This breaks the normal convention for handling "
|
||
"coordinates where the *x* coordinate comes first. This is an unfortunate "
|
||
"difference from most other computer applications, but it's been part of "
|
||
"curses since it was first written, and it's too late to change things now."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:193
|
||
msgid ""
|
||
"Your application can determine the size of the screen by using the :data:"
|
||
"`curses.LINES` and :data:`curses.COLS` variables to obtain the *y* and *x* "
|
||
"sizes. Legal coordinates will then extend from ``(0,0)`` to ``(curses.LINES "
|
||
"- 1, curses.COLS - 1)``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:198
|
||
msgid ""
|
||
"When you call a method to display or erase text, the effect doesn't "
|
||
"immediately show up on the display. Instead you must call the :meth:"
|
||
"`~curses.window.refresh` method of window objects to update the screen."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:203
|
||
msgid ""
|
||
"This is because curses was originally written with slow 300-baud terminal "
|
||
"connections in mind; with these terminals, minimizing the time required to "
|
||
"redraw the screen was very important. Instead curses accumulates changes to "
|
||
"the screen and displays them in the most efficient manner when you call :"
|
||
"meth:`refresh`. For example, if your program displays some text in a window "
|
||
"and then clears the window, there's no need to send the original text "
|
||
"because they're never visible."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:212
|
||
msgid ""
|
||
"In practice, explicitly telling curses to redraw a window doesn't really "
|
||
"complicate programming with curses much. Most programs go into a flurry of "
|
||
"activity, and then pause waiting for a keypress or some other action on the "
|
||
"part of the user. All you have to do is to be sure that the screen has been "
|
||
"redrawn before pausing to wait for user input, by first calling ``stdscr."
|
||
"refresh()`` or the :meth:`refresh` method of some other relevant window."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:220
|
||
msgid ""
|
||
"A pad is a special case of a window; it can be larger than the actual "
|
||
"display screen, and only a portion of the pad displayed at a time. Creating "
|
||
"a pad requires the pad's height and width, while refreshing a pad requires "
|
||
"giving the coordinates of the on-screen area where a subsection of the pad "
|
||
"will be displayed. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:241
|
||
msgid ""
|
||
"The :meth:`refresh` call displays a section of the pad in the rectangle "
|
||
"extending from coordinate (5,5) to coordinate (20,75) on the screen; the "
|
||
"upper left corner of the displayed section is coordinate (0,0) on the pad. "
|
||
"Beyond that difference, pads are exactly like ordinary windows and support "
|
||
"the same methods."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:247
|
||
msgid ""
|
||
"If you have multiple windows and pads on screen there is a more efficient "
|
||
"way to update the screen and prevent annoying screen flicker as each part of "
|
||
"the screen gets updated. :meth:`refresh` actually does two things:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:252
|
||
msgid ""
|
||
"Calls the :meth:`~curses.window.noutrefresh` method of each window to update "
|
||
"an underlying data structure representing the desired state of the screen."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:255
|
||
msgid ""
|
||
"Calls the function :func:`~curses.doupdate` function to change the physical "
|
||
"screen to match the desired state recorded in the data structure."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:258
|
||
msgid ""
|
||
"Instead you can call :meth:`noutrefresh` on a number of windows to update "
|
||
"the data structure, and then call :func:`doupdate` to update the screen."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:264
|
||
msgid "Displaying Text"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:266
|
||
msgid ""
|
||
"From a C programmer's point of view, curses may sometimes look like a twisty "
|
||
"maze of functions, all subtly different. For example, :c:func:`addstr` "
|
||
"displays a string at the current cursor location in the ``stdscr`` window, "
|
||
"while :c:func:`mvaddstr` moves to a given y,x coordinate first before "
|
||
"displaying the string. :c:func:`waddstr` is just like :c:func:`addstr`, but "
|
||
"allows specifying a window to use instead of using ``stdscr`` by default. :c:"
|
||
"func:`mvwaddstr` allows specifying both a window and a coordinate."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:275
|
||
msgid ""
|
||
"Fortunately the Python interface hides all these details. ``stdscr`` is a "
|
||
"window object like any other, and methods such as :meth:`~curses.window."
|
||
"addstr` accept multiple argument forms. Usually there are four different "
|
||
"forms."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:281
|
||
msgid "Form"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:281 ../Doc/howto/curses.rst:350
|
||
msgid "Description"
|
||
msgstr "Description"
|
||
|
||
#: ../Doc/howto/curses.rst:283
|
||
msgid "*str* or *ch*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:283
|
||
msgid "Display the string *str* or character *ch* at the current position"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:286
|
||
msgid "*str* or *ch*, *attr*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:286
|
||
msgid ""
|
||
"Display the string *str* or character *ch*, using attribute *attr* at the "
|
||
"current position"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:290
|
||
msgid "*y*, *x*, *str* or *ch*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:290
|
||
msgid "Move to position *y,x* within the window, and display *str* or *ch*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:293
|
||
msgid "*y*, *x*, *str* or *ch*, *attr*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:293
|
||
msgid ""
|
||
"Move to position *y,x* within the window, and display *str* or *ch*, using "
|
||
"attribute *attr*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:297
|
||
msgid ""
|
||
"Attributes allow displaying text in highlighted forms such as boldface, "
|
||
"underline, reverse code, or in color. They'll be explained in more detail "
|
||
"in the next subsection."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:302
|
||
msgid ""
|
||
"The :meth:`~curses.window.addstr` method takes a Python string or bytestring "
|
||
"as the value to be displayed. The contents of bytestrings are sent to the "
|
||
"terminal as-is. Strings are encoded to bytes using the value of the "
|
||
"window's :attr:`encoding` attribute; this defaults to the default system "
|
||
"encoding as returned by :func:`locale.getpreferredencoding`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:309
|
||
msgid ""
|
||
"The :meth:`~curses.window.addch` methods take a character, which can be "
|
||
"either a string of length 1, a bytestring of length 1, or an integer."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:312
|
||
msgid ""
|
||
"Constants are provided for extension characters; these constants are "
|
||
"integers greater than 255. For example, :const:`ACS_PLMINUS` is a +/- "
|
||
"symbol, and :const:`ACS_ULCORNER` is the upper left corner of a box (handy "
|
||
"for drawing borders). You can also use the appropriate Unicode character."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:318
|
||
msgid ""
|
||
"Windows remember where the cursor was left after the last operation, so if "
|
||
"you leave out the *y,x* coordinates, the string or character will be "
|
||
"displayed wherever the last operation left off. You can also move the "
|
||
"cursor with the ``move(y,x)`` method. Because some terminals always display "
|
||
"a flashing cursor, you may want to ensure that the cursor is positioned in "
|
||
"some location where it won't be distracting; it can be confusing to have the "
|
||
"cursor blinking at some apparently random location."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:326
|
||
msgid ""
|
||
"If your application doesn't need a blinking cursor at all, you can call "
|
||
"``curs_set(False)`` to make it invisible. For compatibility with older "
|
||
"curses versions, there's a ``leaveok(bool)`` function that's a synonym for :"
|
||
"func:`~curses.curs_set`. When *bool* is true, the curses library will "
|
||
"attempt to suppress the flashing cursor, and you won't need to worry about "
|
||
"leaving it in odd locations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:335
|
||
msgid "Attributes and Color"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:337
|
||
msgid ""
|
||
"Characters can be displayed in different ways. Status lines in a text-based "
|
||
"application are commonly shown in reverse video, or a text viewer may need "
|
||
"to highlight certain words. curses supports this by allowing you to specify "
|
||
"an attribute for each cell on the screen."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:342
|
||
msgid ""
|
||
"An attribute is an integer, each bit representing a different attribute. "
|
||
"You can try to display text with multiple attribute bits set, but curses "
|
||
"doesn't guarantee that all the possible combinations are available, or that "
|
||
"they're all visually distinct. That depends on the ability of the terminal "
|
||
"being used, so it's safest to stick to the most commonly available "
|
||
"attributes, listed here."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:350
|
||
msgid "Attribute"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:352
|
||
msgid ":const:`A_BLINK`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:352
|
||
msgid "Blinking text"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:354
|
||
msgid ":const:`A_BOLD`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:354
|
||
msgid "Extra bright or bold text"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:356
|
||
msgid ":const:`A_DIM`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:356
|
||
msgid "Half bright text"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:358
|
||
msgid ":const:`A_REVERSE`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:358
|
||
msgid "Reverse-video text"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:360
|
||
msgid ":const:`A_STANDOUT`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:360
|
||
msgid "The best highlighting mode available"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:362
|
||
msgid ":const:`A_UNDERLINE`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:362
|
||
msgid "Underlined text"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:365
|
||
msgid ""
|
||
"So, to display a reverse-video status line on the top line of the screen, "
|
||
"you could code::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:372
|
||
msgid ""
|
||
"The curses library also supports color on those terminals that provide it. "
|
||
"The most common such terminal is probably the Linux console, followed by "
|
||
"color xterms."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:376
|
||
msgid ""
|
||
"To use color, you must call the :func:`~curses.start_color` function soon "
|
||
"after calling :func:`~curses.initscr`, to initialize the default color set "
|
||
"(the :func:`curses.wrapper` function does this automatically). Once that's "
|
||
"done, the :func:`~curses.has_colors` function returns TRUE if the terminal "
|
||
"in use can actually display color. (Note: curses uses the American spelling "
|
||
"'color', instead of the Canadian/British spelling 'colour'. If you're used "
|
||
"to the British spelling, you'll have to resign yourself to misspelling it "
|
||
"for the sake of these functions.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:386
|
||
msgid ""
|
||
"The curses library maintains a finite number of color pairs, containing a "
|
||
"foreground (or text) color and a background color. You can get the "
|
||
"attribute value corresponding to a color pair with the :func:`~curses."
|
||
"color_pair` function; this can be bitwise-OR'ed with other attributes such "
|
||
"as :const:`A_REVERSE`, but again, such combinations are not guaranteed to "
|
||
"work on all terminals."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:393
|
||
msgid "An example, which displays a line of text using color pair 1::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:398
|
||
msgid ""
|
||
"As I said before, a color pair consists of a foreground and background "
|
||
"color. The ``init_pair(n, f, b)`` function changes the definition of color "
|
||
"pair *n*, to foreground color f and background color b. Color pair 0 is "
|
||
"hard-wired to white on black, and cannot be changed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:403
|
||
msgid ""
|
||
"Colors are numbered, and :func:`start_color` initializes 8 basic colors when "
|
||
"it activates color mode. They are: 0:black, 1:red, 2:green, 3:yellow, 4:"
|
||
"blue, 5:magenta, 6:cyan, and 7:white. The :mod:`curses` module defines "
|
||
"named constants for each of these colors: :const:`curses.COLOR_BLACK`, :"
|
||
"const:`curses.COLOR_RED`, and so forth."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:409
|
||
msgid ""
|
||
"Let's put all this together. To change color 1 to red text on a white "
|
||
"background, you would call::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:414
|
||
msgid ""
|
||
"When you change a color pair, any text already displayed using that color "
|
||
"pair will change to the new colors. You can also display new text in this "
|
||
"color with::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:420
|
||
msgid ""
|
||
"Very fancy terminals can change the definitions of the actual colors to a "
|
||
"given RGB value. This lets you change color 1, which is usually red, to "
|
||
"purple or blue or any other color you like. Unfortunately, the Linux "
|
||
"console doesn't support this, so I'm unable to try it out, and can't provide "
|
||
"any examples. You can check if your terminal can do this by calling :func:"
|
||
"`~curses.can_change_color`, which returns ``True`` if the capability is "
|
||
"there. If you're lucky enough to have such a talented terminal, consult "
|
||
"your system's man pages for more information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:431
|
||
msgid "User Input"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:433
|
||
msgid ""
|
||
"The C curses library offers only very simple input mechanisms. Python's :mod:"
|
||
"`curses` module adds a basic text-input widget. (Other libraries such as "
|
||
"`Urwid <https://pypi.python.org/pypi/urwid/>`_ have more extensive "
|
||
"collections of widgets.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:438
|
||
msgid "There are two methods for getting input from a window:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:440
|
||
msgid ""
|
||
":meth:`~curses.window.getch` refreshes the screen and then waits for the "
|
||
"user to hit a key, displaying the key if :func:`~curses.echo` has been "
|
||
"called earlier. You can optionally specify a coordinate to which the cursor "
|
||
"should be moved before pausing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:445
|
||
msgid ""
|
||
":meth:`~curses.window.getkey` does the same thing but converts the integer "
|
||
"to a string. Individual characters are returned as 1-character strings, and "
|
||
"special keys such as function keys return longer strings containing a key "
|
||
"name such as ``KEY_UP`` or ``^G``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:450
|
||
msgid ""
|
||
"It's possible to not wait for the user using the :meth:`~curses.window."
|
||
"nodelay` window method. After ``nodelay(True)``, :meth:`getch` and :meth:"
|
||
"`getkey` for the window become non-blocking. To signal that no input is "
|
||
"ready, :meth:`getch` returns ``curses.ERR`` (a value of -1) and :meth:"
|
||
"`getkey` raises an exception. There's also a :func:`~curses.halfdelay` "
|
||
"function, which can be used to (in effect) set a timer on each :meth:"
|
||
"`getch`; if no input becomes available within a specified delay (measured in "
|
||
"tenths of a second), curses raises an exception."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:460
|
||
msgid ""
|
||
"The :meth:`getch` method returns an integer; if it's between 0 and 255, it "
|
||
"represents the ASCII code of the key pressed. Values greater than 255 are "
|
||
"special keys such as Page Up, Home, or the cursor keys. You can compare the "
|
||
"value returned to constants such as :const:`curses.KEY_PPAGE`, :const:"
|
||
"`curses.KEY_HOME`, or :const:`curses.KEY_LEFT`. The main loop of your "
|
||
"program may look something like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:476
|
||
msgid ""
|
||
"The :mod:`curses.ascii` module supplies ASCII class membership functions "
|
||
"that take either integer or 1-character string arguments; these may be "
|
||
"useful in writing more readable tests for such loops. It also supplies "
|
||
"conversion functions that take either integer or 1-character-string "
|
||
"arguments and return the same type. For example, :func:`curses.ascii.ctrl` "
|
||
"returns the control character corresponding to its argument."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:483
|
||
msgid ""
|
||
"There's also a method to retrieve an entire string, :meth:`~curses.window."
|
||
"getstr`. It isn't used very often, because its functionality is quite "
|
||
"limited; the only editing keys available are the backspace key and the Enter "
|
||
"key, which terminates the string. It can optionally be limited to a fixed "
|
||
"number of characters. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:494
|
||
msgid ""
|
||
"The :mod:`curses.textpad` module supplies a text box that supports an Emacs-"
|
||
"like set of keybindings. Various methods of the :class:`~curses.textpad."
|
||
"Textbox` class support editing with input validation and gathering the edit "
|
||
"results either with or without trailing spaces. Here's an example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:518
|
||
msgid ""
|
||
"See the library documentation on :mod:`curses.textpad` for more details."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:522
|
||
msgid "For More Information"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:524
|
||
msgid ""
|
||
"This HOWTO doesn't cover some advanced topics, such as reading the contents "
|
||
"of the screen or capturing mouse events from an xterm instance, but the "
|
||
"Python library page for the :mod:`curses` module is now reasonably "
|
||
"complete. You should browse it next."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:529
|
||
msgid ""
|
||
"If you're in doubt about the detailed behavior of the curses functions, "
|
||
"consult the manual pages for your curses implementation, whether it's "
|
||
"ncurses or a proprietary Unix vendor's. The manual pages will document any "
|
||
"quirks, and provide complete lists of all the functions, attributes, and :"
|
||
"const:`ACS_\\*` characters available to you."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:536
|
||
msgid ""
|
||
"Because the curses API is so large, some functions aren't supported in the "
|
||
"Python interface. Often this isn't because they're difficult to implement, "
|
||
"but because no one has needed them yet. Also, Python doesn't yet support "
|
||
"the menu library associated with ncurses. Patches adding support for these "
|
||
"would be welcome; see `the Python Developer's Guide <https://docs.python.org/"
|
||
"devguide/>`_ to learn more about submitting patches to Python."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:544
|
||
msgid ""
|
||
"`Writing Programs with NCURSES <http://invisible-island.net/ncurses/ncurses-"
|
||
"intro.html>`_: a lengthy tutorial for C programmers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:546
|
||
msgid "`The ncurses man page <http://linux.die.net/man/3/ncurses>`_"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:547
|
||
msgid ""
|
||
"`The ncurses FAQ <http://invisible-island.net/ncurses/ncurses.faq.html>`_"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:548
|
||
msgid ""
|
||
"`\"Use curses... don't swear\" <https://www.youtube.com/watch?"
|
||
"v=eN1eZtjLEnU>`_: video of a PyCon 2013 talk on controlling terminals using "
|
||
"curses or Urwid."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:550
|
||
msgid ""
|
||
"`\"Console Applications with Urwid\" <http://www.pyvideo.org/video/1568/"
|
||
"console-applications-with-urwid>`_: video of a PyCon CA 2012 talk "
|
||
"demonstrating some applications written using Urwid."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:3
|
||
msgid "Descriptor HowTo Guide"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:5
|
||
msgid "Raymond Hettinger"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:6
|
||
msgid "<python at rcn dot com>"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:0
|
||
msgid "Contents"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:13
|
||
msgid ""
|
||
"Defines descriptors, summarizes the protocol, and shows how descriptors are "
|
||
"called. Examines a custom descriptor and several built-in python "
|
||
"descriptors including functions, properties, static methods, and class "
|
||
"methods. Shows how each works by giving a pure Python equivalent and a "
|
||
"sample application."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:18
|
||
msgid ""
|
||
"Learning about descriptors not only provides access to a larger toolset, it "
|
||
"creates a deeper understanding of how Python works and an appreciation for "
|
||
"the elegance of its design."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:24
|
||
msgid "Definition and Introduction"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:26
|
||
msgid ""
|
||
"In general, a descriptor is an object attribute with \"binding behavior\", "
|
||
"one whose attribute access has been overridden by methods in the descriptor "
|
||
"protocol. Those methods are :meth:`__get__`, :meth:`__set__`, and :meth:"
|
||
"`__delete__`. If any of those methods are defined for an object, it is said "
|
||
"to be a descriptor."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:32
|
||
msgid ""
|
||
"The default behavior for attribute access is to get, set, or delete the "
|
||
"attribute from an object's dictionary. For instance, ``a.x`` has a lookup "
|
||
"chain starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and "
|
||
"continuing through the base classes of ``type(a)`` excluding metaclasses. If "
|
||
"the looked-up value is an object defining one of the descriptor methods, "
|
||
"then Python may override the default behavior and invoke the descriptor "
|
||
"method instead. Where this occurs in the precedence chain depends on which "
|
||
"descriptor methods were defined."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:41
|
||
msgid ""
|
||
"Descriptors are a powerful, general purpose protocol. They are the "
|
||
"mechanism behind properties, methods, static methods, class methods, and :"
|
||
"func:`super()`. They are used throughout Python itself to implement the new "
|
||
"style classes introduced in version 2.2. Descriptors simplify the "
|
||
"underlying C-code and offer a flexible set of new tools for everyday Python "
|
||
"programs."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:49
|
||
msgid "Descriptor Protocol"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:51
|
||
msgid "``descr.__get__(self, obj, type=None) --> value``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:53
|
||
msgid "``descr.__set__(self, obj, value) --> None``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:55
|
||
msgid "``descr.__delete__(self, obj) --> None``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:57
|
||
msgid ""
|
||
"That is all there is to it. Define any of these methods and an object is "
|
||
"considered a descriptor and can override default behavior upon being looked "
|
||
"up as an attribute."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:61
|
||
msgid ""
|
||
"If an object defines both :meth:`__get__` and :meth:`__set__`, it is "
|
||
"considered a data descriptor. Descriptors that only define :meth:`__get__` "
|
||
"are called non-data descriptors (they are typically used for methods but "
|
||
"other uses are possible)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:66
|
||
msgid ""
|
||
"Data and non-data descriptors differ in how overrides are calculated with "
|
||
"respect to entries in an instance's dictionary. If an instance's dictionary "
|
||
"has an entry with the same name as a data descriptor, the data descriptor "
|
||
"takes precedence. If an instance's dictionary has an entry with the same "
|
||
"name as a non-data descriptor, the dictionary entry takes precedence."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:72
|
||
msgid ""
|
||
"To make a read-only data descriptor, define both :meth:`__get__` and :meth:"
|
||
"`__set__` with the :meth:`__set__` raising an :exc:`AttributeError` when "
|
||
"called. Defining the :meth:`__set__` method with an exception raising "
|
||
"placeholder is enough to make it a data descriptor."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:79
|
||
msgid "Invoking Descriptors"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:81
|
||
msgid ""
|
||
"A descriptor can be called directly by its method name. For example, ``d."
|
||
"__get__(obj)``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:84
|
||
msgid ""
|
||
"Alternatively, it is more common for a descriptor to be invoked "
|
||
"automatically upon attribute access. For example, ``obj.d`` looks up ``d`` "
|
||
"in the dictionary of ``obj``. If ``d`` defines the method :meth:`__get__`, "
|
||
"then ``d.__get__(obj)`` is invoked according to the precedence rules listed "
|
||
"below."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:89
|
||
msgid ""
|
||
"The details of invocation depend on whether ``obj`` is an object or a class."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:91
|
||
msgid ""
|
||
"For objects, the machinery is in :meth:`object.__getattribute__` which "
|
||
"transforms ``b.x`` into ``type(b).__dict__['x'].__get__(b, type(b))``. The "
|
||
"implementation works through a precedence chain that gives data descriptors "
|
||
"priority over instance variables, instance variables priority over non-data "
|
||
"descriptors, and assigns lowest priority to :meth:`__getattr__` if provided. "
|
||
"The full C implementation can be found in :c:func:"
|
||
"`PyObject_GenericGetAttr()` in :source:`Objects/object.c`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:99
|
||
msgid ""
|
||
"For classes, the machinery is in :meth:`type.__getattribute__` which "
|
||
"transforms ``B.x`` into ``B.__dict__['x'].__get__(None, B)``. In pure "
|
||
"Python, it looks like::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:110
|
||
msgid "The important points to remember are:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:112
|
||
msgid "descriptors are invoked by the :meth:`__getattribute__` method"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:113
|
||
msgid "overriding :meth:`__getattribute__` prevents automatic descriptor calls"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:114
|
||
msgid ""
|
||
":meth:`object.__getattribute__` and :meth:`type.__getattribute__` make "
|
||
"different calls to :meth:`__get__`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:116
|
||
msgid "data descriptors always override instance dictionaries."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:117
|
||
msgid "non-data descriptors may be overridden by instance dictionaries."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:119
|
||
msgid ""
|
||
"The object returned by ``super()`` also has a custom :meth:"
|
||
"`__getattribute__` method for invoking descriptors. The call ``super(B, "
|
||
"obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A`` "
|
||
"immediately following ``B`` and then returns ``A.__dict__['m'].__get__(obj, "
|
||
"B)``. If not a descriptor, ``m`` is returned unchanged. If not in the "
|
||
"dictionary, ``m`` reverts to a search using :meth:`object.__getattribute__`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:126
|
||
msgid ""
|
||
"The implementation details are in :c:func:`super_getattro()` in :source:"
|
||
"`Objects/typeobject.c`. and a pure Python equivalent can be found in "
|
||
"`Guido's Tutorial`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:132
|
||
msgid ""
|
||
"The details above show that the mechanism for descriptors is embedded in "
|
||
"the :meth:`__getattribute__()` methods for :class:`object`, :class:`type`, "
|
||
"and :func:`super`. Classes inherit this machinery when they derive from :"
|
||
"class:`object` or if they have a meta-class providing similar functionality. "
|
||
"Likewise, classes can turn-off descriptor invocation by overriding :meth:"
|
||
"`__getattribute__()`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:141
|
||
msgid "Descriptor Example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:143
|
||
msgid ""
|
||
"The following code creates a class whose objects are data descriptors which "
|
||
"print a message for each get or set. Overriding :meth:`__getattribute__` is "
|
||
"alternate approach that could do this for every attribute. However, this "
|
||
"descriptor is useful for monitoring just a few chosen attributes::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:181
|
||
msgid ""
|
||
"The protocol is simple and offers exciting possibilities. Several use cases "
|
||
"are so common that they have been packaged into individual function calls. "
|
||
"Properties, bound and unbound methods, static methods, and class methods are "
|
||
"all based on the descriptor protocol."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:188
|
||
msgid "Properties"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:190
|
||
msgid ""
|
||
"Calling :func:`property` is a succinct way of building a data descriptor "
|
||
"that triggers function calls upon access to an attribute. Its signature is::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:195
|
||
msgid ""
|
||
"The documentation shows a typical use to define a managed attribute ``x``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:203
|
||
msgid ""
|
||
"To see how :func:`property` is implemented in terms of the descriptor "
|
||
"protocol, here is a pure Python equivalent::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:243
|
||
msgid ""
|
||
"The :func:`property` builtin helps whenever a user interface has granted "
|
||
"attribute access and then subsequent changes require the intervention of a "
|
||
"method."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:247
|
||
msgid ""
|
||
"For instance, a spreadsheet class may grant access to a cell value through "
|
||
"``Cell('b10').value``. Subsequent improvements to the program require the "
|
||
"cell to be recalculated on every access; however, the programmer does not "
|
||
"want to affect existing client code accessing the attribute directly. The "
|
||
"solution is to wrap access to the value attribute in a property data "
|
||
"descriptor::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:263
|
||
msgid "Functions and Methods"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:265
|
||
msgid ""
|
||
"Python's object oriented features are built upon a function based "
|
||
"environment. Using non-data descriptors, the two are merged seamlessly."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:268
|
||
msgid ""
|
||
"Class dictionaries store methods as functions. In a class definition, "
|
||
"methods are written using :keyword:`def` and :keyword:`lambda`, the usual "
|
||
"tools for creating functions. The only difference from regular functions is "
|
||
"that the first argument is reserved for the object instance. By Python "
|
||
"convention, the instance reference is called *self* but may be called *this* "
|
||
"or any other variable name."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:275
|
||
msgid ""
|
||
"To support method calls, functions include the :meth:`__get__` method for "
|
||
"binding methods during attribute access. This means that all functions are "
|
||
"non-data descriptors which return bound or unbound methods depending whether "
|
||
"they are invoked from an object or a class. In pure python, it works like "
|
||
"this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:287
|
||
msgid ""
|
||
"Running the interpreter shows how the function descriptor works in practice::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:301
|
||
msgid ""
|
||
"The output suggests that bound and unbound methods are two different types. "
|
||
"While they could have been implemented that way, the actual C implementation "
|
||
"of :c:type:`PyMethod_Type` in :source:`Objects/classobject.c` is a single "
|
||
"object with two different representations depending on whether the :attr:"
|
||
"`im_self` field is set or is *NULL* (the C equivalent of *None*)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:307
|
||
msgid ""
|
||
"Likewise, the effects of calling a method object depend on the :attr:"
|
||
"`im_self` field. If set (meaning bound), the original function (stored in "
|
||
"the :attr:`im_func` field) is called as expected with the first argument set "
|
||
"to the instance. If unbound, all of the arguments are passed unchanged to "
|
||
"the original function. The actual C implementation of :func:"
|
||
"`instancemethod_call()` is only slightly more complex in that it includes "
|
||
"some type checking."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:316
|
||
msgid "Static Methods and Class Methods"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:318
|
||
msgid ""
|
||
"Non-data descriptors provide a simple mechanism for variations on the usual "
|
||
"patterns of binding functions into methods."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:321
|
||
msgid ""
|
||
"To recap, functions have a :meth:`__get__` method so that they can be "
|
||
"converted to a method when accessed as attributes. The non-data descriptor "
|
||
"transforms an ``obj.f(*args)`` call into ``f(obj, *args)``. Calling ``klass."
|
||
"f(*args)`` becomes ``f(*args)``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:326
|
||
msgid "This chart summarizes the binding and its two most useful variants:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:329
|
||
msgid "Transformation"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:329
|
||
msgid "Called from an Object"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:329
|
||
msgid "Called from a Class"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:332
|
||
msgid "function"
|
||
msgstr "fonction"
|
||
|
||
#: ../Doc/howto/descriptor.rst:332
|
||
msgid "f(obj, \\*args)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:332 ../Doc/howto/descriptor.rst:334
|
||
msgid "f(\\*args)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:334
|
||
msgid "staticmethod"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:336
|
||
msgid "classmethod"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:336
|
||
msgid "f(type(obj), \\*args)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:336
|
||
msgid "f(klass, \\*args)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:339
|
||
msgid ""
|
||
"Static methods return the underlying function without changes. Calling "
|
||
"either ``c.f`` or ``C.f`` is the equivalent of a direct lookup into ``object."
|
||
"__getattribute__(c, \"f\")`` or ``object.__getattribute__(C, \"f\")``. As a "
|
||
"result, the function becomes identically accessible from either an object or "
|
||
"a class."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:345
|
||
msgid ""
|
||
"Good candidates for static methods are methods that do not reference the "
|
||
"``self`` variable."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:348
|
||
msgid ""
|
||
"For instance, a statistics package may include a container class for "
|
||
"experimental data. The class provides normal methods for computing the "
|
||
"average, mean, median, and other descriptive statistics that depend on the "
|
||
"data. However, there may be useful functions which are conceptually related "
|
||
"but do not depend on the data. For instance, ``erf(x)`` is handy conversion "
|
||
"routine that comes up in statistical work but does not directly depend on a "
|
||
"particular dataset. It can be called either from an object or the class: "
|
||
"``s.erf(1.5) --> .9332`` or ``Sample.erf(1.5) --> .9332``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:357
|
||
msgid ""
|
||
"Since staticmethods return the underlying function with no changes, the "
|
||
"example calls are unexciting::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:370
|
||
msgid ""
|
||
"Using the non-data descriptor protocol, a pure Python version of :func:"
|
||
"`staticmethod` would look like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:382
|
||
msgid ""
|
||
"Unlike static methods, class methods prepend the class reference to the "
|
||
"argument list before calling the function. This format is the same for "
|
||
"whether the caller is an object or a class::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:397
|
||
msgid ""
|
||
"This behavior is useful whenever the function only needs to have a class "
|
||
"reference and does not care about any underlying data. One use for "
|
||
"classmethods is to create alternate class constructors. In Python 2.3, the "
|
||
"classmethod :func:`dict.fromkeys` creates a new dictionary from a list of "
|
||
"keys. The pure Python equivalent is::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:413
|
||
msgid "Now a new dictionary of unique keys can be constructed like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:418
|
||
msgid ""
|
||
"Using the non-data descriptor protocol, a pure Python version of :func:"
|
||
"`classmethod` would look like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:3
|
||
msgid "Functional Programming HOWTO"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:5
|
||
msgid "A. M. Kuchling"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:6
|
||
msgid "0.32"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:8
|
||
msgid ""
|
||
"In this document, we'll take a tour of Python's features suitable for "
|
||
"implementing programs in a functional style. After an introduction to the "
|
||
"concepts of functional programming, we'll look at language features such as :"
|
||
"term:`iterator`\\s and :term:`generator`\\s and relevant library modules "
|
||
"such as :mod:`itertools` and :mod:`functools`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:16 ../Doc/howto/regex.rst:24
|
||
#: ../Doc/howto/urllib2.rst:18
|
||
msgid "Introduction"
|
||
msgstr "Introduction"
|
||
|
||
#: ../Doc/howto/functional.rst:18
|
||
msgid ""
|
||
"This section explains the basic concept of functional programming; if you're "
|
||
"just interested in learning about Python language features, skip to the next "
|
||
"section on :ref:`functional-howto-iterators`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:22
|
||
msgid ""
|
||
"Programming languages support decomposing problems in several different ways:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:24
|
||
msgid ""
|
||
"Most programming languages are **procedural**: programs are lists of "
|
||
"instructions that tell the computer what to do with the program's input. C, "
|
||
"Pascal, and even Unix shells are procedural languages."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:28
|
||
msgid ""
|
||
"In **declarative** languages, you write a specification that describes the "
|
||
"problem to be solved, and the language implementation figures out how to "
|
||
"perform the computation efficiently. SQL is the declarative language you're "
|
||
"most likely to be familiar with; a SQL query describes the data set you want "
|
||
"to retrieve, and the SQL engine decides whether to scan tables or use "
|
||
"indexes, which subclauses should be performed first, etc."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:35
|
||
msgid ""
|
||
"**Object-oriented** programs manipulate collections of objects. Objects "
|
||
"have internal state and support methods that query or modify this internal "
|
||
"state in some way. Smalltalk and Java are object-oriented languages. C++ "
|
||
"and Python are languages that support object-oriented programming, but don't "
|
||
"force the use of object-oriented features."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:41
|
||
msgid ""
|
||
"**Functional** programming decomposes a problem into a set of functions. "
|
||
"Ideally, functions only take inputs and produce outputs, and don't have any "
|
||
"internal state that affects the output produced for a given input. Well-"
|
||
"known functional languages include the ML family (Standard ML, OCaml, and "
|
||
"other variants) and Haskell."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:47
|
||
msgid ""
|
||
"The designers of some computer languages choose to emphasize one particular "
|
||
"approach to programming. This often makes it difficult to write programs "
|
||
"that use a different approach. Other languages are multi-paradigm languages "
|
||
"that support several different approaches. Lisp, C++, and Python are multi-"
|
||
"paradigm; you can write programs or libraries that are largely procedural, "
|
||
"object-oriented, or functional in all of these languages. In a large "
|
||
"program, different sections might be written using different approaches; the "
|
||
"GUI might be object-oriented while the processing logic is procedural or "
|
||
"functional, for example."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:58
|
||
msgid ""
|
||
"In a functional program, input flows through a set of functions. Each "
|
||
"function operates on its input and produces some output. Functional style "
|
||
"discourages functions with side effects that modify internal state or make "
|
||
"other changes that aren't visible in the function's return value. Functions "
|
||
"that have no side effects at all are called **purely functional**. Avoiding "
|
||
"side effects means not using data structures that get updated as a program "
|
||
"runs; every function's output must only depend on its input."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:66
|
||
msgid ""
|
||
"Some languages are very strict about purity and don't even have assignment "
|
||
"statements such as ``a=3`` or ``c = a + b``, but it's difficult to avoid all "
|
||
"side effects. Printing to the screen or writing to a disk file are side "
|
||
"effects, for example. For example, in Python a call to the :func:`print` "
|
||
"or :func:`time.sleep` function both return no useful value; they're only "
|
||
"called for their side effects of sending some text to the screen or pausing "
|
||
"execution for a second."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:74
|
||
msgid ""
|
||
"Python programs written in functional style usually won't go to the extreme "
|
||
"of avoiding all I/O or all assignments; instead, they'll provide a "
|
||
"functional-appearing interface but will use non-functional features "
|
||
"internally. For example, the implementation of a function will still use "
|
||
"assignments to local variables, but won't modify global variables or have "
|
||
"other side effects."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:80
|
||
msgid ""
|
||
"Functional programming can be considered the opposite of object-oriented "
|
||
"programming. Objects are little capsules containing some internal state "
|
||
"along with a collection of method calls that let you modify this state, and "
|
||
"programs consist of making the right set of state changes. Functional "
|
||
"programming wants to avoid state changes as much as possible and works with "
|
||
"data flowing between functions. In Python you might combine the two "
|
||
"approaches by writing functions that take and return instances representing "
|
||
"objects in your application (e-mail messages, transactions, etc.)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:89
|
||
msgid ""
|
||
"Functional design may seem like an odd constraint to work under. Why should "
|
||
"you avoid objects and side effects? There are theoretical and practical "
|
||
"advantages to the functional style:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:93
|
||
msgid "Formal provability."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:94
|
||
msgid "Modularity."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:95
|
||
msgid "Composability."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:96
|
||
msgid "Ease of debugging and testing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:100
|
||
msgid "Formal provability"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:102
|
||
msgid ""
|
||
"A theoretical benefit is that it's easier to construct a mathematical proof "
|
||
"that a functional program is correct."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:105
|
||
msgid ""
|
||
"For a long time researchers have been interested in finding ways to "
|
||
"mathematically prove programs correct. This is different from testing a "
|
||
"program on numerous inputs and concluding that its output is usually "
|
||
"correct, or reading a program's source code and concluding that the code "
|
||
"looks right; the goal is instead a rigorous proof that a program produces "
|
||
"the right result for all possible inputs."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:112
|
||
msgid ""
|
||
"The technique used to prove programs correct is to write down "
|
||
"**invariants**, properties of the input data and of the program's variables "
|
||
"that are always true. For each line of code, you then show that if "
|
||
"invariants X and Y are true **before** the line is executed, the slightly "
|
||
"different invariants X' and Y' are true **after** the line is executed. "
|
||
"This continues until you reach the end of the program, at which point the "
|
||
"invariants should match the desired conditions on the program's output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:120
|
||
msgid ""
|
||
"Functional programming's avoidance of assignments arose because assignments "
|
||
"are difficult to handle with this technique; assignments can break "
|
||
"invariants that were true before the assignment without producing any new "
|
||
"invariants that can be propagated onward."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:125
|
||
msgid ""
|
||
"Unfortunately, proving programs correct is largely impractical and not "
|
||
"relevant to Python software. Even trivial programs require proofs that are "
|
||
"several pages long; the proof of correctness for a moderately complicated "
|
||
"program would be enormous, and few or none of the programs you use daily "
|
||
"(the Python interpreter, your XML parser, your web browser) could be proven "
|
||
"correct. Even if you wrote down or generated a proof, there would then be "
|
||
"the question of verifying the proof; maybe there's an error in it, and you "
|
||
"wrongly believe you've proved the program correct."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:136
|
||
msgid "Modularity"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:138
|
||
msgid ""
|
||
"A more practical benefit of functional programming is that it forces you to "
|
||
"break apart your problem into small pieces. Programs are more modular as a "
|
||
"result. It's easier to specify and write a small function that does one "
|
||
"thing than a large function that performs a complicated transformation. "
|
||
"Small functions are also easier to read and to check for errors."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:146
|
||
msgid "Ease of debugging and testing"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:148
|
||
msgid "Testing and debugging a functional-style program is easier."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:150
|
||
msgid ""
|
||
"Debugging is simplified because functions are generally small and clearly "
|
||
"specified. When a program doesn't work, each function is an interface point "
|
||
"where you can check that the data are correct. You can look at the "
|
||
"intermediate inputs and outputs to quickly isolate the function that's "
|
||
"responsible for a bug."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:155
|
||
msgid ""
|
||
"Testing is easier because each function is a potential subject for a unit "
|
||
"test. Functions don't depend on system state that needs to be replicated "
|
||
"before running a test; instead you only have to synthesize the right input "
|
||
"and then check that the output matches expectations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:162
|
||
msgid "Composability"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:164
|
||
msgid ""
|
||
"As you work on a functional-style program, you'll write a number of "
|
||
"functions with varying inputs and outputs. Some of these functions will be "
|
||
"unavoidably specialized to a particular application, but others will be "
|
||
"useful in a wide variety of programs. For example, a function that takes a "
|
||
"directory path and returns all the XML files in the directory, or a function "
|
||
"that takes a filename and returns its contents, can be applied to many "
|
||
"different situations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:171
|
||
msgid ""
|
||
"Over time you'll form a personal library of utilities. Often you'll "
|
||
"assemble new programs by arranging existing functions in a new configuration "
|
||
"and writing a few functions specialized for the current task."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:179
|
||
msgid "Iterators"
|
||
msgstr "Itérateurs"
|
||
|
||
#: ../Doc/howto/functional.rst:181
|
||
msgid ""
|
||
"I'll start by looking at a Python language feature that's an important "
|
||
"foundation for writing functional-style programs: iterators."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:184
|
||
msgid ""
|
||
"An iterator is an object representing a stream of data; this object returns "
|
||
"the data one element at a time. A Python iterator must support a method "
|
||
"called :meth:`~iterator.__next__` that takes no arguments and always returns "
|
||
"the next element of the stream. If there are no more elements in the "
|
||
"stream, :meth:`~iterator.__next__` must raise the :exc:`StopIteration` "
|
||
"exception. Iterators don't have to be finite, though; it's perfectly "
|
||
"reasonable to write an iterator that produces an infinite stream of data."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:192
|
||
msgid ""
|
||
"The built-in :func:`iter` function takes an arbitrary object and tries to "
|
||
"return an iterator that will return the object's contents or elements, "
|
||
"raising :exc:`TypeError` if the object doesn't support iteration. Several "
|
||
"of Python's built-in data types support iteration, the most common being "
|
||
"lists and dictionaries. An object is called :term:`iterable` if you can get "
|
||
"an iterator for it."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:199
|
||
msgid "You can experiment with the iteration interface manually:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:217
|
||
msgid ""
|
||
"Python expects iterable objects in several different contexts, the most "
|
||
"important being the :keyword:`for` statement. In the statement ``for X in "
|
||
"Y``, Y must be an iterator or some object for which :func:`iter` can create "
|
||
"an iterator. These two statements are equivalent::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:229
|
||
msgid ""
|
||
"Iterators can be materialized as lists or tuples by using the :func:`list` "
|
||
"or :func:`tuple` constructor functions:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:238
|
||
msgid ""
|
||
"Sequence unpacking also supports iterators: if you know an iterator will "
|
||
"return N elements, you can unpack them into an N-tuple:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:247
|
||
msgid ""
|
||
"Built-in functions such as :func:`max` and :func:`min` can take a single "
|
||
"iterator argument and will return the largest or smallest element. The ``"
|
||
"\"in\"`` and ``\"not in\"`` operators also support iterators: ``X in "
|
||
"iterator`` is true if X is found in the stream returned by the iterator. "
|
||
"You'll run into obvious problems if the iterator is infinite; :func:`max`, :"
|
||
"func:`min` will never return, and if the element X never appears in the "
|
||
"stream, the ``\"in\"`` and ``\"not in\"`` operators won't return either."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:255
|
||
msgid ""
|
||
"Note that you can only go forward in an iterator; there's no way to get the "
|
||
"previous element, reset the iterator, or make a copy of it. Iterator "
|
||
"objects can optionally provide these additional capabilities, but the "
|
||
"iterator protocol only specifies the :meth:`~iterator.__next__` method. "
|
||
"Functions may therefore consume all of the iterator's output, and if you "
|
||
"need to do something different with the same stream, you'll have to create a "
|
||
"new iterator."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:265
|
||
msgid "Data Types That Support Iterators"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:267
|
||
msgid ""
|
||
"We've already seen how lists and tuples support iterators. In fact, any "
|
||
"Python sequence type, such as strings, will automatically support creation "
|
||
"of an iterator."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:271
|
||
msgid ""
|
||
"Calling :func:`iter` on a dictionary returns an iterator that will loop over "
|
||
"the dictionary's keys::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:291
|
||
msgid ""
|
||
"Note that the order is essentially random, because it's based on the hash "
|
||
"ordering of the objects in the dictionary."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:294
|
||
msgid ""
|
||
"Applying :func:`iter` to a dictionary always loops over the keys, but "
|
||
"dictionaries have methods that return other iterators. If you want to "
|
||
"iterate over values or key/value pairs, you can explicitly call the :meth:"
|
||
"`~dict.values` or :meth:`~dict.items` methods to get an appropriate iterator."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:300
|
||
msgid ""
|
||
"The :func:`dict` constructor can accept an iterator that returns a finite "
|
||
"stream of ``(key, value)`` tuples:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:307
|
||
msgid ""
|
||
"Files also support iteration by calling the :meth:`~io.TextIOBase.readline` "
|
||
"method until there are no more lines in the file. This means you can read "
|
||
"each line of a file like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:315
|
||
msgid ""
|
||
"Sets can take their contents from an iterable and let you iterate over the "
|
||
"set's elements::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:325
|
||
msgid "Generator expressions and list comprehensions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:327
|
||
msgid ""
|
||
"Two common operations on an iterator's output are 1) performing some "
|
||
"operation for every element, 2) selecting a subset of elements that meet "
|
||
"some condition. For example, given a list of strings, you might want to "
|
||
"strip off trailing whitespace from each line or extract all the strings "
|
||
"containing a given substring."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:333
|
||
msgid ""
|
||
"List comprehensions and generator expressions (short form: \"listcomps\" and "
|
||
"\"genexps\") are a concise notation for such operations, borrowed from the "
|
||
"functional programming language Haskell (https://www.haskell.org/). You can "
|
||
"strip all the whitespace from a stream of strings with the following code::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:346
|
||
msgid ""
|
||
"You can select only certain elements by adding an ``\"if\"`` condition::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:351
|
||
msgid ""
|
||
"With a list comprehension, you get back a Python list; ``stripped_list`` is "
|
||
"a list containing the resulting lines, not an iterator. Generator "
|
||
"expressions return an iterator that computes the values as necessary, not "
|
||
"needing to materialize all the values at once. This means that list "
|
||
"comprehensions aren't useful if you're working with iterators that return an "
|
||
"infinite stream or a very large amount of data. Generator expressions are "
|
||
"preferable in these situations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:358
|
||
msgid ""
|
||
"Generator expressions are surrounded by parentheses (\"()\") and list "
|
||
"comprehensions are surrounded by square brackets (\"[]\"). Generator "
|
||
"expressions have the form::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:371
|
||
msgid ""
|
||
"Again, for a list comprehension only the outside brackets are different "
|
||
"(square brackets instead of parentheses)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:374
|
||
msgid ""
|
||
"The elements of the generated output will be the successive values of "
|
||
"``expression``. The ``if`` clauses are all optional; if present, "
|
||
"``expression`` is only evaluated and added to the result when ``condition`` "
|
||
"is true."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:378
|
||
msgid ""
|
||
"Generator expressions always have to be written inside parentheses, but the "
|
||
"parentheses signalling a function call also count. If you want to create an "
|
||
"iterator that will be immediately passed to a function you can write::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:384
|
||
msgid ""
|
||
"The ``for...in`` clauses contain the sequences to be iterated over. The "
|
||
"sequences do not have to be the same length, because they are iterated over "
|
||
"from left to right, **not** in parallel. For each element in ``sequence1``, "
|
||
"``sequence2`` is looped over from the beginning. ``sequence3`` is then "
|
||
"looped over for each resulting pair of elements from ``sequence1`` and "
|
||
"``sequence2``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:390
|
||
msgid ""
|
||
"To put it another way, a list comprehension or generator expression is "
|
||
"equivalent to the following Python code::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:407
|
||
msgid ""
|
||
"This means that when there are multiple ``for...in`` clauses but no ``if`` "
|
||
"clauses, the length of the resulting output will be equal to the product of "
|
||
"the lengths of all the sequences. If you have two lists of length 3, the "
|
||
"output list is 9 elements long:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:419
|
||
msgid ""
|
||
"To avoid introducing an ambiguity into Python's grammar, if ``expression`` "
|
||
"is creating a tuple, it must be surrounded with parentheses. The first list "
|
||
"comprehension below is a syntax error, while the second one is correct::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:430
|
||
msgid "Generators"
|
||
msgstr "Générateurs"
|
||
|
||
#: ../Doc/howto/functional.rst:432
|
||
msgid ""
|
||
"Generators are a special class of functions that simplify the task of "
|
||
"writing iterators. Regular functions compute a value and return it, but "
|
||
"generators return an iterator that returns a stream of values."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:436
|
||
msgid ""
|
||
"You're doubtless familiar with how regular function calls work in Python or "
|
||
"C. When you call a function, it gets a private namespace where its local "
|
||
"variables are created. When the function reaches a ``return`` statement, "
|
||
"the local variables are destroyed and the value is returned to the caller. "
|
||
"A later call to the same function creates a new private namespace and a "
|
||
"fresh set of local variables. But, what if the local variables weren't "
|
||
"thrown away on exiting a function? What if you could later resume the "
|
||
"function where it left off? This is what generators provide; they can be "
|
||
"thought of as resumable functions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:445
|
||
msgid "Here's the simplest example of a generator function:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:451
|
||
msgid ""
|
||
"Any function containing a :keyword:`yield` keyword is a generator function; "
|
||
"this is detected by Python's :term:`bytecode` compiler which compiles the "
|
||
"function specially as a result."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:455
|
||
msgid ""
|
||
"When you call a generator function, it doesn't return a single value; "
|
||
"instead it returns a generator object that supports the iterator protocol. "
|
||
"On executing the ``yield`` expression, the generator outputs the value of "
|
||
"``i``, similar to a ``return`` statement. The big difference between "
|
||
"``yield`` and a ``return`` statement is that on reaching a ``yield`` the "
|
||
"generator's state of execution is suspended and local variables are "
|
||
"preserved. On the next call to the generator's :meth:`~generator.__next__` "
|
||
"method, the function will resume executing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:464
|
||
msgid "Here's a sample usage of the ``generate_ints()`` generator:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:481
|
||
msgid ""
|
||
"You could equally write ``for i in generate_ints(5)``, or ``a,b,c = "
|
||
"generate_ints(3)``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:484
|
||
msgid ""
|
||
"Inside a generator function, ``return value`` causes "
|
||
"``StopIteration(value)`` to be raised from the :meth:`~generator.__next__` "
|
||
"method. Once this happens, or the bottom of the function is reached, the "
|
||
"procession of values ends and the generator cannot yield any further values."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:489
|
||
msgid ""
|
||
"You could achieve the effect of generators manually by writing your own "
|
||
"class and storing all the local variables of the generator as instance "
|
||
"variables. For example, returning a list of integers could be done by "
|
||
"setting ``self.count`` to 0, and having the :meth:`~iterator.__next__` "
|
||
"method increment ``self.count`` and return it. However, for a moderately "
|
||
"complicated generator, writing a corresponding class can be much messier."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:497
|
||
msgid ""
|
||
"The test suite included with Python's library, :source:`Lib/test/"
|
||
"test_generators.py`, contains a number of more interesting examples. Here's "
|
||
"one generator that implements an in-order traversal of a tree using "
|
||
"generators recursively. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:513
|
||
msgid ""
|
||
"Two other examples in ``test_generators.py`` produce solutions for the N-"
|
||
"Queens problem (placing N queens on an NxN chess board so that no queen "
|
||
"threatens another) and the Knight's Tour (finding a route that takes a "
|
||
"knight to every square of an NxN chessboard without visiting any square "
|
||
"twice)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:521
|
||
msgid "Passing values into a generator"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:523
|
||
msgid ""
|
||
"In Python 2.4 and earlier, generators only produced output. Once a "
|
||
"generator's code was invoked to create an iterator, there was no way to pass "
|
||
"any new information into the function when its execution is resumed. You "
|
||
"could hack together this ability by making the generator look at a global "
|
||
"variable or by passing in some mutable object that callers then modify, but "
|
||
"these approaches are messy."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:530
|
||
msgid ""
|
||
"In Python 2.5 there's a simple way to pass values into a generator. :keyword:"
|
||
"`yield` became an expression, returning a value that can be assigned to a "
|
||
"variable or otherwise operated on::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:536
|
||
msgid ""
|
||
"I recommend that you **always** put parentheses around a ``yield`` "
|
||
"expression when you're doing something with the returned value, as in the "
|
||
"above example. The parentheses aren't always necessary, but it's easier to "
|
||
"always add them instead of having to remember when they're needed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:541
|
||
msgid ""
|
||
"(:pep:`342` explains the exact rules, which are that a ``yield``-expression "
|
||
"must always be parenthesized except when it occurs at the top-level "
|
||
"expression on the right-hand side of an assignment. This means you can "
|
||
"write ``val = yield i`` but have to use parentheses when there's an "
|
||
"operation, as in ``val = (yield i) + 12``.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:547
|
||
msgid ""
|
||
"Values are sent into a generator by calling its :meth:`send(value) "
|
||
"<generator.send>` method. This method resumes the generator's code and the "
|
||
"``yield`` expression returns the specified value. If the regular :meth:"
|
||
"`~generator.__next__` method is called, the ``yield`` returns ``None``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:552
|
||
msgid ""
|
||
"Here's a simple counter that increments by 1 and allows changing the value "
|
||
"of the internal counter."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:567
|
||
msgid "And here's an example of changing the counter:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:584
|
||
msgid ""
|
||
"Because ``yield`` will often be returning ``None``, you should always check "
|
||
"for this case. Don't just use its value in expressions unless you're sure "
|
||
"that the :meth:`~generator.send` method will be the only method used to "
|
||
"resume your generator function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:589
|
||
msgid ""
|
||
"In addition to :meth:`~generator.send`, there are two other methods on "
|
||
"generators:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:592
|
||
msgid ""
|
||
":meth:`throw(type, value=None, traceback=None) <generator.throw>` is used to "
|
||
"raise an exception inside the generator; the exception is raised by the "
|
||
"``yield`` expression where the generator's execution is paused."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:596
|
||
msgid ""
|
||
":meth:`~generator.close` raises a :exc:`GeneratorExit` exception inside the "
|
||
"generator to terminate the iteration. On receiving this exception, the "
|
||
"generator's code must either raise :exc:`GeneratorExit` or :exc:"
|
||
"`StopIteration`; catching the exception and doing anything else is illegal "
|
||
"and will trigger a :exc:`RuntimeError`. :meth:`~generator.close` will also "
|
||
"be called by Python's garbage collector when the generator is garbage-"
|
||
"collected."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:604
|
||
msgid ""
|
||
"If you need to run cleanup code when a :exc:`GeneratorExit` occurs, I "
|
||
"suggest using a ``try: ... finally:`` suite instead of catching :exc:"
|
||
"`GeneratorExit`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:607
|
||
msgid ""
|
||
"The cumulative effect of these changes is to turn generators from one-way "
|
||
"producers of information into both producers and consumers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:610
|
||
msgid ""
|
||
"Generators also become **coroutines**, a more generalized form of "
|
||
"subroutines. Subroutines are entered at one point and exited at another "
|
||
"point (the top of the function, and a ``return`` statement), but coroutines "
|
||
"can be entered, exited, and resumed at many different points (the ``yield`` "
|
||
"statements)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:617
|
||
msgid "Built-in functions"
|
||
msgstr "Fonctions Natives"
|
||
|
||
#: ../Doc/howto/functional.rst:619
|
||
msgid ""
|
||
"Let's look in more detail at built-in functions often used with iterators."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:621
|
||
msgid ""
|
||
"Two of Python's built-in functions, :func:`map` and :func:`filter` duplicate "
|
||
"the features of generator expressions:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:633
|
||
msgid ""
|
||
":func:`map(f, iterA, iterB, ...) <map>` returns an iterator over the sequence"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:625
|
||
msgid ""
|
||
"``f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:635
|
||
msgid "You can of course achieve the same effect with a list comprehension."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:637
|
||
msgid ""
|
||
":func:`filter(predicate, iter) <filter>` returns an iterator over all the "
|
||
"sequence elements that meet a certain condition, and is similarly duplicated "
|
||
"by list comprehensions. A **predicate** is a function that returns the "
|
||
"truth value of some condition; for use with :func:`filter`, the predicate "
|
||
"must take a single value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:650
|
||
msgid "This can also be written as a list comprehension:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:656
|
||
msgid ""
|
||
":func:`enumerate(iter) <enumerate>` counts off the elements in the iterable, "
|
||
"returning 2-tuples containing the count and each element. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:665
|
||
msgid ""
|
||
":func:`enumerate` is often used when looping through a list and recording "
|
||
"the indexes at which certain conditions are met::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:673
|
||
msgid ""
|
||
":func:`sorted(iterable, key=None, reverse=False) <sorted>` collects all the "
|
||
"elements of the iterable into a list, sorts the list, and returns the sorted "
|
||
"result. The *key* and *reverse* arguments are passed through to the "
|
||
"constructed list's :meth:`~list.sort` method. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:688
|
||
msgid ""
|
||
"(For a more detailed discussion of sorting, see the :ref:`sortinghowto`.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:691
|
||
msgid ""
|
||
"The :func:`any(iter) <any>` and :func:`all(iter) <all>` built-ins look at "
|
||
"the truth values of an iterable's contents. :func:`any` returns ``True`` if "
|
||
"any element in the iterable is a true value, and :func:`all` returns "
|
||
"``True`` if all of the elements are true values:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:710
|
||
msgid ""
|
||
":func:`zip(iterA, iterB, ...) <zip>` takes one element from each iterable "
|
||
"and returns them in a tuple::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:716
|
||
msgid ""
|
||
"It doesn't construct an in-memory list and exhaust all the input iterators "
|
||
"before returning; instead tuples are constructed and returned only if "
|
||
"they're requested. (The technical term for this behaviour is `lazy "
|
||
"evaluation <https://en.wikipedia.org/wiki/Lazy_evaluation>`__.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:721
|
||
msgid ""
|
||
"This iterator is intended to be used with iterables that are all of the same "
|
||
"length. If the iterables are of different lengths, the resulting stream "
|
||
"will be the same length as the shortest iterable. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:728
|
||
msgid ""
|
||
"You should avoid doing this, though, because an element may be taken from "
|
||
"the longer iterators and discarded. This means you can't go on to use the "
|
||
"iterators further because you risk skipping a discarded element."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:734
|
||
msgid "The itertools module"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:736
|
||
msgid ""
|
||
"The :mod:`itertools` module contains a number of commonly-used iterators as "
|
||
"well as functions for combining several iterators. This section will "
|
||
"introduce the module's contents by showing small examples."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:740
|
||
msgid "The module's functions fall into a few broad classes:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:742
|
||
msgid "Functions that create a new iterator based on an existing iterator."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:743
|
||
msgid "Functions for treating an iterator's elements as function arguments."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:744
|
||
msgid "Functions for selecting portions of an iterator's output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:745
|
||
msgid "A function for grouping an iterator's output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:748
|
||
msgid "Creating new iterators"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:750
|
||
msgid ""
|
||
":func:`itertools.count(n) <itertools.count>` returns an infinite stream of "
|
||
"integers, increasing by 1 each time. You can optionally supply the starting "
|
||
"number, which defaults to 0::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:759
|
||
msgid ""
|
||
":func:`itertools.cycle(iter) <itertools.cycle>` saves a copy of the contents "
|
||
"of a provided iterable and returns a new iterator that returns its elements "
|
||
"from first to last. The new iterator will repeat these elements "
|
||
"infinitely. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:766
|
||
msgid ""
|
||
":func:`itertools.repeat(elem, [n]) <itertools.repeat>` returns the provided "
|
||
"element *n* times, or returns the element endlessly if *n* is not "
|
||
"provided. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:774
|
||
msgid ""
|
||
":func:`itertools.chain(iterA, iterB, ...) <itertools.chain>` takes an "
|
||
"arbitrary number of iterables as input, and returns all the elements of the "
|
||
"first iterator, then all the elements of the second, and so on, until all of "
|
||
"the iterables have been exhausted. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:782
|
||
msgid ""
|
||
":func:`itertools.islice(iter, [start], stop, [step]) <itertools.islice>` "
|
||
"returns a stream that's a slice of the iterator. With a single *stop* "
|
||
"argument, it will return the first *stop* elements. If you supply a "
|
||
"starting index, you'll get *stop-start* elements, and if you supply a value "
|
||
"for *step*, elements will be skipped accordingly. Unlike Python's string "
|
||
"and list slicing, you can't use negative values for *start*, *stop*, or "
|
||
"*step*. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:796
|
||
msgid ""
|
||
":func:`itertools.tee(iter, [n]) <itertools.tee>` replicates an iterator; it "
|
||
"returns *n* independent iterators that will all return the contents of the "
|
||
"source iterator. If you don't supply a value for *n*, the default is 2. "
|
||
"Replicating iterators requires saving some of the contents of the source "
|
||
"iterator, so this can consume significant memory if the iterator is large "
|
||
"and one of the new iterators is consumed more than the others. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:815
|
||
msgid "Calling functions on elements"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:817
|
||
msgid ""
|
||
"The :mod:`operator` module contains a set of functions corresponding to "
|
||
"Python's operators. Some examples are :func:`operator.add(a, b) <operator."
|
||
"add>` (adds two values), :func:`operator.ne(a, b) <operator.ne>` (same as "
|
||
"``a != b``), and :func:`operator.attrgetter('id') <operator.attrgetter>` "
|
||
"(returns a callable that fetches the ``.id`` attribute)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:823
|
||
msgid ""
|
||
":func:`itertools.starmap(func, iter) <itertools.starmap>` assumes that the "
|
||
"iterable will return a stream of tuples, and calls *func* using these tuples "
|
||
"as the arguments::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:835
|
||
msgid "Selecting elements"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:837
|
||
msgid ""
|
||
"Another group of functions chooses a subset of an iterator's elements based "
|
||
"on a predicate."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:840
|
||
msgid ""
|
||
":func:`itertools.filterfalse(predicate, iter) <itertools.filterfalse>` is "
|
||
"the opposite of :func:`filter`, returning all elements for which the "
|
||
"predicate returns false::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:847
|
||
msgid ""
|
||
":func:`itertools.takewhile(predicate, iter) <itertools.takewhile>` returns "
|
||
"elements for as long as the predicate returns true. Once the predicate "
|
||
"returns false, the iterator will signal the end of its results. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:860
|
||
msgid ""
|
||
":func:`itertools.dropwhile(predicate, iter) <itertools.dropwhile>` discards "
|
||
"elements while the predicate returns true, and then returns the rest of the "
|
||
"iterable's results. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:870
|
||
msgid ""
|
||
":func:`itertools.compress(data, selectors) <itertools.compress>` takes two "
|
||
"iterators and returns only those elements of *data* for which the "
|
||
"corresponding element of *selectors* is true, stopping whenever either one "
|
||
"is exhausted::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:879
|
||
msgid "Combinatoric functions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:881
|
||
msgid ""
|
||
"The :func:`itertools.combinations(iterable, r) <itertools.combinations>` "
|
||
"returns an iterator giving all possible *r*-tuple combinations of the "
|
||
"elements contained in *iterable*. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:896
|
||
msgid ""
|
||
"The elements within each tuple remain in the same order as *iterable* "
|
||
"returned them. For example, the number 1 is always before 2, 3, 4, or 5 in "
|
||
"the examples above. A similar function, :func:`itertools."
|
||
"permutations(iterable, r=None) <itertools.permutations>`, removes this "
|
||
"constraint on the order, returning all possible arrangements of length *r*::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:915
|
||
msgid ""
|
||
"If you don't supply a value for *r* the length of the iterable is used, "
|
||
"meaning that all the elements are permuted."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:918
|
||
msgid ""
|
||
"Note that these functions produce all of the possible combinations by "
|
||
"position and don't require that the contents of *iterable* are unique::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:925
|
||
msgid ""
|
||
"The identical tuple ``('a', 'a', 'b')`` occurs twice, but the two 'a' "
|
||
"strings came from different positions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:928
|
||
msgid ""
|
||
"The :func:`itertools.combinations_with_replacement(iterable, r) <itertools."
|
||
"combinations_with_replacement>` function relaxes a different constraint: "
|
||
"elements can be repeated within a single tuple. Conceptually an element is "
|
||
"selected for the first position of each tuple and then is replaced before "
|
||
"the second element is selected. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:943
|
||
msgid "Grouping elements"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:945
|
||
msgid ""
|
||
"The last function I'll discuss, :func:`itertools.groupby(iter, "
|
||
"key_func=None) <itertools.groupby>`, is the most complicated. "
|
||
"``key_func(elem)`` is a function that can compute a key value for each "
|
||
"element returned by the iterable. If you don't supply a key function, the "
|
||
"key is simply each element itself."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:950
|
||
msgid ""
|
||
":func:`~itertools.groupby` collects all the consecutive elements from the "
|
||
"underlying iterable that have the same key value, and returns a stream of 2-"
|
||
"tuples containing a key value and an iterator for the elements with that key."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:978
|
||
msgid ""
|
||
":func:`~itertools.groupby` assumes that the underlying iterable's contents "
|
||
"will already be sorted based on the key. Note that the returned iterators "
|
||
"also use the underlying iterable, so you have to consume the results of "
|
||
"iterator-1 before requesting iterator-2 and its corresponding key."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:985
|
||
msgid "The functools module"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:987
|
||
msgid ""
|
||
"The :mod:`functools` module in Python 2.5 contains some higher-order "
|
||
"functions. A **higher-order function** takes one or more functions as input "
|
||
"and returns a new function. The most useful tool in this module is the :"
|
||
"func:`functools.partial` function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:992
|
||
msgid ""
|
||
"For programs written in a functional style, you'll sometimes want to "
|
||
"construct variants of existing functions that have some of the parameters "
|
||
"filled in. Consider a Python function ``f(a, b, c)``; you may wish to create "
|
||
"a new function ``g(b, c)`` that's equivalent to ``f(1, b, c)``; you're "
|
||
"filling in a value for one of ``f()``'s parameters. This is called "
|
||
"\"partial function application\"."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:998
|
||
msgid ""
|
||
"The constructor for :func:`~functools.partial` takes the arguments "
|
||
"``(function, arg1, arg2, ..., kwarg1=value1, kwarg2=value2)``. The "
|
||
"resulting object is callable, so you can just call it to invoke ``function`` "
|
||
"with the filled-in arguments."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1003
|
||
msgid "Here's a small but realistic example::"
|
||
msgstr "Voici un exemple court mais réaliste ::"
|
||
|
||
#: ../Doc/howto/functional.rst:1015
|
||
msgid ""
|
||
":func:`functools.reduce(func, iter, [initial_value]) <functools.reduce>` "
|
||
"cumulatively performs an operation on all the iterable's elements and, "
|
||
"therefore, can't be applied to infinite iterables. *func* must be a function "
|
||
"that takes two elements and returns a single value. :func:`functools."
|
||
"reduce` takes the first two elements A and B returned by the iterator and "
|
||
"calculates ``func(A, B)``. It then requests the third element, C, "
|
||
"calculates ``func(func(A, B), C)``, combines this result with the fourth "
|
||
"element returned, and continues until the iterable is exhausted. If the "
|
||
"iterable returns no values at all, a :exc:`TypeError` exception is raised. "
|
||
"If the initial value is supplied, it's used as a starting point and "
|
||
"``func(initial_value, A)`` is the first calculation. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1039
|
||
msgid ""
|
||
"If you use :func:`operator.add` with :func:`functools.reduce`, you'll add up "
|
||
"all the elements of the iterable. This case is so common that there's a "
|
||
"special built-in called :func:`sum` to compute it:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1051
|
||
msgid ""
|
||
"For many uses of :func:`functools.reduce`, though, it can be clearer to just "
|
||
"write the obvious :keyword:`for` loop::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1063
|
||
msgid ""
|
||
"A related function is `itertools.accumulate(iterable, func=operator.add) "
|
||
"<itertools.accumulate`. It performs the same calculation, but instead of "
|
||
"returning only the final result, :func:`accumulate` returns an iterator that "
|
||
"also yields each partial result::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1076
|
||
msgid "The operator module"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1078
|
||
msgid ""
|
||
"The :mod:`operator` module was mentioned earlier. It contains a set of "
|
||
"functions corresponding to Python's operators. These functions are often "
|
||
"useful in functional-style code because they save you from writing trivial "
|
||
"functions that perform a single operation."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1083
|
||
msgid "Some of the functions in this module are:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1085
|
||
msgid ""
|
||
"Math operations: ``add()``, ``sub()``, ``mul()``, ``floordiv()``, "
|
||
"``abs()``, ..."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1086
|
||
msgid "Logical operations: ``not_()``, ``truth()``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1087
|
||
msgid "Bitwise operations: ``and_()``, ``or_()``, ``invert()``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1088
|
||
msgid ""
|
||
"Comparisons: ``eq()``, ``ne()``, ``lt()``, ``le()``, ``gt()``, and ``ge()``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1089
|
||
msgid "Object identity: ``is_()``, ``is_not()``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1091
|
||
msgid "Consult the operator module's documentation for a complete list."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1095
|
||
msgid "Small functions and the lambda expression"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1097
|
||
msgid ""
|
||
"When writing functional-style programs, you'll often need little functions "
|
||
"that act as predicates or that combine elements in some way."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1100
|
||
msgid ""
|
||
"If there's a Python built-in or a module function that's suitable, you don't "
|
||
"need to define a new function at all::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1106
|
||
msgid ""
|
||
"If the function you need doesn't exist, you need to write it. One way to "
|
||
"write small functions is to use the :keyword:`lambda` statement. ``lambda`` "
|
||
"takes a number of parameters and an expression combining these parameters, "
|
||
"and creates an anonymous function that returns the value of the expression::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1115
|
||
msgid ""
|
||
"An alternative is to just use the ``def`` statement and define a function in "
|
||
"the usual way::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1124
|
||
msgid ""
|
||
"Which alternative is preferable? That's a style question; my usual course "
|
||
"is to avoid using ``lambda``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1127
|
||
msgid ""
|
||
"One reason for my preference is that ``lambda`` is quite limited in the "
|
||
"functions it can define. The result has to be computable as a single "
|
||
"expression, which means you can't have multiway ``if... elif... else`` "
|
||
"comparisons or ``try... except`` statements. If you try to do too much in a "
|
||
"``lambda`` statement, you'll end up with an overly complicated expression "
|
||
"that's hard to read. Quick, what's the following code doing? ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1137
|
||
msgid ""
|
||
"You can figure it out, but it takes time to disentangle the expression to "
|
||
"figure out what's going on. Using a short nested ``def`` statements makes "
|
||
"things a little bit better::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1147
|
||
msgid "But it would be best of all if I had simply used a ``for`` loop::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1153
|
||
msgid "Or the :func:`sum` built-in and a generator expression::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1157
|
||
msgid ""
|
||
"Many uses of :func:`functools.reduce` are clearer when written as ``for`` "
|
||
"loops."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1159
|
||
msgid ""
|
||
"Fredrik Lundh once suggested the following set of rules for refactoring uses "
|
||
"of ``lambda``:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1162
|
||
msgid "Write a lambda function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1163
|
||
msgid "Write a comment explaining what the heck that lambda does."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1164
|
||
msgid ""
|
||
"Study the comment for a while, and think of a name that captures the essence "
|
||
"of the comment."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1166
|
||
msgid "Convert the lambda to a def statement, using that name."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1167
|
||
msgid "Remove the comment."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1169
|
||
msgid ""
|
||
"I really like these rules, but you're free to disagree about whether this "
|
||
"lambda-free style is better."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1174
|
||
msgid "Revision History and Acknowledgements"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1176
|
||
msgid ""
|
||
"The author would like to thank the following people for offering "
|
||
"suggestions, corrections and assistance with various drafts of this article: "
|
||
"Ian Bicking, Nick Coghlan, Nick Efford, Raymond Hettinger, Jim Jewett, Mike "
|
||
"Krell, Leandro Lameiro, Jussi Salmela, Collin Winter, Blake Winton."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1181
|
||
msgid "Version 0.1: posted June 30 2006."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1183
|
||
msgid "Version 0.11: posted July 1 2006. Typo fixes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1185
|
||
msgid ""
|
||
"Version 0.2: posted July 10 2006. Merged genexp and listcomp sections into "
|
||
"one. Typo fixes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1188
|
||
msgid ""
|
||
"Version 0.21: Added more references suggested on the tutor mailing list."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1190
|
||
msgid ""
|
||
"Version 0.30: Adds a section on the ``functional`` module written by Collin "
|
||
"Winter; adds short section on the operator module; a few other edits."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1195 ../Doc/howto/unicode.rst:209
|
||
#: ../Doc/howto/unicode.rst:483 ../Doc/howto/unicode.rst:703
|
||
msgid "References"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1198
|
||
msgid "General"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1200
|
||
msgid ""
|
||
"**Structure and Interpretation of Computer Programs**, by Harold Abelson and "
|
||
"Gerald Jay Sussman with Julie Sussman. Full text at https://mitpress.mit."
|
||
"edu/sicp/. In this classic textbook of computer science, chapters 2 and 3 "
|
||
"discuss the use of sequences and streams to organize the data flow inside a "
|
||
"program. The book uses Scheme for its examples, but many of the design "
|
||
"approaches described in these chapters are applicable to functional-style "
|
||
"Python code."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1208
|
||
msgid ""
|
||
"http://www.defmacro.org/ramblings/fp.html: A general introduction to "
|
||
"functional programming that uses Java examples and has a lengthy historical "
|
||
"introduction."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1211
|
||
msgid ""
|
||
"https://en.wikipedia.org/wiki/Functional_programming: General Wikipedia "
|
||
"entry describing functional programming."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1214
|
||
msgid "https://en.wikipedia.org/wiki/Coroutine: Entry for coroutines."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1216
|
||
msgid ""
|
||
"https://en.wikipedia.org/wiki/Currying: Entry for the concept of currying."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1219
|
||
msgid "Python-specific"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1221
|
||
msgid ""
|
||
"http://gnosis.cx/TPiP/: The first chapter of David Mertz's book :title-"
|
||
"reference:`Text Processing in Python` discusses functional programming for "
|
||
"text processing, in the section titled \"Utilizing Higher-Order Functions in "
|
||
"Text Processing\"."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1226
|
||
msgid ""
|
||
"Mertz also wrote a 3-part series of articles on functional programming for "
|
||
"IBM's DeveloperWorks site; see `part 1 <https://www.ibm.com/developerworks/"
|
||
"linux/library/l-prog/index.html>`__, `part 2 <https://www.ibm.com/"
|
||
"developerworks/linux/library/l-prog2/index.html>`__, and `part 3 <https://"
|
||
"www.ibm.com/developerworks/linux/library/l-prog3/index.html>`__,"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1234
|
||
msgid "Python documentation"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1236
|
||
msgid "Documentation for the :mod:`itertools` module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1238
|
||
msgid "Documentation for the :mod:`operator` module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1240
|
||
msgid ":pep:`289`: \"Generator Expressions\""
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1242
|
||
msgid ""
|
||
":pep:`342`: \"Coroutines via Enhanced Generators\" describes the new "
|
||
"generator features in Python 2.5."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/index.rst:3
|
||
msgid "Python HOWTOs"
|
||
msgstr "Les HOWTOs de Python [en]"
|
||
|
||
#: ../Doc/howto/index.rst:5
|
||
msgid ""
|
||
"Python HOWTOs are documents that cover a single, specific topic, and attempt "
|
||
"to cover it fairly completely. Modelled on the Linux Documentation Project's "
|
||
"HOWTO collection, this collection is an effort to foster documentation "
|
||
"that's more detailed than the Python Library Reference."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/index.rst:11
|
||
msgid "Currently, the HOWTOs are:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:5
|
||
msgid "Instrumenting CPython with DTrace and SystemTap"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:7
|
||
msgid "David Malcolm"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:8
|
||
msgid "Łukasz Langa"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:10
|
||
msgid ""
|
||
"DTrace and SystemTap are monitoring tools, each providing a way to inspect "
|
||
"what the processes on a computer system are doing. They both use domain-"
|
||
"specific languages allowing a user to write scripts which:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:14
|
||
msgid "filter which processes are to be observed"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:15
|
||
msgid "gather data from the processes of interest"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:16
|
||
msgid "generate reports on the data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:18
|
||
msgid ""
|
||
"As of Python 3.6, CPython can be built with embedded \"markers\", also known "
|
||
"as \"probes\", that can be observed by a DTrace or SystemTap script, making "
|
||
"it easier to monitor what the CPython processes on a system are doing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:28
|
||
msgid ""
|
||
"DTrace markers are implementation details of the CPython interpreter. No "
|
||
"guarantees are made about probe compatibility between versions of CPython. "
|
||
"DTrace scripts can stop working or work incorrectly without warning when "
|
||
"changing CPython versions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:35
|
||
msgid "Enabling the static markers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:37
|
||
msgid ""
|
||
"macOS comes with built-in support for DTrace. On Linux, in order to build "
|
||
"CPython with the embedded markers for SystemTap, the SystemTap development "
|
||
"tools must be installed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:41
|
||
msgid "On a Linux machine, this can be done via::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:45
|
||
msgid "or::"
|
||
msgstr "ou : ::"
|
||
|
||
#: ../Doc/howto/instrumentation.rst:50
|
||
msgid "CPython must then be configured `--with-dtrace`::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:54
|
||
msgid ""
|
||
"On macOS, you can list available DTrace probes by running a Python process "
|
||
"in the background and listing all probes made available by the Python "
|
||
"provider::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:71
|
||
msgid ""
|
||
"On Linux, you can verify if the SystemTap static markers are present in the "
|
||
"built binary by seeing if it contains a \".note.stapsdt\" section."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:79
|
||
msgid ""
|
||
"If you've built Python as a shared library (with --enable-shared), you need "
|
||
"to look instead within the shared library. For example:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:87
|
||
msgid "Sufficiently modern readelf can print the metadata:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:126
|
||
msgid ""
|
||
"The above metadata contains information for SystemTap describing how it can "
|
||
"patch strategically-placed machine code instructions to enable the tracing "
|
||
"hooks used by a SystemTap script."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:132
|
||
msgid "Static DTrace probes"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:134
|
||
msgid ""
|
||
"The following example DTrace script can be used to show the call/return "
|
||
"hierarchy of a Python script, only tracing within the invocation of a "
|
||
"function called \"start\". In other words, import-time function invocations "
|
||
"are not going to be listed:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:173 ../Doc/howto/instrumentation.rst:231
|
||
msgid "It can be invoked like this:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:179 ../Doc/howto/instrumentation.rst:239
|
||
#: ../Doc/howto/logging-cookbook.rst:75
|
||
msgid "The output looks like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:202
|
||
msgid "Static SystemTap markers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:204
|
||
msgid ""
|
||
"The low-level way to use the SystemTap integration is to use the static "
|
||
"markers directly. This requires you to explicitly state the binary file "
|
||
"containing them."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:208
|
||
msgid ""
|
||
"For example, this SystemTap script can be used to show the call/return "
|
||
"hierarchy of a Python script:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:248
|
||
msgid "where the columns are:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:250
|
||
msgid "time in microseconds since start of script"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:252
|
||
msgid "name of executable"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:254
|
||
msgid "PID of process"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:256
|
||
msgid ""
|
||
"and the remainder indicates the call/return hierarchy as the script executes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:258
|
||
msgid ""
|
||
"For a `--enable-shared` build of CPython, the markers are contained within "
|
||
"the libpython shared library, and the probe's dotted path needs to reflect "
|
||
"this. For example, this line from the above example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:264
|
||
msgid "should instead read::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:268
|
||
msgid "(assuming a debug build of CPython 3.6)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:272
|
||
msgid "Available static markers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:278
|
||
msgid ""
|
||
"This marker indicates that execution of a Python function has begun. It is "
|
||
"only triggered for pure-Python (bytecode) functions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:281
|
||
msgid ""
|
||
"The filename, function name, and line number are provided back to the "
|
||
"tracing script as positional arguments, which must be accessed using ``"
|
||
"$arg1``, ``$arg2``, ``$arg3``:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:285
|
||
msgid ""
|
||
"``$arg1`` : ``(const char *)`` filename, accessible using "
|
||
"``user_string($arg1)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:287
|
||
msgid ""
|
||
"``$arg2`` : ``(const char *)`` function name, accessible using "
|
||
"``user_string($arg2)``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:290
|
||
msgid "``$arg3`` : ``int`` line number"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:294
|
||
msgid ""
|
||
"This marker is the converse of :c:func:`function__entry`, and indicates that "
|
||
"execution of a Python function has ended (either via ``return``, or via an "
|
||
"exception). It is only triggered for pure-Python (bytecode) functions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:298
|
||
msgid "The arguments are the same as for :c:func:`function__entry`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:302
|
||
msgid ""
|
||
"This marker indicates a Python line is about to be executed. It is the "
|
||
"equivalent of line-by-line tracing with a Python profiler. It is not "
|
||
"triggered within C functions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:306
|
||
msgid "The arguments are the same as for :c:func:`function__entry`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:310
|
||
msgid ""
|
||
"Fires when the Python interpreter starts a garbage collection cycle. "
|
||
"``arg0`` is the generation to scan, like :func:`gc.collect()`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:315
|
||
msgid ""
|
||
"Fires when the Python interpreter finishes a garbage collection cycle. "
|
||
"``arg0`` is the number of collected objects."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:320
|
||
msgid "SystemTap Tapsets"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:322
|
||
msgid ""
|
||
"The higher-level way to use the SystemTap integration is to use a \"tapset"
|
||
"\": SystemTap's equivalent of a library, which hides some of the lower-level "
|
||
"details of the static markers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:326
|
||
msgid "Here is a tapset file, based on a non-shared build of CPython:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:349
|
||
msgid ""
|
||
"If this file is installed in SystemTap's tapset directory (e.g. ``/usr/share/"
|
||
"systemtap/tapset``), then these additional probepoints become available:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:355
|
||
msgid ""
|
||
"This probe point indicates that execution of a Python function has begun. It "
|
||
"is only triggered for pure-python (bytecode) functions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:360
|
||
msgid ""
|
||
"This probe point is the converse of :c:func:`python.function.return`, and "
|
||
"indicates that execution of a Python function has ended (either via "
|
||
"``return``, or via an exception). It is only triggered for pure-python "
|
||
"(bytecode) functions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:367
|
||
msgid "Examples"
|
||
msgstr "Exemples"
|
||
|
||
#: ../Doc/howto/instrumentation.rst:368
|
||
msgid ""
|
||
"This SystemTap script uses the tapset above to more cleanly implement the "
|
||
"example given above of tracing the Python function-call hierarchy, without "
|
||
"needing to directly name the static markers:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/instrumentation.rst:387
|
||
msgid ""
|
||
"The following script uses the tapset above to provide a top-like view of all "
|
||
"running CPython code, showing the top 20 most frequently-entered bytecode "
|
||
"frames, each second, across the whole system:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:9
|
||
msgid "An introduction to the ipaddress module"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:11
|
||
msgid "Peter Moody"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:12
|
||
msgid "Nick Coghlan"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:0
|
||
msgid "Overview"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:16
|
||
msgid ""
|
||
"This document aims to provide a gentle introduction to the :mod:`ipaddress` "
|
||
"module. It is aimed primarily at users that aren't already familiar with IP "
|
||
"networking terminology, but may also be useful to network engineers wanting "
|
||
"an overview of how :mod:`ipaddress` represents IP network addressing "
|
||
"concepts."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:24
|
||
msgid "Creating Address/Network/Interface objects"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:26
|
||
msgid ""
|
||
"Since :mod:`ipaddress` is a module for inspecting and manipulating IP "
|
||
"addresses, the first thing you'll want to do is create some objects. You "
|
||
"can use :mod:`ipaddress` to create objects from strings and integers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:32
|
||
msgid "A Note on IP Versions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:34
|
||
msgid ""
|
||
"For readers that aren't particularly familiar with IP addressing, it's "
|
||
"important to know that the Internet Protocol is currently in the process of "
|
||
"moving from version 4 of the protocol to version 6. This transition is "
|
||
"occurring largely because version 4 of the protocol doesn't provide enough "
|
||
"addresses to handle the needs of the whole world, especially given the "
|
||
"increasing number of devices with direct connections to the internet."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:41
|
||
msgid ""
|
||
"Explaining the details of the differences between the two versions of the "
|
||
"protocol is beyond the scope of this introduction, but readers need to at "
|
||
"least be aware that these two versions exist, and it will sometimes be "
|
||
"necessary to force the use of one version or the other."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:48
|
||
msgid "IP Host Addresses"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:50
|
||
msgid ""
|
||
"Addresses, often referred to as \"host addresses\" are the most basic unit "
|
||
"when working with IP addressing. The simplest way to create addresses is to "
|
||
"use the :func:`ipaddress.ip_address` factory function, which automatically "
|
||
"determines whether to create an IPv4 or IPv6 address based on the passed in "
|
||
"value:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:61
|
||
msgid ""
|
||
"Addresses can also be created directly from integers. Values that will fit "
|
||
"within 32 bits are assumed to be IPv4 addresses::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:69
|
||
msgid ""
|
||
"To force the use of IPv4 or IPv6 addresses, the relevant classes can be "
|
||
"invoked directly. This is particularly useful to force creation of IPv6 "
|
||
"addresses for small integers::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:82
|
||
msgid "Defining Networks"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:84
|
||
msgid ""
|
||
"Host addresses are usually grouped together into IP networks, so :mod:"
|
||
"`ipaddress` provides a way to create, inspect and manipulate network "
|
||
"definitions. IP network objects are constructed from strings that define the "
|
||
"range of host addresses that are part of that network. The simplest form for "
|
||
"that information is a \"network address/network prefix\" pair, where the "
|
||
"prefix defines the number of leading bits that are compared to determine "
|
||
"whether or not an address is part of the network and the network address "
|
||
"defines the expected value of those bits."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:93
|
||
msgid ""
|
||
"As for addresses, a factory function is provided that determines the correct "
|
||
"IP version automatically::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:101
|
||
msgid ""
|
||
"Network objects cannot have any host bits set. The practical effect of this "
|
||
"is that ``192.0.2.1/24`` does not describe a network. Such definitions are "
|
||
"referred to as interface objects since the ip-on-a-network notation is "
|
||
"commonly used to describe network interfaces of a computer on a given "
|
||
"network and are described further in the next section."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:107
|
||
msgid ""
|
||
"By default, attempting to create a network object with host bits set will "
|
||
"result in :exc:`ValueError` being raised. To request that the additional "
|
||
"bits instead be coerced to zero, the flag ``strict=False`` can be passed to "
|
||
"the constructor::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:119
|
||
msgid ""
|
||
"While the string form offers significantly more flexibility, networks can "
|
||
"also be defined with integers, just like host addresses. In this case, the "
|
||
"network is considered to contain only the single address identified by the "
|
||
"integer, so the network prefix includes the entire network address::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:129
|
||
msgid ""
|
||
"As with addresses, creation of a particular kind of network can be forced by "
|
||
"calling the class constructor directly instead of using the factory function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:135
|
||
msgid "Host Interfaces"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:137
|
||
msgid ""
|
||
"As mentioned just above, if you need to describe an address on a particular "
|
||
"network, neither the address nor the network classes are sufficient. "
|
||
"Notation like ``192.0.2.1/24`` is commonly used by network engineers and the "
|
||
"people who write tools for firewalls and routers as shorthand for \"the host "
|
||
"``192.0.2.1`` on the network ``192.0.2.0/24``\", Accordingly, :mod:"
|
||
"`ipaddress` provides a set of hybrid classes that associate an address with "
|
||
"a particular network. The interface for creation is identical to that for "
|
||
"defining network objects, except that the address portion isn't constrained "
|
||
"to being a network address."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:152
|
||
msgid ""
|
||
"Integer inputs are accepted (as with networks), and use of a particular IP "
|
||
"version can be forced by calling the relevant constructor directly."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:157
|
||
msgid "Inspecting Address/Network/Interface Objects"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:159
|
||
msgid ""
|
||
"You've gone to the trouble of creating an IPv(4|6)(Address|Network|"
|
||
"Interface) object, so you probably want to get information about it. :mod:"
|
||
"`ipaddress` tries to make doing this easy and intuitive."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:163
|
||
msgid "Extracting the IP version::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:172
|
||
msgid "Obtaining the network from an interface::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:181
|
||
msgid "Finding out how many individual addresses are in a network::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:190
|
||
msgid "Iterating through the \"usable\" addresses on a network::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:205
|
||
msgid ""
|
||
"Obtaining the netmask (i.e. set bits corresponding to the network prefix) or "
|
||
"the hostmask (any bits that are not part of the netmask):"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:220
|
||
msgid "Exploding or compressing the address::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:231
|
||
msgid ""
|
||
"While IPv4 doesn't support explosion or compression, the associated objects "
|
||
"still provide the relevant properties so that version neutral code can "
|
||
"easily ensure the most concise or most verbose form is used for IPv6 "
|
||
"addresses while still correctly handling IPv4 addresses."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:238
|
||
msgid "Networks as lists of Addresses"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:240
|
||
msgid ""
|
||
"It's sometimes useful to treat networks as lists. This means it is possible "
|
||
"to index them like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:253
|
||
msgid ""
|
||
"It also means that network objects lend themselves to using the list "
|
||
"membership test syntax like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:259
|
||
msgid "Containment testing is done efficiently based on the network prefix::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:269
|
||
msgid "Comparisons"
|
||
msgstr "Comparaisons"
|
||
|
||
#: ../Doc/howto/ipaddress.rst:271
|
||
msgid ""
|
||
":mod:`ipaddress` provides some simple, hopefully intuitive ways to compare "
|
||
"objects, where it makes sense::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:277
|
||
msgid ""
|
||
"A :exc:`TypeError` exception is raised if you try to compare objects of "
|
||
"different versions or different types."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:282
|
||
msgid "Using IP Addresses with other modules"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:284
|
||
msgid ""
|
||
"Other modules that use IP addresses (such as :mod:`socket`) usually won't "
|
||
"accept objects from this module directly. Instead, they must be coerced to "
|
||
"an integer or string that the other module will accept::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:296
|
||
msgid "Getting more detail when instance creation fails"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:298
|
||
msgid ""
|
||
"When creating address/network/interface objects using the version-agnostic "
|
||
"factory functions, any errors will be reported as :exc:`ValueError` with a "
|
||
"generic error message that simply says the passed in value was not "
|
||
"recognized as an object of that type. The lack of a specific error is "
|
||
"because it's necessary to know whether the value is *supposed* to be IPv4 or "
|
||
"IPv6 in order to provide more detail on why it has been rejected."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:305
|
||
msgid ""
|
||
"To support use cases where it is useful to have access to this additional "
|
||
"detail, the individual class constructors actually raise the :exc:"
|
||
"`ValueError` subclasses :exc:`ipaddress.AddressValueError` and :exc:"
|
||
"`ipaddress.NetmaskValueError` to indicate exactly which part of the "
|
||
"definition failed to parse correctly."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:311
|
||
msgid ""
|
||
"The error messages are significantly more detailed when using the class "
|
||
"constructors directly. For example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/ipaddress.rst:332
|
||
msgid ""
|
||
"However, both of the module specific exceptions have :exc:`ValueError` as "
|
||
"their parent class, so if you're not concerned with the particular type of "
|
||
"error, you can still write code like the following::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:3
|
||
msgid "Logging HOWTO"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:5 ../Doc/howto/logging-cookbook.rst:7
|
||
msgid "Vinay Sajip <vinay_sajip at red-dove dot com>"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:12
|
||
msgid "Basic Logging Tutorial"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:14
|
||
msgid ""
|
||
"Logging is a means of tracking events that happen when some software runs. "
|
||
"The software's developer adds logging calls to their code to indicate that "
|
||
"certain events have occurred. An event is described by a descriptive message "
|
||
"which can optionally contain variable data (i.e. data that is potentially "
|
||
"different for each occurrence of the event). Events also have an importance "
|
||
"which the developer ascribes to the event; the importance can also be called "
|
||
"the *level* or *severity*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:23
|
||
msgid "When to use logging"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:25
|
||
msgid ""
|
||
"Logging provides a set of convenience functions for simple logging usage. "
|
||
"These are :func:`debug`, :func:`info`, :func:`warning`, :func:`error` and :"
|
||
"func:`critical`. To determine when to use logging, see the table below, "
|
||
"which states, for each of a set of common tasks, the best tool to use for it."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:31
|
||
msgid "Task you want to perform"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:31
|
||
msgid "The best tool for the task"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:33
|
||
msgid ""
|
||
"Display console output for ordinary usage of a command line script or program"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:33
|
||
msgid ":func:`print`"
|
||
msgstr ":func:`print`"
|
||
|
||
#: ../Doc/howto/logging.rst:37
|
||
msgid ""
|
||
"Report events that occur during normal operation of a program (e.g. for "
|
||
"status monitoring or fault investigation)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:37
|
||
msgid ""
|
||
":func:`logging.info` (or :func:`logging.debug` for very detailed output for "
|
||
"diagnostic purposes)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:42
|
||
msgid "Issue a warning regarding a particular runtime event"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:42
|
||
msgid ""
|
||
":func:`warnings.warn` in library code if the issue is avoidable and the "
|
||
"client application should be modified to eliminate the warning"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:47
|
||
msgid ""
|
||
":func:`logging.warning` if there is nothing the client application can do "
|
||
"about the situation, but the event should still be noted"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:52
|
||
msgid "Report an error regarding a particular runtime event"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:52
|
||
msgid "Raise an exception"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:55
|
||
msgid ""
|
||
"Report suppression of an error without raising an exception (e.g. error "
|
||
"handler in a long-running server process)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:55
|
||
msgid ""
|
||
":func:`logging.error`, :func:`logging.exception` or :func:`logging.critical` "
|
||
"as appropriate for the specific error and application domain"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:62
|
||
msgid ""
|
||
"The logging functions are named after the level or severity of the events "
|
||
"they are used to track. The standard levels and their applicability are "
|
||
"described below (in increasing order of severity):"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:69 ../Doc/howto/logging.rst:826
|
||
msgid "Level"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:69
|
||
msgid "When it's used"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:71 ../Doc/howto/logging.rst:836
|
||
msgid "``DEBUG``"
|
||
msgstr "``DEBUG``"
|
||
|
||
#: ../Doc/howto/logging.rst:71
|
||
msgid ""
|
||
"Detailed information, typically of interest only when diagnosing problems."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:74 ../Doc/howto/logging.rst:834
|
||
msgid "``INFO``"
|
||
msgstr "``INFO``"
|
||
|
||
#: ../Doc/howto/logging.rst:74
|
||
msgid "Confirmation that things are working as expected."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:77 ../Doc/howto/logging.rst:832
|
||
msgid "``WARNING``"
|
||
msgstr "``WARNING``"
|
||
|
||
#: ../Doc/howto/logging.rst:77
|
||
msgid ""
|
||
"An indication that something unexpected happened, or indicative of some "
|
||
"problem in the near future (e.g. 'disk space low'). The software is still "
|
||
"working as expected."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:82 ../Doc/howto/logging.rst:830
|
||
msgid "``ERROR``"
|
||
msgstr "``ERROR``"
|
||
|
||
#: ../Doc/howto/logging.rst:82
|
||
msgid ""
|
||
"Due to a more serious problem, the software has not been able to perform "
|
||
"some function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:85 ../Doc/howto/logging.rst:828
|
||
msgid "``CRITICAL``"
|
||
msgstr "``CRITICAL``"
|
||
|
||
#: ../Doc/howto/logging.rst:85
|
||
msgid ""
|
||
"A serious error, indicating that the program itself may be unable to "
|
||
"continue running."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:89
|
||
msgid ""
|
||
"The default level is ``WARNING``, which means that only events of this level "
|
||
"and above will be tracked, unless the logging package is configured to do "
|
||
"otherwise."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:93
|
||
msgid ""
|
||
"Events that are tracked can be handled in different ways. The simplest way "
|
||
"of handling tracked events is to print them to the console. Another common "
|
||
"way is to write them to a disk file."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:101
|
||
msgid "A simple example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:103
|
||
msgid "A very simple example is::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:109
|
||
msgid "If you type these lines into a script and run it, you'll see:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:115
|
||
msgid ""
|
||
"printed out on the console. The ``INFO`` message doesn't appear because the "
|
||
"default level is ``WARNING``. The printed message includes the indication of "
|
||
"the level and the description of the event provided in the logging call, i."
|
||
"e. 'Watch out!'. Don't worry about the 'root' part for now: it will be "
|
||
"explained later. The actual output can be formatted quite flexibly if you "
|
||
"need that; formatting options will also be explained later."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:124
|
||
msgid "Logging to a file"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:126
|
||
msgid ""
|
||
"A very common situation is that of recording logging events in a file, so "
|
||
"let's look at that next. Be sure to try the following in a newly-started "
|
||
"Python interpreter, and don't just continue from the session described "
|
||
"above::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:136
|
||
msgid ""
|
||
"And now if we open the file and look at what we have, we should find the log "
|
||
"messages::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:143
|
||
msgid ""
|
||
"This example also shows how you can set the logging level which acts as the "
|
||
"threshold for tracking. In this case, because we set the threshold to "
|
||
"``DEBUG``, all of the messages were printed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:147
|
||
msgid ""
|
||
"If you want to set the logging level from a command-line option such as::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:151
|
||
msgid ""
|
||
"and you have the value of the parameter passed for ``--log`` in some "
|
||
"variable *loglevel*, you can use::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:156
|
||
msgid ""
|
||
"to get the value which you'll pass to :func:`basicConfig` via the *level* "
|
||
"argument. You may want to error check any user input value, perhaps as in "
|
||
"the following example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:168
|
||
msgid ""
|
||
"The call to :func:`basicConfig` should come *before* any calls to :func:"
|
||
"`debug`, :func:`info` etc. As it's intended as a one-off simple "
|
||
"configuration facility, only the first call will actually do anything: "
|
||
"subsequent calls are effectively no-ops."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:173
|
||
msgid ""
|
||
"If you run the above script several times, the messages from successive runs "
|
||
"are appended to the file *example.log*. If you want each run to start "
|
||
"afresh, not remembering the messages from earlier runs, you can specify the "
|
||
"*filemode* argument, by changing the call in the above example to::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:180
|
||
msgid ""
|
||
"The output will be the same as before, but the log file is no longer "
|
||
"appended to, so the messages from earlier runs are lost."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:185
|
||
msgid "Logging from multiple modules"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:187
|
||
msgid ""
|
||
"If your program consists of multiple modules, here's an example of how you "
|
||
"could organize logging in it::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:211
|
||
msgid "If you run *myapp.py*, you should see this in *myapp.log*::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:217
|
||
msgid ""
|
||
"which is hopefully what you were expecting to see. You can generalize this "
|
||
"to multiple modules, using the pattern in *mylib.py*. Note that for this "
|
||
"simple usage pattern, you won't know, by looking in the log file, *where* in "
|
||
"your application your messages came from, apart from looking at the event "
|
||
"description. If you want to track the location of your messages, you'll need "
|
||
"to refer to the documentation beyond the tutorial level -- see :ref:`logging-"
|
||
"advanced-tutorial`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:227
|
||
msgid "Logging variable data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:229
|
||
msgid ""
|
||
"To log variable data, use a format string for the event description message "
|
||
"and append the variable data as arguments. For example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:235
|
||
msgid "will display:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:241
|
||
msgid ""
|
||
"As you can see, merging of variable data into the event description message "
|
||
"uses the old, %-style of string formatting. This is for backwards "
|
||
"compatibility: the logging package pre-dates newer formatting options such "
|
||
"as :meth:`str.format` and :class:`string.Template`. These newer formatting "
|
||
"options *are* supported, but exploring them is outside the scope of this "
|
||
"tutorial: see :ref:`formatting-styles` for more information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:250
|
||
msgid "Changing the format of displayed messages"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:252
|
||
msgid ""
|
||
"To change the format which is used to display messages, you need to specify "
|
||
"the format you want to use::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:261
|
||
msgid "which would print::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:267
|
||
msgid ""
|
||
"Notice that the 'root' which appeared in earlier examples has disappeared. "
|
||
"For a full set of things that can appear in format strings, you can refer to "
|
||
"the documentation for :ref:`logrecord-attributes`, but for simple usage, you "
|
||
"just need the *levelname* (severity), *message* (event description, "
|
||
"including variable data) and perhaps to display when the event occurred. "
|
||
"This is described in the next section."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:276
|
||
msgid "Displaying the date/time in messages"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:278
|
||
msgid ""
|
||
"To display the date and time of an event, you would place '%(asctime)s' in "
|
||
"your format string::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:285
|
||
msgid "which should print something like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:289
|
||
msgid ""
|
||
"The default format for date/time display (shown above) is ISO8601. If you "
|
||
"need more control over the formatting of the date/time, provide a *datefmt* "
|
||
"argument to ``basicConfig``, as in this example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:297
|
||
msgid "which would display something like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:301
|
||
msgid ""
|
||
"The format of the *datefmt* argument is the same as supported by :func:`time."
|
||
"strftime`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:306
|
||
msgid "Next Steps"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:308
|
||
msgid ""
|
||
"That concludes the basic tutorial. It should be enough to get you up and "
|
||
"running with logging. There's a lot more that the logging package offers, "
|
||
"but to get the best out of it, you'll need to invest a little more of your "
|
||
"time in reading the following sections. If you're ready for that, grab some "
|
||
"of your favourite beverage and carry on."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:314
|
||
msgid ""
|
||
"If your logging needs are simple, then use the above examples to incorporate "
|
||
"logging into your own scripts, and if you run into problems or don't "
|
||
"understand something, please post a question on the comp.lang.python Usenet "
|
||
"group (available at https://groups.google.com/group/comp.lang.python) and "
|
||
"you should receive help before too long."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:320
|
||
msgid ""
|
||
"Still here? You can carry on reading the next few sections, which provide a "
|
||
"slightly more advanced/in-depth tutorial than the basic one above. After "
|
||
"that, you can take a look at the :ref:`logging-cookbook`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:328
|
||
msgid "Advanced Logging Tutorial"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:330
|
||
msgid ""
|
||
"The logging library takes a modular approach and offers several categories "
|
||
"of components: loggers, handlers, filters, and formatters."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:333
|
||
msgid "Loggers expose the interface that application code directly uses."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:334
|
||
msgid ""
|
||
"Handlers send the log records (created by loggers) to the appropriate "
|
||
"destination."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:336
|
||
msgid ""
|
||
"Filters provide a finer grained facility for determining which log records "
|
||
"to output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:338
|
||
msgid "Formatters specify the layout of log records in the final output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:340
|
||
msgid ""
|
||
"Log event information is passed between loggers, handlers, filters and "
|
||
"formatters in a :class:`LogRecord` instance."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:343
|
||
msgid ""
|
||
"Logging is performed by calling methods on instances of the :class:`Logger` "
|
||
"class (hereafter called :dfn:`loggers`). Each instance has a name, and they "
|
||
"are conceptually arranged in a namespace hierarchy using dots (periods) as "
|
||
"separators. For example, a logger named 'scan' is the parent of loggers "
|
||
"'scan.text', 'scan.html' and 'scan.pdf'. Logger names can be anything you "
|
||
"want, and indicate the area of an application in which a logged message "
|
||
"originates."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:350
|
||
msgid ""
|
||
"A good convention to use when naming loggers is to use a module-level "
|
||
"logger, in each module which uses logging, named as follows::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:355
|
||
msgid ""
|
||
"This means that logger names track the package/module hierarchy, and it's "
|
||
"intuitively obvious where events are logged just from the logger name."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:358
|
||
msgid ""
|
||
"The root of the hierarchy of loggers is called the root logger. That's the "
|
||
"logger used by the functions :func:`debug`, :func:`info`, :func:`warning`, :"
|
||
"func:`error` and :func:`critical`, which just call the same-named method of "
|
||
"the root logger. The functions and the methods have the same signatures. The "
|
||
"root logger's name is printed as 'root' in the logged output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:364
|
||
msgid ""
|
||
"It is, of course, possible to log messages to different destinations. "
|
||
"Support is included in the package for writing log messages to files, HTTP "
|
||
"GET/POST locations, email via SMTP, generic sockets, queues, or OS-specific "
|
||
"logging mechanisms such as syslog or the Windows NT event log. Destinations "
|
||
"are served by :dfn:`handler` classes. You can create your own log "
|
||
"destination class if you have special requirements not met by any of the "
|
||
"built-in handler classes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:371
|
||
msgid ""
|
||
"By default, no destination is set for any logging messages. You can specify "
|
||
"a destination (such as console or file) by using :func:`basicConfig` as in "
|
||
"the tutorial examples. If you call the functions :func:`debug`, :func:"
|
||
"`info`, :func:`warning`, :func:`error` and :func:`critical`, they will check "
|
||
"to see if no destination is set; and if one is not set, they will set a "
|
||
"destination of the console (``sys.stderr``) and a default format for the "
|
||
"displayed message before delegating to the root logger to do the actual "
|
||
"message output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:379
|
||
msgid "The default format set by :func:`basicConfig` for messages is::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:383
|
||
msgid ""
|
||
"You can change this by passing a format string to :func:`basicConfig` with "
|
||
"the *format* keyword argument. For all options regarding how a format string "
|
||
"is constructed, see :ref:`formatter-objects`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:388
|
||
msgid "Logging Flow"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:390
|
||
msgid ""
|
||
"The flow of log event information in loggers and handlers is illustrated in "
|
||
"the following diagram."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:396
|
||
msgid "Loggers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:398
|
||
msgid ""
|
||
":class:`Logger` objects have a threefold job. First, they expose several "
|
||
"methods to application code so that applications can log messages at "
|
||
"runtime. Second, logger objects determine which log messages to act upon "
|
||
"based upon severity (the default filtering facility) or filter objects. "
|
||
"Third, logger objects pass along relevant log messages to all interested log "
|
||
"handlers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:404
|
||
msgid ""
|
||
"The most widely used methods on logger objects fall into two categories: "
|
||
"configuration and message sending."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:407
|
||
msgid "These are the most common configuration methods:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:409
|
||
msgid ""
|
||
":meth:`Logger.setLevel` specifies the lowest-severity log message a logger "
|
||
"will handle, where debug is the lowest built-in severity level and critical "
|
||
"is the highest built-in severity. For example, if the severity level is "
|
||
"INFO, the logger will handle only INFO, WARNING, ERROR, and CRITICAL "
|
||
"messages and will ignore DEBUG messages."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:415
|
||
msgid ""
|
||
":meth:`Logger.addHandler` and :meth:`Logger.removeHandler` add and remove "
|
||
"handler objects from the logger object. Handlers are covered in more detail "
|
||
"in :ref:`handler-basic`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:419
|
||
msgid ""
|
||
":meth:`Logger.addFilter` and :meth:`Logger.removeFilter` add and remove "
|
||
"filter objects from the logger object. Filters are covered in more detail "
|
||
"in :ref:`filter`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:423
|
||
msgid ""
|
||
"You don't need to always call these methods on every logger you create. See "
|
||
"the last two paragraphs in this section."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:426
|
||
msgid ""
|
||
"With the logger object configured, the following methods create log messages:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:428
|
||
msgid ""
|
||
":meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`, :meth:"
|
||
"`Logger.error`, and :meth:`Logger.critical` all create log records with a "
|
||
"message and a level that corresponds to their respective method names. The "
|
||
"message is actually a format string, which may contain the standard string "
|
||
"substitution syntax of ``%s``, ``%d``, ``%f``, and so on. The rest of their "
|
||
"arguments is a list of objects that correspond with the substitution fields "
|
||
"in the message. With regard to ``**kwargs``, the logging methods care only "
|
||
"about a keyword of ``exc_info`` and use it to determine whether to log "
|
||
"exception information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:438
|
||
msgid ""
|
||
":meth:`Logger.exception` creates a log message similar to :meth:`Logger."
|
||
"error`. The difference is that :meth:`Logger.exception` dumps a stack trace "
|
||
"along with it. Call this method only from an exception handler."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:442
|
||
msgid ""
|
||
":meth:`Logger.log` takes a log level as an explicit argument. This is a "
|
||
"little more verbose for logging messages than using the log level "
|
||
"convenience methods listed above, but this is how to log at custom log "
|
||
"levels."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:446
|
||
msgid ""
|
||
":func:`getLogger` returns a reference to a logger instance with the "
|
||
"specified name if it is provided, or ``root`` if not. The names are period-"
|
||
"separated hierarchical structures. Multiple calls to :func:`getLogger` with "
|
||
"the same name will return a reference to the same logger object. Loggers "
|
||
"that are further down in the hierarchical list are children of loggers "
|
||
"higher up in the list. For example, given a logger with a name of ``foo``, "
|
||
"loggers with names of ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all "
|
||
"descendants of ``foo``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:454
|
||
msgid ""
|
||
"Loggers have a concept of *effective level*. If a level is not explicitly "
|
||
"set on a logger, the level of its parent is used instead as its effective "
|
||
"level. If the parent has no explicit level set, *its* parent is examined, "
|
||
"and so on - all ancestors are searched until an explicitly set level is "
|
||
"found. The root logger always has an explicit level set (``WARNING`` by "
|
||
"default). When deciding whether to process an event, the effective level of "
|
||
"the logger is used to determine whether the event is passed to the logger's "
|
||
"handlers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:462
|
||
msgid ""
|
||
"Child loggers propagate messages up to the handlers associated with their "
|
||
"ancestor loggers. Because of this, it is unnecessary to define and configure "
|
||
"handlers for all the loggers an application uses. It is sufficient to "
|
||
"configure handlers for a top-level logger and create child loggers as "
|
||
"needed. (You can, however, turn off propagation by setting the *propagate* "
|
||
"attribute of a logger to *False*.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:473
|
||
msgid "Handlers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:475
|
||
msgid ""
|
||
":class:`~logging.Handler` objects are responsible for dispatching the "
|
||
"appropriate log messages (based on the log messages' severity) to the "
|
||
"handler's specified destination. :class:`Logger` objects can add zero or "
|
||
"more handler objects to themselves with an :meth:`~Logger.addHandler` "
|
||
"method. As an example scenario, an application may want to send all log "
|
||
"messages to a log file, all log messages of error or higher to stdout, and "
|
||
"all messages of critical to an email address. This scenario requires three "
|
||
"individual handlers where each handler is responsible for sending messages "
|
||
"of a specific severity to a specific location."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:485
|
||
msgid ""
|
||
"The standard library includes quite a few handler types (see :ref:`useful-"
|
||
"handlers`); the tutorials use mainly :class:`StreamHandler` and :class:"
|
||
"`FileHandler` in its examples."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:489
|
||
msgid ""
|
||
"There are very few methods in a handler for application developers to "
|
||
"concern themselves with. The only handler methods that seem relevant for "
|
||
"application developers who are using the built-in handler objects (that is, "
|
||
"not creating custom handlers) are the following configuration methods:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:494
|
||
msgid ""
|
||
"The :meth:`~Handler.setLevel` method, just as in logger objects, specifies "
|
||
"the lowest severity that will be dispatched to the appropriate destination. "
|
||
"Why are there two :func:`setLevel` methods? The level set in the logger "
|
||
"determines which severity of messages it will pass to its handlers. The "
|
||
"level set in each handler determines which messages that handler will send "
|
||
"on."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:500
|
||
msgid ""
|
||
":meth:`~Handler.setFormatter` selects a Formatter object for this handler to "
|
||
"use."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:503
|
||
msgid ""
|
||
":meth:`~Handler.addFilter` and :meth:`~Handler.removeFilter` respectively "
|
||
"configure and deconfigure filter objects on handlers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:506
|
||
msgid ""
|
||
"Application code should not directly instantiate and use instances of :class:"
|
||
"`Handler`. Instead, the :class:`Handler` class is a base class that defines "
|
||
"the interface that all handlers should have and establishes some default "
|
||
"behavior that child classes can use (or override)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:513
|
||
msgid "Formatters"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:515
|
||
msgid ""
|
||
"Formatter objects configure the final order, structure, and contents of the "
|
||
"log message. Unlike the base :class:`logging.Handler` class, application "
|
||
"code may instantiate formatter classes, although you could likely subclass "
|
||
"the formatter if your application needs special behavior. The constructor "
|
||
"takes three optional arguments -- a message format string, a date format "
|
||
"string and a style indicator."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:524
|
||
msgid ""
|
||
"If there is no message format string, the default is to use the raw "
|
||
"message. If there is no date format string, the default date format is::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:529
|
||
msgid ""
|
||
"with the milliseconds tacked on at the end. The ``style`` is one of `%`, '{' "
|
||
"or '$'. If one of these is not specified, then '%' will be used."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:532
|
||
msgid ""
|
||
"If the ``style`` is '%', the message format string uses ``%(<dictionary "
|
||
"key>)s`` styled string substitution; the possible keys are documented in :"
|
||
"ref:`logrecord-attributes`. If the style is '{', the message format string "
|
||
"is assumed to be compatible with :meth:`str.format` (using keyword "
|
||
"arguments), while if the style is '$' then the message format string should "
|
||
"conform to what is expected by :meth:`string.Template.substitute`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:539
|
||
msgid "Added the ``style`` parameter."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:542
|
||
msgid ""
|
||
"The following message format string will log the time in a human-readable "
|
||
"format, the severity of the message, and the contents of the message, in "
|
||
"that order::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:548
|
||
msgid ""
|
||
"Formatters use a user-configurable function to convert the creation time of "
|
||
"a record to a tuple. By default, :func:`time.localtime` is used; to change "
|
||
"this for a particular formatter instance, set the ``converter`` attribute of "
|
||
"the instance to a function with the same signature as :func:`time.localtime` "
|
||
"or :func:`time.gmtime`. To change it for all formatters, for example if you "
|
||
"want all logging times to be shown in GMT, set the ``converter`` attribute "
|
||
"in the Formatter class (to ``time.gmtime`` for GMT display)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:558
|
||
msgid "Configuring Logging"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:562
|
||
msgid "Programmers can configure logging in three ways:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:564
|
||
msgid ""
|
||
"Creating loggers, handlers, and formatters explicitly using Python code that "
|
||
"calls the configuration methods listed above."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:566
|
||
msgid ""
|
||
"Creating a logging config file and reading it using the :func:`fileConfig` "
|
||
"function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:568
|
||
msgid ""
|
||
"Creating a dictionary of configuration information and passing it to the :"
|
||
"func:`dictConfig` function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:571
|
||
msgid ""
|
||
"For the reference documentation on the last two options, see :ref:`logging-"
|
||
"config-api`. The following example configures a very simple logger, a "
|
||
"console handler, and a simple formatter using Python code::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:601
|
||
msgid ""
|
||
"Running this module from the command line produces the following output:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:612
|
||
msgid ""
|
||
"The following Python module creates a logger, handler, and formatter nearly "
|
||
"identical to those in the example listed above, with the only difference "
|
||
"being the names of the objects::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:631
|
||
msgid "Here is the logging.conf file::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:662
|
||
msgid ""
|
||
"The output is nearly identical to that of the non-config-file-based example:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:673
|
||
msgid ""
|
||
"You can see that the config file approach has a few advantages over the "
|
||
"Python code approach, mainly separation of configuration and code and the "
|
||
"ability of noncoders to easily modify the logging properties."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:677
|
||
msgid ""
|
||
"The :func:`fileConfig` function takes a default parameter, "
|
||
"``disable_existing_loggers``, which defaults to ``True`` for reasons of "
|
||
"backward compatibility. This may or may not be what you want, since it will "
|
||
"cause any loggers existing before the :func:`fileConfig` call to be disabled "
|
||
"unless they (or an ancestor) are explicitly named in the configuration. "
|
||
"Please refer to the reference documentation for more information, and "
|
||
"specify ``False`` for this parameter if you wish."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:685
|
||
msgid ""
|
||
"The dictionary passed to :func:`dictConfig` can also specify a Boolean value "
|
||
"with key ``disable_existing_loggers``, which if not specified explicitly in "
|
||
"the dictionary also defaults to being interpreted as ``True``. This leads "
|
||
"to the logger-disabling behaviour described above, which may not be what you "
|
||
"want - in which case, provide the key explicitly with a value of ``False``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:695
|
||
msgid ""
|
||
"Note that the class names referenced in config files need to be either "
|
||
"relative to the logging module, or absolute values which can be resolved "
|
||
"using normal import mechanisms. Thus, you could use either :class:`~logging."
|
||
"handlers.WatchedFileHandler` (relative to the logging module) or ``mypackage."
|
||
"mymodule.MyHandler`` (for a class defined in package ``mypackage`` and "
|
||
"module ``mymodule``, where ``mypackage`` is available on the Python import "
|
||
"path)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:703
|
||
msgid ""
|
||
"In Python 3.2, a new means of configuring logging has been introduced, using "
|
||
"dictionaries to hold configuration information. This provides a superset of "
|
||
"the functionality of the config-file-based approach outlined above, and is "
|
||
"the recommended configuration method for new applications and deployments. "
|
||
"Because a Python dictionary is used to hold configuration information, and "
|
||
"since you can populate that dictionary using different means, you have more "
|
||
"options for configuration. For example, you can use a configuration file in "
|
||
"JSON format, or, if you have access to YAML processing functionality, a file "
|
||
"in YAML format, to populate the configuration dictionary. Or, of course, you "
|
||
"can construct the dictionary in Python code, receive it in pickled form over "
|
||
"a socket, or use whatever approach makes sense for your application."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:715
|
||
msgid ""
|
||
"Here's an example of the same configuration as above, in YAML format for the "
|
||
"new dictionary-based approach::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:737
|
||
msgid ""
|
||
"For more information about logging using a dictionary, see :ref:`logging-"
|
||
"config-api`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:741
|
||
msgid "What happens if no configuration is provided"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:743
|
||
msgid ""
|
||
"If no logging configuration is provided, it is possible to have a situation "
|
||
"where a logging event needs to be output, but no handlers can be found to "
|
||
"output the event. The behaviour of the logging package in these "
|
||
"circumstances is dependent on the Python version."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:748
|
||
msgid "For versions of Python prior to 3.2, the behaviour is as follows:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:750
|
||
msgid ""
|
||
"If *logging.raiseExceptions* is *False* (production mode), the event is "
|
||
"silently dropped."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:753
|
||
msgid ""
|
||
"If *logging.raiseExceptions* is *True* (development mode), a message 'No "
|
||
"handlers could be found for logger X.Y.Z' is printed once."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:756
|
||
msgid "In Python 3.2 and later, the behaviour is as follows:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:758
|
||
msgid ""
|
||
"The event is output using a 'handler of last resort', stored in ``logging."
|
||
"lastResort``. This internal handler is not associated with any logger, and "
|
||
"acts like a :class:`~logging.StreamHandler` which writes the event "
|
||
"description message to the current value of ``sys.stderr`` (therefore "
|
||
"respecting any redirections which may be in effect). No formatting is done "
|
||
"on the message - just the bare event description message is printed. The "
|
||
"handler's level is set to ``WARNING``, so all events at this and greater "
|
||
"severities will be output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:767
|
||
msgid ""
|
||
"To obtain the pre-3.2 behaviour, ``logging.lastResort`` can be set to *None*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:772
|
||
msgid "Configuring Logging for a Library"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:774
|
||
msgid ""
|
||
"When developing a library which uses logging, you should take care to "
|
||
"document how the library uses logging - for example, the names of loggers "
|
||
"used. Some consideration also needs to be given to its logging "
|
||
"configuration. If the using application does not use logging, and library "
|
||
"code makes logging calls, then (as described in the previous section) events "
|
||
"of severity ``WARNING`` and greater will be printed to ``sys.stderr``. This "
|
||
"is regarded as the best default behaviour."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:782
|
||
msgid ""
|
||
"If for some reason you *don't* want these messages printed in the absence of "
|
||
"any logging configuration, you can attach a do-nothing handler to the top-"
|
||
"level logger for your library. This avoids the message being printed, since "
|
||
"a handler will be always be found for the library's events: it just doesn't "
|
||
"produce any output. If the library user configures logging for application "
|
||
"use, presumably that configuration will add some handlers, and if levels are "
|
||
"suitably configured then logging calls made in library code will send output "
|
||
"to those handlers, as normal."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:791
|
||
msgid ""
|
||
"A do-nothing handler is included in the logging package: :class:`~logging."
|
||
"NullHandler` (since Python 3.1). An instance of this handler could be added "
|
||
"to the top-level logger of the logging namespace used by the library (*if* "
|
||
"you want to prevent your library's logged events being output to ``sys."
|
||
"stderr`` in the absence of logging configuration). If all logging by a "
|
||
"library *foo* is done using loggers with names matching 'foo.x', 'foo.x.y', "
|
||
"etc. then the code::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:802
|
||
msgid ""
|
||
"should have the desired effect. If an organisation produces a number of "
|
||
"libraries, then the logger name specified can be 'orgname.foo' rather than "
|
||
"just 'foo'."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:806
|
||
msgid ""
|
||
"It is strongly advised that you *do not add any handlers other than* :class:"
|
||
"`~logging.NullHandler` *to your library's loggers*. This is because the "
|
||
"configuration of handlers is the prerogative of the application developer "
|
||
"who uses your library. The application developer knows their target audience "
|
||
"and what handlers are most appropriate for their application: if you add "
|
||
"handlers 'under the hood', you might well interfere with their ability to "
|
||
"carry out unit tests and deliver logs which suit their requirements."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:817
|
||
msgid "Logging Levels"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:819
|
||
msgid ""
|
||
"The numeric values of logging levels are given in the following table. These "
|
||
"are primarily of interest if you want to define your own levels, and need "
|
||
"them to have specific values relative to the predefined levels. If you "
|
||
"define a level with the same numeric value, it overwrites the predefined "
|
||
"value; the predefined name is lost."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:826
|
||
msgid "Numeric value"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:828
|
||
msgid "50"
|
||
msgstr "50"
|
||
|
||
#: ../Doc/howto/logging.rst:830
|
||
msgid "40"
|
||
msgstr "40"
|
||
|
||
#: ../Doc/howto/logging.rst:832
|
||
msgid "30"
|
||
msgstr "30"
|
||
|
||
#: ../Doc/howto/logging.rst:834
|
||
msgid "20"
|
||
msgstr "20"
|
||
|
||
#: ../Doc/howto/logging.rst:836
|
||
msgid "10"
|
||
msgstr "10"
|
||
|
||
#: ../Doc/howto/logging.rst:838
|
||
msgid "``NOTSET``"
|
||
msgstr "``NOTSET``"
|
||
|
||
#: ../Doc/howto/logging.rst:838
|
||
msgid "0"
|
||
msgstr "0"
|
||
|
||
#: ../Doc/howto/logging.rst:841
|
||
msgid ""
|
||
"Levels can also be associated with loggers, being set either by the "
|
||
"developer or through loading a saved logging configuration. When a logging "
|
||
"method is called on a logger, the logger compares its own level with the "
|
||
"level associated with the method call. If the logger's level is higher than "
|
||
"the method call's, no logging message is actually generated. This is the "
|
||
"basic mechanism controlling the verbosity of logging output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:848
|
||
msgid ""
|
||
"Logging messages are encoded as instances of the :class:`~logging.LogRecord` "
|
||
"class. When a logger decides to actually log an event, a :class:`~logging."
|
||
"LogRecord` instance is created from the logging message."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:852
|
||
msgid ""
|
||
"Logging messages are subjected to a dispatch mechanism through the use of :"
|
||
"dfn:`handlers`, which are instances of subclasses of the :class:`Handler` "
|
||
"class. Handlers are responsible for ensuring that a logged message (in the "
|
||
"form of a :class:`LogRecord`) ends up in a particular location (or set of "
|
||
"locations) which is useful for the target audience for that message (such as "
|
||
"end users, support desk staff, system administrators, developers). Handlers "
|
||
"are passed :class:`LogRecord` instances intended for particular "
|
||
"destinations. Each logger can have zero, one or more handlers associated "
|
||
"with it (via the :meth:`~Logger.addHandler` method of :class:`Logger`). In "
|
||
"addition to any handlers directly associated with a logger, *all handlers "
|
||
"associated with all ancestors of the logger* are called to dispatch the "
|
||
"message (unless the *propagate* flag for a logger is set to a false value, "
|
||
"at which point the passing to ancestor handlers stops)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:866
|
||
msgid ""
|
||
"Just as for loggers, handlers can have levels associated with them. A "
|
||
"handler's level acts as a filter in the same way as a logger's level does. "
|
||
"If a handler decides to actually dispatch an event, the :meth:`~Handler."
|
||
"emit` method is used to send the message to its destination. Most user-"
|
||
"defined subclasses of :class:`Handler` will need to override this :meth:"
|
||
"`~Handler.emit`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:875
|
||
msgid "Custom Levels"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:877
|
||
msgid ""
|
||
"Defining your own levels is possible, but should not be necessary, as the "
|
||
"existing levels have been chosen on the basis of practical experience. "
|
||
"However, if you are convinced that you need custom levels, great care should "
|
||
"be exercised when doing this, and it is possibly *a very bad idea to define "
|
||
"custom levels if you are developing a library*. That's because if multiple "
|
||
"library authors all define their own custom levels, there is a chance that "
|
||
"the logging output from such multiple libraries used together will be "
|
||
"difficult for the using developer to control and/or interpret, because a "
|
||
"given numeric value might mean different things for different libraries."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:890
|
||
msgid "Useful Handlers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:892
|
||
msgid ""
|
||
"In addition to the base :class:`Handler` class, many useful subclasses are "
|
||
"provided:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:895
|
||
msgid ""
|
||
":class:`StreamHandler` instances send messages to streams (file-like "
|
||
"objects)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:898
|
||
msgid ":class:`FileHandler` instances send messages to disk files."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:900
|
||
msgid ""
|
||
":class:`~handlers.BaseRotatingHandler` is the base class for handlers that "
|
||
"rotate log files at a certain point. It is not meant to be instantiated "
|
||
"directly. Instead, use :class:`~handlers.RotatingFileHandler` or :class:"
|
||
"`~handlers.TimedRotatingFileHandler`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:905
|
||
msgid ""
|
||
":class:`~handlers.RotatingFileHandler` instances send messages to disk "
|
||
"files, with support for maximum log file sizes and log file rotation."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:908
|
||
msgid ""
|
||
":class:`~handlers.TimedRotatingFileHandler` instances send messages to disk "
|
||
"files, rotating the log file at certain timed intervals."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:911
|
||
msgid ""
|
||
":class:`~handlers.SocketHandler` instances send messages to TCP/IP sockets. "
|
||
"Since 3.4, Unix domain sockets are also supported."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:914
|
||
msgid ""
|
||
":class:`~handlers.DatagramHandler` instances send messages to UDP sockets. "
|
||
"Since 3.4, Unix domain sockets are also supported."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:917
|
||
msgid ""
|
||
":class:`~handlers.SMTPHandler` instances send messages to a designated email "
|
||
"address."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:920
|
||
msgid ""
|
||
":class:`~handlers.SysLogHandler` instances send messages to a Unix syslog "
|
||
"daemon, possibly on a remote machine."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:923
|
||
msgid ""
|
||
":class:`~handlers.NTEventLogHandler` instances send messages to a Windows "
|
||
"NT/2000/XP event log."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:926
|
||
msgid ""
|
||
":class:`~handlers.MemoryHandler` instances send messages to a buffer in "
|
||
"memory, which is flushed whenever specific criteria are met."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:929
|
||
msgid ""
|
||
":class:`~handlers.HTTPHandler` instances send messages to an HTTP server "
|
||
"using either ``GET`` or ``POST`` semantics."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:932
|
||
msgid ""
|
||
":class:`~handlers.WatchedFileHandler` instances watch the file they are "
|
||
"logging to. If the file changes, it is closed and reopened using the file "
|
||
"name. This handler is only useful on Unix-like systems; Windows does not "
|
||
"support the underlying mechanism used."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:937
|
||
msgid ""
|
||
":class:`~handlers.QueueHandler` instances send messages to a queue, such as "
|
||
"those implemented in the :mod:`queue` or :mod:`multiprocessing` modules."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:940
|
||
msgid ""
|
||
":class:`NullHandler` instances do nothing with error messages. They are used "
|
||
"by library developers who want to use logging, but want to avoid the 'No "
|
||
"handlers could be found for logger XXX' message which can be displayed if "
|
||
"the library user has not configured logging. See :ref:`library-config` for "
|
||
"more information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:946
|
||
msgid "The :class:`NullHandler` class."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:949
|
||
msgid "The :class:`~handlers.QueueHandler` class."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:952
|
||
msgid ""
|
||
"The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler` "
|
||
"classes are defined in the core logging package. The other handlers are "
|
||
"defined in a sub- module, :mod:`logging.handlers`. (There is also another "
|
||
"sub-module, :mod:`logging.config`, for configuration functionality.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:957
|
||
msgid ""
|
||
"Logged messages are formatted for presentation through instances of the :"
|
||
"class:`Formatter` class. They are initialized with a format string suitable "
|
||
"for use with the % operator and a dictionary."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:961
|
||
msgid ""
|
||
"For formatting multiple messages in a batch, instances of :class:`~handlers."
|
||
"BufferingFormatter` can be used. In addition to the format string (which is "
|
||
"applied to each message in the batch), there is provision for header and "
|
||
"trailer format strings."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:966
|
||
msgid ""
|
||
"When filtering based on logger level and/or handler level is not enough, "
|
||
"instances of :class:`Filter` can be added to both :class:`Logger` and :class:"
|
||
"`Handler` instances (through their :meth:`~Handler.addFilter` method). "
|
||
"Before deciding to process a message further, both loggers and handlers "
|
||
"consult all their filters for permission. If any filter returns a false "
|
||
"value, the message is not processed further."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:973
|
||
msgid ""
|
||
"The basic :class:`Filter` functionality allows filtering by specific logger "
|
||
"name. If this feature is used, messages sent to the named logger and its "
|
||
"children are allowed through the filter, and all others dropped."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:981
|
||
msgid "Exceptions raised during logging"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:983
|
||
msgid ""
|
||
"The logging package is designed to swallow exceptions which occur while "
|
||
"logging in production. This is so that errors which occur while handling "
|
||
"logging events - such as logging misconfiguration, network or other similar "
|
||
"errors - do not cause the application using logging to terminate prematurely."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:988
|
||
msgid ""
|
||
":class:`SystemExit` and :class:`KeyboardInterrupt` exceptions are never "
|
||
"swallowed. Other exceptions which occur during the :meth:`~Handler.emit` "
|
||
"method of a :class:`Handler` subclass are passed to its :meth:`~Handler."
|
||
"handleError` method."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:993
|
||
msgid ""
|
||
"The default implementation of :meth:`~Handler.handleError` in :class:"
|
||
"`Handler` checks to see if a module-level variable, :data:`raiseExceptions`, "
|
||
"is set. If set, a traceback is printed to :data:`sys.stderr`. If not set, "
|
||
"the exception is swallowed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:998
|
||
msgid ""
|
||
"The default value of :data:`raiseExceptions` is ``True``. This is because "
|
||
"during development, you typically want to be notified of any exceptions that "
|
||
"occur. It's advised that you set :data:`raiseExceptions` to ``False`` for "
|
||
"production usage."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1008
|
||
msgid "Using arbitrary objects as messages"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1010
|
||
msgid ""
|
||
"In the preceding sections and examples, it has been assumed that the message "
|
||
"passed when logging the event is a string. However, this is not the only "
|
||
"possibility. You can pass an arbitrary object as a message, and its :meth:"
|
||
"`~object.__str__` method will be called when the logging system needs to "
|
||
"convert it to a string representation. In fact, if you want to, you can "
|
||
"avoid computing a string representation altogether - for example, the :class:"
|
||
"`~handlers.SocketHandler` emits an event by pickling it and sending it over "
|
||
"the wire."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1021
|
||
msgid "Optimization"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1023
|
||
msgid ""
|
||
"Formatting of message arguments is deferred until it cannot be avoided. "
|
||
"However, computing the arguments passed to the logging method can also be "
|
||
"expensive, and you may want to avoid doing it if the logger will just throw "
|
||
"away your event. To decide what to do, you can call the :meth:`~Logger."
|
||
"isEnabledFor` method which takes a level argument and returns true if the "
|
||
"event would be created by the Logger for that level of call. You can write "
|
||
"code like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1035
|
||
msgid ""
|
||
"so that if the logger's threshold is set above ``DEBUG``, the calls to :func:"
|
||
"`expensive_func1` and :func:`expensive_func2` are never made."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1038
|
||
msgid ""
|
||
"In some cases, :meth:`~Logger.isEnabledFor` can itself be more expensive "
|
||
"than you'd like (e.g. for deeply nested loggers where an explicit level is "
|
||
"only set high up in the logger hierarchy). In such cases (or if you want to "
|
||
"avoid calling a method in tight loops), you can cache the result of a call "
|
||
"to :meth:`~Logger.isEnabledFor` in a local or instance variable, and use "
|
||
"that instead of calling the method each time. Such a cached value would only "
|
||
"need to be recomputed when the logging configuration changes dynamically "
|
||
"while the application is running (which is not all that common)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1047
|
||
msgid ""
|
||
"There are other optimizations which can be made for specific applications "
|
||
"which need more precise control over what logging information is collected. "
|
||
"Here's a list of things you can do to avoid processing during logging which "
|
||
"you don't need:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1053
|
||
msgid "What you don't want to collect"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1053
|
||
msgid "How to avoid collecting it"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1055
|
||
msgid "Information about where calls were made from."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1055
|
||
msgid ""
|
||
"Set ``logging._srcfile`` to ``None``. This avoids calling :func:`sys."
|
||
"_getframe`, which may help to speed up your code in environments like PyPy "
|
||
"(which can't speed up code that uses :func:`sys._getframe`), if and when "
|
||
"PyPy supports Python 3.x."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1063
|
||
msgid "Threading information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1063
|
||
msgid "Set ``logging.logThreads`` to ``0``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1065
|
||
msgid "Process information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1065
|
||
msgid "Set ``logging.logProcesses`` to ``0``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1068
|
||
msgid ""
|
||
"Also note that the core logging module only includes the basic handlers. If "
|
||
"you don't import :mod:`logging.handlers` and :mod:`logging.config`, they "
|
||
"won't take up any memory."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1075 ../Doc/howto/logging-cookbook.rst:1306
|
||
msgid "Module :mod:`logging`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1075 ../Doc/howto/logging-cookbook.rst:1306
|
||
msgid "API reference for the logging module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1078 ../Doc/howto/logging-cookbook.rst:1309
|
||
msgid "Module :mod:`logging.config`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1078 ../Doc/howto/logging-cookbook.rst:1309
|
||
msgid "Configuration API for the logging module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1081 ../Doc/howto/logging-cookbook.rst:1312
|
||
msgid "Module :mod:`logging.handlers`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1081 ../Doc/howto/logging-cookbook.rst:1312
|
||
msgid "Useful handlers included with the logging module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1083
|
||
msgid ":ref:`A logging cookbook <logging-cookbook>`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:5
|
||
msgid "Logging Cookbook"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:9
|
||
msgid ""
|
||
"This page contains a number of recipes related to logging, which have been "
|
||
"found useful in the past."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:15
|
||
msgid "Using logging in multiple modules"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:17
|
||
msgid ""
|
||
"Multiple calls to ``logging.getLogger('someLogger')`` return a reference to "
|
||
"the same logger object. This is true not only within the same module, but "
|
||
"also across modules as long as it is in the same Python interpreter "
|
||
"process. It is true for references to the same object; additionally, "
|
||
"application code can define and configure a parent logger in one module and "
|
||
"create (but not configure) a child logger in a separate module, and all "
|
||
"logger calls to the child will pass up to the parent. Here is a main "
|
||
"module::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:55
|
||
msgid "Here is the auxiliary module::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:99
|
||
msgid "Logging from multiple threads"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:101
|
||
msgid ""
|
||
"Logging from multiple threads requires no special effort. The following "
|
||
"example shows logging from the main (initial) thread and another thread::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:130
|
||
msgid "When run, the script should print something like the following::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:150
|
||
msgid ""
|
||
"This shows the logging output interspersed as one might expect. This "
|
||
"approach works for more threads than shown here, of course."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:154
|
||
msgid "Multiple handlers and formatters"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:156
|
||
msgid ""
|
||
"Loggers are plain Python objects. The :meth:`~Logger.addHandler` method has "
|
||
"no minimum or maximum quota for the number of handlers you may add. "
|
||
"Sometimes it will be beneficial for an application to log all messages of "
|
||
"all severities to a text file while simultaneously logging errors or above "
|
||
"to the console. To set this up, simply configure the appropriate handlers. "
|
||
"The logging calls in the application code will remain unchanged. Here is a "
|
||
"slight modification to the previous simple module-based configuration "
|
||
"example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:189
|
||
msgid ""
|
||
"Notice that the 'application' code does not care about multiple handlers. "
|
||
"All that changed was the addition and configuration of a new handler named "
|
||
"*fh*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:192
|
||
msgid ""
|
||
"The ability to create new handlers with higher- or lower-severity filters "
|
||
"can be very helpful when writing and testing an application. Instead of "
|
||
"using many ``print`` statements for debugging, use ``logger.debug``: Unlike "
|
||
"the print statements, which you will have to delete or comment out later, "
|
||
"the logger.debug statements can remain intact in the source code and remain "
|
||
"dormant until you need them again. At that time, the only change that needs "
|
||
"to happen is to modify the severity level of the logger and/or handler to "
|
||
"debug."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:203
|
||
msgid "Logging to multiple destinations"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:205
|
||
msgid ""
|
||
"Let's say you want to log to console and file with different message formats "
|
||
"and in differing circumstances. Say you want to log messages with levels of "
|
||
"DEBUG and higher to file, and those messages at level INFO and higher to the "
|
||
"console. Let's also assume that the file should contain timestamps, but the "
|
||
"console messages should not. Here's how you can achieve this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:243
|
||
msgid "When you run this, on the console you will see ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:250
|
||
msgid "and in the file you will see something like ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:258
|
||
msgid ""
|
||
"As you can see, the DEBUG message only shows up in the file. The other "
|
||
"messages are sent to both destinations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:261
|
||
msgid ""
|
||
"This example uses console and file handlers, but you can use any number and "
|
||
"combination of handlers you choose."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:266
|
||
msgid "Configuration server example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:268
|
||
msgid "Here is an example of a module using the logging configuration server::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:299
|
||
msgid ""
|
||
"And here is a script that takes a filename and sends that file to the "
|
||
"server, properly preceded with the binary-encoded length, as the new logging "
|
||
"configuration::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:322
|
||
msgid "Dealing with handlers that block"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:326
|
||
msgid ""
|
||
"Sometimes you have to get your logging handlers to do their work without "
|
||
"blocking the thread you're logging from. This is common in Web applications, "
|
||
"though of course it also occurs in other scenarios."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:330
|
||
msgid ""
|
||
"A common culprit which demonstrates sluggish behaviour is the :class:"
|
||
"`SMTPHandler`: sending emails can take a long time, for a number of reasons "
|
||
"outside the developer's control (for example, a poorly performing mail or "
|
||
"network infrastructure). But almost any network-based handler can block: "
|
||
"Even a :class:`SocketHandler` operation may do a DNS query under the hood "
|
||
"which is too slow (and this query can be deep in the socket library code, "
|
||
"below the Python layer, and outside your control)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:338
|
||
msgid ""
|
||
"One solution is to use a two-part approach. For the first part, attach only "
|
||
"a :class:`QueueHandler` to those loggers which are accessed from performance-"
|
||
"critical threads. They simply write to their queue, which can be sized to a "
|
||
"large enough capacity or initialized with no upper bound to their size. The "
|
||
"write to the queue will typically be accepted quickly, though you will "
|
||
"probably need to catch the :exc:`queue.Full` exception as a precaution in "
|
||
"your code. If you are a library developer who has performance-critical "
|
||
"threads in their code, be sure to document this (together with a suggestion "
|
||
"to attach only ``QueueHandlers`` to your loggers) for the benefit of other "
|
||
"developers who will use your code."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:349
|
||
msgid ""
|
||
"The second part of the solution is :class:`QueueListener`, which has been "
|
||
"designed as the counterpart to :class:`QueueHandler`. A :class:"
|
||
"`QueueListener` is very simple: it's passed a queue and some handlers, and "
|
||
"it fires up an internal thread which listens to its queue for LogRecords "
|
||
"sent from ``QueueHandlers`` (or any other source of ``LogRecords``, for that "
|
||
"matter). The ``LogRecords`` are removed from the queue and passed to the "
|
||
"handlers for processing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:357
|
||
msgid ""
|
||
"The advantage of having a separate :class:`QueueListener` class is that you "
|
||
"can use the same instance to service multiple ``QueueHandlers``. This is "
|
||
"more resource-friendly than, say, having threaded versions of the existing "
|
||
"handler classes, which would eat up one thread per handler for no particular "
|
||
"benefit."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:362
|
||
msgid "An example of using these two classes follows (imports omitted)::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:380
|
||
msgid "which, when run, will produce:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:386
|
||
msgid ""
|
||
"Prior to Python 3.5, the :class:`QueueListener` always passed every message "
|
||
"received from the queue to every handler it was initialized with. (This was "
|
||
"because it was assumed that level filtering was all done on the other side, "
|
||
"where the queue is filled.) From 3.5 onwards, this behaviour can be changed "
|
||
"by passing a keyword argument ``respect_handler_level=True`` to the "
|
||
"listener's constructor. When this is done, the listener compares the level "
|
||
"of each message with the handler's level, and only passes a message to a "
|
||
"handler if it's appropriate to do so."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:399
|
||
msgid "Sending and receiving logging events across a network"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:401
|
||
msgid ""
|
||
"Let's say you want to send logging events across a network, and handle them "
|
||
"at the receiving end. A simple way of doing this is attaching a :class:"
|
||
"`SocketHandler` instance to the root logger at the sending end::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:429
|
||
msgid ""
|
||
"At the receiving end, you can set up a receiver using the :mod:"
|
||
"`socketserver` module. Here is a basic working example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:517
|
||
msgid ""
|
||
"First run the server, and then the client. On the client side, nothing is "
|
||
"printed on the console; on the server side, you should see something like::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:527
|
||
msgid ""
|
||
"Note that there are some security issues with pickle in some scenarios. If "
|
||
"these affect you, you can use an alternative serialization scheme by "
|
||
"overriding the :meth:`~handlers.SocketHandler.makePickle` method and "
|
||
"implementing your alternative there, as well as adapting the above script to "
|
||
"use your alternative serialization."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:537
|
||
msgid "Adding contextual information to your logging output"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:539
|
||
msgid ""
|
||
"Sometimes you want logging output to contain contextual information in "
|
||
"addition to the parameters passed to the logging call. For example, in a "
|
||
"networked application, it may be desirable to log client-specific "
|
||
"information in the log (e.g. remote client's username, or IP address). "
|
||
"Although you could use the *extra* parameter to achieve this, it's not "
|
||
"always convenient to pass the information in this way. While it might be "
|
||
"tempting to create :class:`Logger` instances on a per-connection basis, this "
|
||
"is not a good idea because these instances are not garbage collected. While "
|
||
"this is not a problem in practice, when the number of :class:`Logger` "
|
||
"instances is dependent on the level of granularity you want to use in "
|
||
"logging an application, it could be hard to manage if the number of :class:"
|
||
"`Logger` instances becomes effectively unbounded."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:554
|
||
msgid "Using LoggerAdapters to impart contextual information"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:556
|
||
msgid ""
|
||
"An easy way in which you can pass contextual information to be output along "
|
||
"with logging event information is to use the :class:`LoggerAdapter` class. "
|
||
"This class is designed to look like a :class:`Logger`, so that you can call :"
|
||
"meth:`debug`, :meth:`info`, :meth:`warning`, :meth:`error`, :meth:"
|
||
"`exception`, :meth:`critical` and :meth:`log`. These methods have the same "
|
||
"signatures as their counterparts in :class:`Logger`, so you can use the two "
|
||
"types of instances interchangeably."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:564
|
||
msgid ""
|
||
"When you create an instance of :class:`LoggerAdapter`, you pass it a :class:"
|
||
"`Logger` instance and a dict-like object which contains your contextual "
|
||
"information. When you call one of the logging methods on an instance of :"
|
||
"class:`LoggerAdapter`, it delegates the call to the underlying instance of :"
|
||
"class:`Logger` passed to its constructor, and arranges to pass the "
|
||
"contextual information in the delegated call. Here's a snippet from the code "
|
||
"of :class:`LoggerAdapter`::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:580
|
||
msgid ""
|
||
"The :meth:`~LoggerAdapter.process` method of :class:`LoggerAdapter` is where "
|
||
"the contextual information is added to the logging output. It's passed the "
|
||
"message and keyword arguments of the logging call, and it passes back "
|
||
"(potentially) modified versions of these to use in the call to the "
|
||
"underlying logger. The default implementation of this method leaves the "
|
||
"message alone, but inserts an 'extra' key in the keyword argument whose "
|
||
"value is the dict-like object passed to the constructor. Of course, if you "
|
||
"had passed an 'extra' keyword argument in the call to the adapter, it will "
|
||
"be silently overwritten."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:589
|
||
msgid ""
|
||
"The advantage of using 'extra' is that the values in the dict-like object "
|
||
"are merged into the :class:`LogRecord` instance's __dict__, allowing you to "
|
||
"use customized strings with your :class:`Formatter` instances which know "
|
||
"about the keys of the dict-like object. If you need a different method, e.g. "
|
||
"if you want to prepend or append the contextual information to the message "
|
||
"string, you just need to subclass :class:`LoggerAdapter` and override :meth:"
|
||
"`~LoggerAdapter.process` to do what you need. Here is a simple example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:605
|
||
msgid "which you can use like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:610
|
||
msgid ""
|
||
"Then any events that you log to the adapter will have the value of "
|
||
"``some_conn_id`` prepended to the log messages."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:614
|
||
msgid "Using objects other than dicts to pass contextual information"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:616
|
||
msgid ""
|
||
"You don't need to pass an actual dict to a :class:`LoggerAdapter` - you "
|
||
"could pass an instance of a class which implements ``__getitem__`` and "
|
||
"``__iter__`` so that it looks like a dict to logging. This would be useful "
|
||
"if you want to generate values dynamically (whereas the values in a dict "
|
||
"would be constant)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:625
|
||
msgid "Using Filters to impart contextual information"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:627
|
||
msgid ""
|
||
"You can also add contextual information to log output using a user-defined :"
|
||
"class:`Filter`. ``Filter`` instances are allowed to modify the "
|
||
"``LogRecords`` passed to them, including adding additional attributes which "
|
||
"can then be output using a suitable format string, or if needed a custom :"
|
||
"class:`Formatter`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:632
|
||
msgid ""
|
||
"For example in a web application, the request being processed (or at least, "
|
||
"the interesting parts of it) can be stored in a threadlocal (:class:"
|
||
"`threading.local`) variable, and then accessed from a ``Filter`` to add, "
|
||
"say, information from the request - say, the remote IP address and remote "
|
||
"user's username - to the ``LogRecord``, using the attribute names 'ip' and "
|
||
"'user' as in the ``LoggerAdapter`` example above. In that case, the same "
|
||
"format string can be used to get similar output to that shown above. Here's "
|
||
"an example script::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:678
|
||
msgid "which, when run, produces something like::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:697
|
||
msgid "Logging to a single file from multiple processes"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:699
|
||
msgid ""
|
||
"Although logging is thread-safe, and logging to a single file from multiple "
|
||
"threads in a single process *is* supported, logging to a single file from "
|
||
"*multiple processes* is *not* supported, because there is no standard way to "
|
||
"serialize access to a single file across multiple processes in Python. If "
|
||
"you need to log to a single file from multiple processes, one way of doing "
|
||
"this is to have all the processes log to a :class:`~handlers.SocketHandler`, "
|
||
"and have a separate process which implements a socket server which reads "
|
||
"from the socket and logs to file. (If you prefer, you can dedicate one "
|
||
"thread in one of the existing processes to perform this function.) :ref:"
|
||
"`This section <network-logging>` documents this approach in more detail and "
|
||
"includes a working socket receiver which can be used as a starting point for "
|
||
"you to adapt in your own applications."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:712
|
||
msgid ""
|
||
"If you are using a recent version of Python which includes the :mod:"
|
||
"`multiprocessing` module, you could write your own handler which uses the :"
|
||
"class:`~multiprocessing.Lock` class from this module to serialize access to "
|
||
"the file from your processes. The existing :class:`FileHandler` and "
|
||
"subclasses do not make use of :mod:`multiprocessing` at present, though they "
|
||
"may do so in the future. Note that at present, the :mod:`multiprocessing` "
|
||
"module does not provide working lock functionality on all platforms (see "
|
||
"https://bugs.python.org/issue3770)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:723
|
||
msgid ""
|
||
"Alternatively, you can use a ``Queue`` and a :class:`QueueHandler` to send "
|
||
"all logging events to one of the processes in your multi-process "
|
||
"application. The following example script demonstrates how you can do this; "
|
||
"in the example a separate listener process listens for events sent by other "
|
||
"processes and logs them according to its own logging configuration. Although "
|
||
"the example only demonstrates one way of doing it (for example, you may want "
|
||
"to use a listener thread rather than a separate listener process -- the "
|
||
"implementation would be analogous) it does allow for completely different "
|
||
"logging configurations for the listener and the other processes in your "
|
||
"application, and can be used as the basis for code meeting your own specific "
|
||
"requirements::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:839
|
||
msgid ""
|
||
"A variant of the above script keeps the logging in the main process, in a "
|
||
"separate thread::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:934
|
||
msgid ""
|
||
"This variant shows how you can e.g. apply configuration for particular "
|
||
"loggers - e.g. the ``foo`` logger has a special handler which stores all "
|
||
"events in the ``foo`` subsystem in a file ``mplog-foo.log``. This will be "
|
||
"used by the logging machinery in the main process (even though the logging "
|
||
"events are generated in the worker processes) to direct the messages to the "
|
||
"appropriate destinations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:941
|
||
msgid "Using file rotation"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:946
|
||
msgid ""
|
||
"Sometimes you want to let a log file grow to a certain size, then open a new "
|
||
"file and log to that. You may want to keep a certain number of these files, "
|
||
"and when that many files have been created, rotate the files so that the "
|
||
"number of files and the size of the files both remain bounded. For this "
|
||
"usage pattern, the logging package provides a :class:`~handlers."
|
||
"RotatingFileHandler`::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:978
|
||
msgid ""
|
||
"The result should be 6 separate files, each with part of the log history for "
|
||
"the application::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:988
|
||
msgid ""
|
||
"The most current file is always :file:`logging_rotatingfile_example.out`, "
|
||
"and each time it reaches the size limit it is renamed with the suffix "
|
||
"``.1``. Each of the existing backup files is renamed to increment the suffix "
|
||
"(``.1`` becomes ``.2``, etc.) and the ``.6`` file is erased."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:993
|
||
msgid ""
|
||
"Obviously this example sets the log length much too small as an extreme "
|
||
"example. You would want to set *maxBytes* to an appropriate value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:999
|
||
msgid "Use of alternative formatting styles"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1001
|
||
msgid ""
|
||
"When logging was added to the Python standard library, the only way of "
|
||
"formatting messages with variable content was to use the %-formatting "
|
||
"method. Since then, Python has gained two new formatting approaches: :class:"
|
||
"`string.Template` (added in Python 2.4) and :meth:`str.format` (added in "
|
||
"Python 2.6)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1007
|
||
msgid ""
|
||
"Logging (as of 3.2) provides improved support for these two additional "
|
||
"formatting styles. The :class:`Formatter` class been enhanced to take an "
|
||
"additional, optional keyword parameter named ``style``. This defaults to "
|
||
"``'%'``, but other possible values are ``'{'`` and ``'$'``, which correspond "
|
||
"to the other two formatting styles. Backwards compatibility is maintained by "
|
||
"default (as you would expect), but by explicitly specifying a style "
|
||
"parameter, you get the ability to specify format strings which work with :"
|
||
"meth:`str.format` or :class:`string.Template`. Here's an example console "
|
||
"session to show the possibilities:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1041
|
||
msgid ""
|
||
"Note that the formatting of logging messages for final output to logs is "
|
||
"completely independent of how an individual logging message is constructed. "
|
||
"That can still use %-formatting, as shown here::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1049
|
||
msgid ""
|
||
"Logging calls (``logger.debug()``, ``logger.info()`` etc.) only take "
|
||
"positional parameters for the actual logging message itself, with keyword "
|
||
"parameters used only for determining options for how to handle the actual "
|
||
"logging call (e.g. the ``exc_info`` keyword parameter to indicate that "
|
||
"traceback information should be logged, or the ``extra`` keyword parameter "
|
||
"to indicate additional contextual information to be added to the log). So "
|
||
"you cannot directly make logging calls using :meth:`str.format` or :class:"
|
||
"`string.Template` syntax, because internally the logging package uses %-"
|
||
"formatting to merge the format string and the variable arguments. There "
|
||
"would no changing this while preserving backward compatibility, since all "
|
||
"logging calls which are out there in existing code will be using %-format "
|
||
"strings."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1062
|
||
msgid ""
|
||
"There is, however, a way that you can use {}- and $- formatting to construct "
|
||
"your individual log messages. Recall that for a message you can use an "
|
||
"arbitrary object as a message format string, and that the logging package "
|
||
"will call ``str()`` on that object to get the actual format string. Consider "
|
||
"the following two classes::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1086
|
||
msgid ""
|
||
"Either of these can be used in place of a format string, to allow {}- or $-"
|
||
"formatting to be used to build the actual \"message\" part which appears in "
|
||
"the formatted log output in place of \"%(message)s\" or \"{message}\" or "
|
||
"\"$message\". It's a little unwieldy to use the class names whenever you "
|
||
"want to log something, but it's quite palatable if you use an alias such as "
|
||
"__ (double underscore – not to be confused with _, the single underscore "
|
||
"used as a synonym/alias for :func:`gettext.gettext` or its brethren)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1094
|
||
msgid ""
|
||
"The above classes are not included in Python, though they're easy enough to "
|
||
"copy and paste into your own code. They can be used as follows (assuming "
|
||
"that they're declared in a module called ``wherever``):"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1116
|
||
msgid ""
|
||
"While the above examples use ``print()`` to show how the formatting works, "
|
||
"you would of course use ``logger.debug()`` or similar to actually log using "
|
||
"this approach."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1120
|
||
msgid ""
|
||
"One thing to note is that you pay no significant performance penalty with "
|
||
"this approach: the actual formatting happens not when you make the logging "
|
||
"call, but when (and if) the logged message is actually about to be output to "
|
||
"a log by a handler. So the only slightly unusual thing which might trip you "
|
||
"up is that the parentheses go around the format string and the arguments, "
|
||
"not just the format string. That's because the __ notation is just syntax "
|
||
"sugar for a constructor call to one of the XXXMessage classes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1128
|
||
msgid ""
|
||
"If you prefer, you can use a :class:`LoggerAdapter` to achieve a similar "
|
||
"effect to the above, as in the following example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1159
|
||
msgid ""
|
||
"The above script should log the message ``Hello, world!`` when run with "
|
||
"Python 3.2 or later."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1168
|
||
msgid "Customizing ``LogRecord``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1170
|
||
msgid ""
|
||
"Every logging event is represented by a :class:`LogRecord` instance. When an "
|
||
"event is logged and not filtered out by a logger's level, a :class:"
|
||
"`LogRecord` is created, populated with information about the event and then "
|
||
"passed to the handlers for that logger (and its ancestors, up to and "
|
||
"including the logger where further propagation up the hierarchy is "
|
||
"disabled). Before Python 3.2, there were only two places where this creation "
|
||
"was done:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1177
|
||
msgid ""
|
||
":meth:`Logger.makeRecord`, which is called in the normal process of logging "
|
||
"an event. This invoked :class:`LogRecord` directly to create an instance."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1180
|
||
msgid ""
|
||
":func:`makeLogRecord`, which is called with a dictionary containing "
|
||
"attributes to be added to the LogRecord. This is typically invoked when a "
|
||
"suitable dictionary has been received over the network (e.g. in pickle form "
|
||
"via a :class:`~handlers.SocketHandler`, or in JSON form via an :class:"
|
||
"`~handlers.HTTPHandler`)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1186
|
||
msgid ""
|
||
"This has usually meant that if you need to do anything special with a :class:"
|
||
"`LogRecord`, you've had to do one of the following."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1189
|
||
msgid ""
|
||
"Create your own :class:`Logger` subclass, which overrides :meth:`Logger."
|
||
"makeRecord`, and set it using :func:`~logging.setLoggerClass` before any "
|
||
"loggers that you care about are instantiated."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1192
|
||
msgid ""
|
||
"Add a :class:`Filter` to a logger or handler, which does the necessary "
|
||
"special manipulation you need when its :meth:`~Filter.filter` method is "
|
||
"called."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1196
|
||
msgid ""
|
||
"The first approach would be a little unwieldy in the scenario where (say) "
|
||
"several different libraries wanted to do different things. Each would "
|
||
"attempt to set its own :class:`Logger` subclass, and the one which did this "
|
||
"last would win."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1201
|
||
msgid ""
|
||
"The second approach works reasonably well for many cases, but does not allow "
|
||
"you to e.g. use a specialized subclass of :class:`LogRecord`. Library "
|
||
"developers can set a suitable filter on their loggers, but they would have "
|
||
"to remember to do this every time they introduced a new logger (which they "
|
||
"would do simply by adding new packages or modules and doing ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1209
|
||
msgid ""
|
||
"at module level). It's probably one too many things to think about. "
|
||
"Developers could also add the filter to a :class:`~logging.NullHandler` "
|
||
"attached to their top-level logger, but this would not be invoked if an "
|
||
"application developer attached a handler to a lower-level library logger – "
|
||
"so output from that handler would not reflect the intentions of the library "
|
||
"developer."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1215
|
||
msgid ""
|
||
"In Python 3.2 and later, :class:`~logging.LogRecord` creation is done "
|
||
"through a factory, which you can specify. The factory is just a callable you "
|
||
"can set with :func:`~logging.setLogRecordFactory`, and interrogate with :"
|
||
"func:`~logging.getLogRecordFactory`. The factory is invoked with the same "
|
||
"signature as the :class:`~logging.LogRecord` constructor, as :class:"
|
||
"`LogRecord` is the default setting for the factory."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1222
|
||
msgid ""
|
||
"This approach allows a custom factory to control all aspects of LogRecord "
|
||
"creation. For example, you could return a subclass, or just add some "
|
||
"additional attributes to the record once created, using a pattern similar to "
|
||
"this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1235
|
||
msgid ""
|
||
"This pattern allows different libraries to chain factories together, and as "
|
||
"long as they don't overwrite each other's attributes or unintentionally "
|
||
"overwrite the attributes provided as standard, there should be no surprises. "
|
||
"However, it should be borne in mind that each link in the chain adds run-"
|
||
"time overhead to all logging operations, and the technique should only be "
|
||
"used when the use of a :class:`Filter` does not provide the desired result."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1246
|
||
msgid "Subclassing QueueHandler - a ZeroMQ example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1248
|
||
msgid ""
|
||
"You can use a :class:`QueueHandler` subclass to send messages to other kinds "
|
||
"of queues, for example a ZeroMQ 'publish' socket. In the example below,the "
|
||
"socket is created separately and passed to the handler (as its 'queue')::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1267
|
||
msgid ""
|
||
"Of course there are other ways of organizing this, for example passing in "
|
||
"the data needed by the handler to create the socket::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1286
|
||
msgid "Subclassing QueueListener - a ZeroMQ example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1288
|
||
msgid ""
|
||
"You can also subclass :class:`QueueListener` to get messages from other "
|
||
"kinds of queues, for example a ZeroMQ 'subscribe' socket. Here's an example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1314
|
||
msgid ":ref:`A basic logging tutorial <logging-basic-tutorial>`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1316
|
||
msgid ":ref:`A more advanced logging tutorial <logging-advanced-tutorial>`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1320
|
||
msgid "An example dictionary-based configuration"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1322
|
||
msgid ""
|
||
"Below is an example of a logging configuration dictionary - it's taken from "
|
||
"the `documentation on the Django project <https://docs.djangoproject.com/"
|
||
"en/1.9/topics/logging/#configuring-logging>`_. This dictionary is passed to :"
|
||
"func:`~config.dictConfig` to put the configuration into effect::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1378
|
||
msgid ""
|
||
"For more information about this configuration, you can see the `relevant "
|
||
"section <https://docs.djangoproject.com/en/1.9/topics/logging/#configuring-"
|
||
"logging>`_ of the Django documentation."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1385
|
||
msgid "Using a rotator and namer to customize log rotation processing"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1387
|
||
msgid ""
|
||
"An example of how you can define a namer and rotator is given in the "
|
||
"following snippet, which shows zlib-based compression of the log file::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1405
|
||
msgid ""
|
||
"These are not \"true\" .gz files, as they are bare compressed data, with no "
|
||
"\"container\" such as you’d find in an actual gzip file. This snippet is "
|
||
"just for illustration purposes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1410
|
||
msgid "A more elaborate multiprocessing example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1412
|
||
msgid ""
|
||
"The following working example shows how logging can be used with "
|
||
"multiprocessing using configuration files. The configurations are fairly "
|
||
"simple, but serve to illustrate how more complex ones could be implemented "
|
||
"in a real multiprocessing scenario."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1417
|
||
msgid ""
|
||
"In the example, the main process spawns a listener process and some worker "
|
||
"processes. Each of the main process, the listener and the workers have three "
|
||
"separate configurations (the workers all share the same configuration). We "
|
||
"can see logging in the main process, how the workers log to a QueueHandler "
|
||
"and how the listener implements a QueueListener and a more complex logging "
|
||
"configuration, and arranges to dispatch events received via the queue to the "
|
||
"handlers specified in the configuration. Note that these configurations are "
|
||
"purely illustrative, but you should be able to adapt this example to your "
|
||
"own scenario."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1427
|
||
msgid ""
|
||
"Here's the script - the docstrings and the comments hopefully explain how it "
|
||
"works::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1639
|
||
msgid "Inserting a BOM into messages sent to a SysLogHandler"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1641
|
||
msgid ""
|
||
"`RFC 5424 <https://tools.ietf.org/html/rfc5424>`_ requires that a Unicode "
|
||
"message be sent to a syslog daemon as a set of bytes which have the "
|
||
"following structure: an optional pure-ASCII component, followed by a UTF-8 "
|
||
"Byte Order Mark (BOM), followed by Unicode encoded using UTF-8. (See the "
|
||
"`relevant section of the specification <https://tools.ietf.org/html/"
|
||
"rfc5424#section-6>`_.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1647
|
||
msgid ""
|
||
"In Python 3.1, code was added to :class:`~logging.handlers.SysLogHandler` to "
|
||
"insert a BOM into the message, but unfortunately, it was implemented "
|
||
"incorrectly, with the BOM appearing at the beginning of the message and "
|
||
"hence not allowing any pure-ASCII component to appear before it."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1653
|
||
msgid ""
|
||
"As this behaviour is broken, the incorrect BOM insertion code is being "
|
||
"removed from Python 3.2.4 and later. However, it is not being replaced, and "
|
||
"if you want to produce RFC 5424-compliant messages which include a BOM, an "
|
||
"optional pure-ASCII sequence before it and arbitrary Unicode after it, "
|
||
"encoded using UTF-8, then you need to do the following:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1659
|
||
msgid ""
|
||
"Attach a :class:`~logging.Formatter` instance to your :class:`~logging."
|
||
"handlers.SysLogHandler` instance, with a format string such as::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1665
|
||
msgid ""
|
||
"The Unicode code point U+FEFF, when encoded using UTF-8, will be encoded as "
|
||
"a UTF-8 BOM -- the byte-string ``b'\\xef\\xbb\\xbf'``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1668
|
||
msgid ""
|
||
"Replace the ASCII section with whatever placeholders you like, but make sure "
|
||
"that the data that appears in there after substitution is always ASCII (that "
|
||
"way, it will remain unchanged after UTF-8 encoding)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1672
|
||
msgid ""
|
||
"Replace the Unicode section with whatever placeholders you like; if the data "
|
||
"which appears there after substitution contains characters outside the ASCII "
|
||
"range, that's fine -- it will be encoded using UTF-8."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1676
|
||
msgid ""
|
||
"The formatted message *will* be encoded using UTF-8 encoding by "
|
||
"``SysLogHandler``. If you follow the above rules, you should be able to "
|
||
"produce RFC 5424-compliant messages. If you don't, logging may not complain, "
|
||
"but your messages will not be RFC 5424-compliant, and your syslog daemon may "
|
||
"complain."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1683
|
||
msgid "Implementing structured logging"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1685
|
||
msgid ""
|
||
"Although most logging messages are intended for reading by humans, and thus "
|
||
"not readily machine-parseable, there might be cirumstances where you want to "
|
||
"output messages in a structured format which *is* capable of being parsed by "
|
||
"a program (without needing complex regular expressions to parse the log "
|
||
"message). This is straightforward to achieve using the logging package. "
|
||
"There are a number of ways in which this could be achieved, but the "
|
||
"following is a simple approach which uses JSON to serialise the event in a "
|
||
"machine-parseable manner::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1709
|
||
msgid "If the above script is run, it prints::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1713
|
||
#: ../Doc/howto/logging-cookbook.rst:1760
|
||
msgid ""
|
||
"Note that the order of items might be different according to the version of "
|
||
"Python used."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1716
|
||
msgid ""
|
||
"If you need more specialised processing, you can use a custom JSON encoder, "
|
||
"as in the following complete example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1756
|
||
msgid "When the above script is run, it prints::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1769
|
||
msgid "Customizing handlers with :func:`dictConfig`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1771
|
||
msgid ""
|
||
"There are times when you want to customize logging handlers in particular "
|
||
"ways, and if you use :func:`dictConfig` you may be able to do this without "
|
||
"subclassing. As an example, consider that you may want to set the ownership "
|
||
"of a log file. On POSIX, this is easily done using :func:`shutil.chown`, but "
|
||
"the file handlers in the stdlib don't offer built-in support. You can "
|
||
"customize handler creation using a plain function such as::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1785
|
||
msgid ""
|
||
"You can then specify, in a logging configuration passed to :func:"
|
||
"`dictConfig`, that a logging handler be created by calling this function::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1818
|
||
msgid ""
|
||
"In this example I am setting the ownership using the ``pulse`` user and "
|
||
"group, just for the purposes of illustration. Putting it together into a "
|
||
"working script, ``chowntest.py``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1865
|
||
msgid "To run this, you will probably need to run as ``root``:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1875
|
||
msgid ""
|
||
"Note that this example uses Python 3.3 because that's where :func:`shutil."
|
||
"chown` makes an appearance. This approach should work with any Python "
|
||
"version that supports :func:`dictConfig` - namely, Python 2.7, 3.2 or later. "
|
||
"With pre-3.3 versions, you would need to implement the actual ownership "
|
||
"change using e.g. :func:`os.chown`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1881
|
||
msgid ""
|
||
"In practice, the handler-creating function may be in a utility module "
|
||
"somewhere in your project. Instead of the line in the configuration::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1886
|
||
msgid "you could use e.g.::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1890
|
||
msgid ""
|
||
"where ``project.util`` can be replaced with the actual name of the package "
|
||
"where the function resides. In the above working script, using ``'ext://"
|
||
"__main__.owned_file_handler'`` should work. Here, the actual callable is "
|
||
"resolved by :func:`dictConfig` from the ``ext://`` specification."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1895
|
||
msgid ""
|
||
"This example hopefully also points the way to how you could implement other "
|
||
"types of file change - e.g. setting specific POSIX permission bits - in the "
|
||
"same way, using :func:`os.chmod`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1899
|
||
msgid ""
|
||
"Of course, the approach could also be extended to types of handler other "
|
||
"than a :class:`~logging.FileHandler` - for example, one of the rotating file "
|
||
"handlers, or a different type of handler altogether."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1909
|
||
msgid "Using particular formatting styles throughout your application"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1911
|
||
msgid ""
|
||
"In Python 3.2, the :class:`~logging.Formatter` gained a ``style`` keyword "
|
||
"parameter which, while defaulting to ``%`` for backward compatibility, "
|
||
"allowed the specification of ``{`` or ``$`` to support the formatting "
|
||
"approaches supported by :meth:`str.format` and :class:`string.Template`. "
|
||
"Note that this governs the formatting of logging messages for final output "
|
||
"to logs, and is completely orthogonal to how an individual logging message "
|
||
"is constructed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1918
|
||
msgid ""
|
||
"Logging calls (:meth:`~Logger.debug`, :meth:`~Logger.info` etc.) only take "
|
||
"positional parameters for the actual logging message itself, with keyword "
|
||
"parameters used only for determining options for how to handle the logging "
|
||
"call (e.g. the ``exc_info`` keyword parameter to indicate that traceback "
|
||
"information should be logged, or the ``extra`` keyword parameter to indicate "
|
||
"additional contextual information to be added to the log). So you cannot "
|
||
"directly make logging calls using :meth:`str.format` or :class:`string."
|
||
"Template` syntax, because internally the logging package uses %-formatting "
|
||
"to merge the format string and the variable arguments. There would no "
|
||
"changing this while preserving backward compatibility, since all logging "
|
||
"calls which are out there in existing code will be using %-format strings."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1930
|
||
msgid ""
|
||
"There have been suggestions to associate format styles with specific "
|
||
"loggers, but that approach also runs into backward compatibility problems "
|
||
"because any existing code could be using a given logger name and using %-"
|
||
"formatting."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1934
|
||
msgid ""
|
||
"For logging to work interoperably between any third-party libraries and your "
|
||
"code, decisions about formatting need to be made at the level of the "
|
||
"individual logging call. This opens up a couple of ways in which alternative "
|
||
"formatting styles can be accommodated."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1941
|
||
msgid "Using LogRecord factories"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1943
|
||
msgid ""
|
||
"In Python 3.2, along with the :class:`~logging.Formatter` changes mentioned "
|
||
"above, the logging package gained the ability to allow users to set their "
|
||
"own :class:`LogRecord` subclasses, using the :func:`setLogRecordFactory` "
|
||
"function. You can use this to set your own subclass of :class:`LogRecord`, "
|
||
"which does the Right Thing by overriding the :meth:`~LogRecord.getMessage` "
|
||
"method. The base class implementation of this method is where the ``msg % "
|
||
"args`` formatting happens, and where you can substitute your alternate "
|
||
"formatting; however, you should be careful to support all formatting styles "
|
||
"and allow %-formatting as the default, to ensure interoperability with other "
|
||
"code. Care should also be taken to call ``str(self.msg)``, just as the base "
|
||
"implementation does."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1954
|
||
msgid ""
|
||
"Refer to the reference documentation on :func:`setLogRecordFactory` and :"
|
||
"class:`LogRecord` for more information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1959
|
||
msgid "Using custom message objects"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1961
|
||
msgid ""
|
||
"There is another, perhaps simpler way that you can use {}- and $- formatting "
|
||
"to construct your individual log messages. You may recall (from :ref:"
|
||
"`arbitrary-object-messages`) that when logging you can use an arbitrary "
|
||
"object as a message format string, and that the logging package will call :"
|
||
"func:`str` on that object to get the actual format string. Consider the "
|
||
"following two classes::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1986
|
||
msgid ""
|
||
"Either of these can be used in place of a format string, to allow {}- or $-"
|
||
"formatting to be used to build the actual \"message\" part which appears in "
|
||
"the formatted log output in place of “%(message)s” or “{message}” or "
|
||
"“$message”. If you find it a little unwieldy to use the class names whenever "
|
||
"you want to log something, you can make it more palatable if you use an "
|
||
"alias such as ``M`` or ``_`` for the message (or perhaps ``__``, if you are "
|
||
"using ``_`` for localization)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1994
|
||
msgid ""
|
||
"Examples of this approach are given below. Firstly, formatting with :meth:"
|
||
"`str.format`::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2008
|
||
msgid "Secondly, formatting with :class:`string.Template`::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2015
|
||
msgid ""
|
||
"One thing to note is that you pay no significant performance penalty with "
|
||
"this approach: the actual formatting happens not when you make the logging "
|
||
"call, but when (and if) the logged message is actually about to be output to "
|
||
"a log by a handler. So the only slightly unusual thing which might trip you "
|
||
"up is that the parentheses go around the format string and the arguments, "
|
||
"not just the format string. That’s because the __ notation is just syntax "
|
||
"sugar for a constructor call to one of the ``XXXMessage`` classes shown "
|
||
"above."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2029
|
||
msgid "Configuring filters with :func:`dictConfig`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2031
|
||
msgid ""
|
||
"You *can* configure filters using :func:`~logging.config.dictConfig`, though "
|
||
"it might not be obvious at first glance how to do it (hence this recipe). "
|
||
"Since :class:`~logging.Filter` is the only filter class included in the "
|
||
"standard library, and it is unlikely to cater to many requirements (it's "
|
||
"only there as a base class), you will typically need to define your own :"
|
||
"class:`~logging.Filter` subclass with an overridden :meth:`~logging.Filter."
|
||
"filter` method. To do this, specify the ``()`` key in the configuration "
|
||
"dictionary for the filter, specifying a callable which will be used to "
|
||
"create the filter (a class is the most obvious, but you can provide any "
|
||
"callable which returns a :class:`~logging.Filter` instance). Here is a "
|
||
"complete example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2084
|
||
msgid ""
|
||
"This example shows how you can pass configuration data to the callable which "
|
||
"constructs the instance, in the form of keyword parameters. When run, the "
|
||
"above script will print::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2090
|
||
msgid "which shows that the filter is working as configured."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2092
|
||
msgid "A couple of extra points to note:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2094
|
||
msgid ""
|
||
"If you can't refer to the callable directly in the configuration (e.g. if it "
|
||
"lives in a different module, and you can't import it directly where the "
|
||
"configuration dictionary is), you can use the form ``ext://...`` as "
|
||
"described in :ref:`logging-config-dict-externalobj`. For example, you could "
|
||
"have used the text ``'ext://__main__.MyFilter'`` instead of ``MyFilter`` in "
|
||
"the above example."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2101
|
||
msgid ""
|
||
"As well as for filters, this technique can also be used to configure custom "
|
||
"handlers and formatters. See :ref:`logging-config-dict-userdef` for more "
|
||
"information on how logging supports using user-defined objects in its "
|
||
"configuration, and see the other cookbook recipe :ref:`custom-handlers` "
|
||
"above."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2110
|
||
msgid "Customized exception formatting"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2112
|
||
msgid ""
|
||
"There might be times when you want to do customized exception formatting - "
|
||
"for argument's sake, let's say you want exactly one line per logged event, "
|
||
"even when exception information is present. You can do this with a custom "
|
||
"formatter class, as shown in the following example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2153
|
||
msgid "When run, this produces a file with exactly two lines::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2158
|
||
msgid ""
|
||
"While the above treatment is simplistic, it points the way to how exception "
|
||
"information can be formatted to your liking. The :mod:`traceback` module may "
|
||
"be helpful for more specialized needs."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2165
|
||
msgid "Speaking logging messages"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2167
|
||
msgid ""
|
||
"There might be situations when it is desirable to have logging messages "
|
||
"rendered in an audible rather than a visible format. This is easy to do if "
|
||
"you have text- to-speech (TTS) functionality available in your system, even "
|
||
"if it doesn't have a Python binding. Most TTS systems have a command line "
|
||
"program you can run, and this can be invoked from a handler using :mod:"
|
||
"`subprocess`. It's assumed here that TTS command line programs won't expect "
|
||
"to interact with users or take a long time to complete, and that the "
|
||
"frequency of logged messages will be not so high as to swamp the user with "
|
||
"messages, and that it's acceptable to have the messages spoken one at a time "
|
||
"rather than concurrently, The example implementation below waits for one "
|
||
"message to be spoken before the next is processed, and this might cause "
|
||
"other handlers to be kept waiting. Here is a short example showing the "
|
||
"approach, which assumes that the ``espeak`` TTS package is available::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2209
|
||
msgid ""
|
||
"When run, this script should say \"Hello\" and then \"Goodbye\" in a female "
|
||
"voice."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2211
|
||
msgid ""
|
||
"The above approach can, of course, be adapted to other TTS systems and even "
|
||
"other systems altogether which can process messages via external programs "
|
||
"run from a command line."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2219
|
||
msgid "Buffering logging messages and outputting them conditionally"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2221
|
||
msgid ""
|
||
"There might be situations where you want to log messages in a temporary area "
|
||
"and only output them if a certain condition occurs. For example, you may "
|
||
"want to start logging debug events in a function, and if the function "
|
||
"completes without errors, you don't want to clutter the log with the "
|
||
"collected debug information, but if there is an error, you want all the "
|
||
"debug information to be output as well as the error."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2228
|
||
msgid ""
|
||
"Here is an example which shows how you could do this using a decorator for "
|
||
"your functions where you want logging to behave this way. It makes use of "
|
||
"the :class:`logging.handlers.MemoryHandler`, which allows buffering of "
|
||
"logged events until some condition occurs, at which point the buffered "
|
||
"events are ``flushed`` - passed to another handler (the ``target`` handler) "
|
||
"for processing. By default, the ``MemoryHandler`` flushed when its buffer "
|
||
"gets filled up or an event whose level is greater than or equal to a "
|
||
"specified threshold is seen. You can use this recipe with a more specialised "
|
||
"subclass of ``MemoryHandler`` if you want custom flushing behavior."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2238
|
||
msgid ""
|
||
"The example script has a simple function, ``foo``, which just cycles through "
|
||
"all the logging levels, writing to ``sys.stderr`` to say what level it's "
|
||
"about to log at, and then actually logging a message at that level. You can "
|
||
"pass a parameter to ``foo`` which, if true, will log at ERROR and CRITICAL "
|
||
"levels - otherwise, it only logs at DEBUG, INFO and WARNING levels."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2244
|
||
msgid ""
|
||
"The script just arranges to decorate ``foo`` with a decorator which will do "
|
||
"the conditional logging that's required. The decorator takes a logger as a "
|
||
"parameter and attaches a memory handler for the duration of the call to the "
|
||
"decorated function. The decorator can be additionally parameterised using a "
|
||
"target handler, a level at which flushing should occur, and a capacity for "
|
||
"the buffer. These default to a :class:`~logging.StreamHandler` which writes "
|
||
"to ``sys.stderr``, ``logging.ERROR`` and ``100`` respectively."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2252
|
||
msgid "Here's the script::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2315
|
||
msgid "When this script is run, the following output should be observed::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2343
|
||
msgid ""
|
||
"As you can see, actual logging output only occurs when an event is logged "
|
||
"whose severity is ERROR or greater, but in that case, any previous events at "
|
||
"lower severities are also logged."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2347
|
||
msgid "You can of course use the conventional means of decoration::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2357
|
||
msgid "Formatting times using UTC (GMT) via configuration"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2359
|
||
msgid ""
|
||
"Sometimes you want to format times using UTC, which can be done using a "
|
||
"class such as `UTCFormatter`, shown below::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2368
|
||
msgid ""
|
||
"and you can then use the ``UTCFormatter`` in your code instead of :class:"
|
||
"`~logging.Formatter`. If you want to do that via configuration, you can use "
|
||
"the :func:`~logging.config.dictConfig` API with an approach illustrated by "
|
||
"the following complete example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2411
|
||
msgid "When this script is run, it should print something like::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2416
|
||
msgid ""
|
||
"showing how the time is formatted both as local time and UTC, one for each "
|
||
"handler."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2423
|
||
msgid "Using a context manager for selective logging"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2425
|
||
msgid ""
|
||
"There are times when it would be useful to temporarily change the logging "
|
||
"configuration and revert it back after doing something. For this, a context "
|
||
"manager is the most obvious way of saving and restoring the logging context. "
|
||
"Here is a simple example of such a context manager, which allows you to "
|
||
"optionally change the logging level and add a logging handler purely in the "
|
||
"scope of the context manager::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2458
|
||
msgid ""
|
||
"If you specify a level value, the logger's level is set to that value in the "
|
||
"scope of the with block covered by the context manager. If you specify a "
|
||
"handler, it is added to the logger on entry to the block and removed on exit "
|
||
"from the block. You can also ask the manager to close the handler for you on "
|
||
"block exit - you could do this if you don't need the handler any more."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2464
|
||
msgid ""
|
||
"To illustrate how it works, we can add the following block of code to the "
|
||
"above::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2482
|
||
msgid ""
|
||
"We initially set the logger's level to ``INFO``, so message #1 appears and "
|
||
"message #2 doesn't. We then change the level to ``DEBUG`` temporarily in the "
|
||
"following ``with`` block, and so message #3 appears. After the block exits, "
|
||
"the logger's level is restored to ``INFO`` and so message #4 doesn't appear. "
|
||
"In the next ``with`` block, we set the level to ``DEBUG`` again but also add "
|
||
"a handler writing to ``sys.stdout``. Thus, message #5 appears twice on the "
|
||
"console (once via ``stderr`` and once via ``stdout``). After the ``with`` "
|
||
"statement's completion, the status is as it was before so message #6 appears "
|
||
"(like message #1) whereas message #7 doesn't (just like message #2)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2492
|
||
msgid "If we run the resulting script, the result is as follows:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2503
|
||
msgid ""
|
||
"If we run it again, but pipe ``stderr`` to ``/dev/null``, we see the "
|
||
"following, which is the only message written to ``stdout``:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2511
|
||
msgid "Once again, but piping ``stdout`` to ``/dev/null``, we get:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2521
|
||
msgid ""
|
||
"In this case, the message #5 printed to ``stdout`` doesn't appear, as "
|
||
"expected."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:2523
|
||
msgid ""
|
||
"Of course, the approach described here can be generalised, for example to "
|
||
"attach logging filters temporarily. Note that the above code works in Python "
|
||
"2 as well as Python 3."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:5
|
||
msgid "Porting Python 2 Code to Python 3"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:7
|
||
msgid "Brett Cannon"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:11
|
||
msgid ""
|
||
"With Python 3 being the future of Python while Python 2 is still in active "
|
||
"use, it is good to have your project available for both major releases of "
|
||
"Python. This guide is meant to help you figure out how best to support both "
|
||
"Python 2 & 3 simultaneously."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:16
|
||
msgid ""
|
||
"If you are looking to port an extension module instead of pure Python code, "
|
||
"please see :ref:`cporting-howto`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:19
|
||
msgid ""
|
||
"If you would like to read one core Python developer's take on why Python 3 "
|
||
"came into existence, you can read Nick Coghlan's `Python 3 Q & A`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:22
|
||
msgid ""
|
||
"For help with porting, you can email the python-porting_ mailing list with "
|
||
"questions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:26
|
||
msgid "The Short Explanation"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:28
|
||
msgid ""
|
||
"To make your project be single-source Python 2/3 compatible, the basic steps "
|
||
"are:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:31
|
||
msgid "Only worry about supporting Python 2.7"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:32
|
||
msgid ""
|
||
"Make sure you have good test coverage (coverage.py_ can help; ``pip install "
|
||
"coverage``)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:34 ../Doc/howto/pyporting.rst:114
|
||
#: ../Doc/howto/pyporting.rst:415
|
||
msgid "Learn the differences between Python 2 & 3"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:35
|
||
msgid ""
|
||
"Use Modernize_ or Futurize_ to update your code (``pip install modernize`` "
|
||
"or ``pip install future``, respectively)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:37
|
||
msgid ""
|
||
"Use Pylint_ to help make sure you don't regress on your Python 3 support "
|
||
"(``pip install pylint``)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:39
|
||
msgid ""
|
||
"Use caniusepython3_ to find out which of your dependencies are blocking your "
|
||
"use of Python 3 (``pip install caniusepython3``)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:41
|
||
msgid ""
|
||
"Once your dependencies are no longer blocking you, use continuous "
|
||
"integration to make sure you stay compatible with Python 2 & 3 (tox_ can "
|
||
"help test against multiple versions of Python; ``pip install tox``)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:45
|
||
msgid ""
|
||
"If you are dropping support for Python 2 entirely, then after you learn the "
|
||
"differences between Python 2 & 3 you can run 2to3_ over your code and skip "
|
||
"the rest of the steps outlined above."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:51
|
||
msgid "Details"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:53
|
||
msgid ""
|
||
"A key point about supporting Python 2 & 3 simultaneously is that you can "
|
||
"start **today**! Even if your dependencies are not supporting Python 3 yet "
|
||
"that does not mean you can't modernize your code **now** to support Python "
|
||
"3. Most changes required to support Python 3 lead to cleaner code using "
|
||
"newer practices even in Python 2."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:59
|
||
msgid ""
|
||
"Another key point is that modernizing your Python 2 code to also support "
|
||
"Python 3 is largely automated for you. While you might have to make some API "
|
||
"decisions thanks to Python 3 clarifying text data versus binary data, the "
|
||
"lower-level work is now mostly done for you and thus can at least benefit "
|
||
"from the automated changes immediately."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:65
|
||
msgid ""
|
||
"Keep those key points in mind while you read on about the details of porting "
|
||
"your code to support Python 2 & 3 simultaneously."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:70
|
||
msgid "Drop support for Python 2.6 and older"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:72
|
||
msgid ""
|
||
"While you can make Python 2.5 work with Python 3, it is **much** easier if "
|
||
"you only have to work with Python 2.7. If dropping Python 2.5 is not an "
|
||
"option then the six_ project can help you support Python 2.5 & 3 "
|
||
"simultaneously (``pip install six``). Do realize, though, that nearly all "
|
||
"the projects listed in this HOWTO will not be available to you."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:78
|
||
msgid ""
|
||
"If you are able to skip Python 2.5 and older, then the required changes to "
|
||
"your code should continue to look and feel like idiomatic Python code. At "
|
||
"worst you will have to use a function instead of a method in some instances "
|
||
"or have to import a function instead of using a built-in one, but otherwise "
|
||
"the overall transformation should not feel foreign to you."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:84
|
||
msgid ""
|
||
"But you should aim for only supporting Python 2.7. Python 2.6 is no longer "
|
||
"supported and thus is not receiving bugfixes. This means **you** will have "
|
||
"to work around any issues you come across with Python 2.6. There are also "
|
||
"some tools mentioned in this HOWTO which do not support Python 2.6 (e.g., "
|
||
"Pylint_), and this will become more commonplace as time goes on. It will "
|
||
"simply be easier for you if you only support the versions of Python that you "
|
||
"have to support."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:92
|
||
msgid ""
|
||
"Make sure you specify the proper version support in your ``setup.py`` file"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:94
|
||
msgid ""
|
||
"In your ``setup.py`` file you should have the proper `trove classifier`_ "
|
||
"specifying what versions of Python you support. As your project does not "
|
||
"support Python 3 yet you should at least have ``Programming Language :: "
|
||
"Python :: 2 :: Only`` specified. Ideally you should also specify each major/"
|
||
"minor version of Python that you do support, e.g. ``Programming Language :: "
|
||
"Python :: 2.7``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:102
|
||
msgid "Have good test coverage"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:104
|
||
msgid ""
|
||
"Once you have your code supporting the oldest version of Python 2 you want "
|
||
"it to, you will want to make sure your test suite has good coverage. A good "
|
||
"rule of thumb is that if you want to be confident enough in your test suite "
|
||
"that any failures that appear after having tools rewrite your code are "
|
||
"actual bugs in the tools and not in your code. If you want a number to aim "
|
||
"for, try to get over 80% coverage (and don't feel bad if you can't easily "
|
||
"get past 90%). If you don't already have a tool to measure test coverage "
|
||
"then coverage.py_ is recommended."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:116
|
||
msgid ""
|
||
"Once you have your code well-tested you are ready to begin porting your code "
|
||
"to Python 3! But to fully understand how your code is going to change and "
|
||
"what you want to look out for while you code, you will want to learn what "
|
||
"changes Python 3 makes in terms of Python 2. Typically the two best ways of "
|
||
"doing that is reading the `\"What's New\"`_ doc for each release of Python 3 "
|
||
"and the `Porting to Python 3`_ book (which is free online). There is also a "
|
||
"handy `cheat sheet`_ from the Python-Future project."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:126
|
||
msgid "Update your code"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:128
|
||
msgid ""
|
||
"Once you feel like you know what is different in Python 3 compared to Python "
|
||
"2, it's time to update your code! You have a choice between two tools in "
|
||
"porting your code automatically: Modernize_ and Futurize_. Which tool you "
|
||
"choose will depend on how much like Python 3 you want your code to be. "
|
||
"Futurize_ does its best to make Python 3 idioms and practices exist in "
|
||
"Python 2, e.g. backporting the ``bytes`` type from Python 3 so that you have "
|
||
"semantic parity between the major versions of Python. Modernize_, on the "
|
||
"other hand, is more conservative and targets a Python 2/3 subset of Python, "
|
||
"relying on six_ to help provide compatibility."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:138
|
||
msgid ""
|
||
"Regardless of which tool you choose, they will update your code to run under "
|
||
"Python 3 while staying compatible with the version of Python 2 you started "
|
||
"with. Depending on how conservative you want to be, you may want to run the "
|
||
"tool over your test suite first and visually inspect the diff to make sure "
|
||
"the transformation is accurate. After you have transformed your test suite "
|
||
"and verified that all the tests still pass as expected, then you can "
|
||
"transform your application code knowing that any tests which fail is a "
|
||
"translation failure."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:146
|
||
msgid ""
|
||
"Unfortunately the tools can't automate everything to make your code work "
|
||
"under Python 3 and so there are a handful of things you will need to update "
|
||
"manually to get full Python 3 support (which of these steps are necessary "
|
||
"vary between the tools). Read the documentation for the tool you choose to "
|
||
"use to see what it fixes by default and what it can do optionally to know "
|
||
"what will (not) be fixed for you and what you may have to fix on your own (e."
|
||
"g. using ``io.open()`` over the built-in ``open()`` function is off by "
|
||
"default in Modernize). Luckily, though, there are only a couple of things to "
|
||
"watch out for which can be considered large issues that may be hard to debug "
|
||
"if not watched for."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:157
|
||
msgid "Division"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:159
|
||
msgid ""
|
||
"In Python 3, ``5 / 2 == 2.5`` and not ``2``; all division between ``int`` "
|
||
"values result in a ``float``. This change has actually been planned since "
|
||
"Python 2.2 which was released in 2002. Since then users have been encouraged "
|
||
"to add ``from __future__ import division`` to any and all files which use "
|
||
"the ``/`` and ``//`` operators or to be running the interpreter with the ``-"
|
||
"Q`` flag. If you have not been doing this then you will need to go through "
|
||
"your code and do two things:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:167
|
||
msgid "Add ``from __future__ import division`` to your files"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:168
|
||
msgid ""
|
||
"Update any division operator as necessary to either use ``//`` to use floor "
|
||
"division or continue using ``/`` and expect a float"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:171
|
||
msgid ""
|
||
"The reason that ``/`` isn't simply translated to ``//`` automatically is "
|
||
"that if an object defines a ``__truediv__`` method but not ``__floordiv__`` "
|
||
"then your code would begin to fail (e.g. a user-defined class that uses ``/"
|
||
"`` to signify some operation but not ``//`` for the same thing or at all)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:177
|
||
msgid "Text versus binary data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:179
|
||
msgid ""
|
||
"In Python 2 you could use the ``str`` type for both text and binary data. "
|
||
"Unfortunately this confluence of two different concepts could lead to "
|
||
"brittle code which sometimes worked for either kind of data, sometimes not. "
|
||
"It also could lead to confusing APIs if people didn't explicitly state that "
|
||
"something that accepted ``str`` accepted either text or binary data instead "
|
||
"of one specific type. This complicated the situation especially for anyone "
|
||
"supporting multiple languages as APIs wouldn't bother explicitly supporting "
|
||
"``unicode`` when they claimed text data support."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:188
|
||
msgid ""
|
||
"To make the distinction between text and binary data clearer and more "
|
||
"pronounced, Python 3 did what most languages created in the age of the "
|
||
"internet have done and made text and binary data distinct types that cannot "
|
||
"blindly be mixed together (Python predates widespread access to the "
|
||
"internet). For any code that only deals with text or only binary data, this "
|
||
"separation doesn't pose an issue. But for code that has to deal with both, "
|
||
"it does mean you might have to now care about when you are using text "
|
||
"compared to binary data, which is why this cannot be entirely automated."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:197
|
||
msgid ""
|
||
"To start, you will need to decide which APIs take text and which take binary "
|
||
"(it is **highly** recommended you don't design APIs that can take both due "
|
||
"to the difficulty of keeping the code working; as stated earlier it is "
|
||
"difficult to do well). In Python 2 this means making sure the APIs that take "
|
||
"text can work with ``unicode`` in Python 2 and those that work with binary "
|
||
"data work with the ``bytes`` type from Python 3 and thus a subset of ``str`` "
|
||
"in Python 2 (which the ``bytes`` type in Python 2 is an alias for). Usually "
|
||
"the biggest issue is realizing which methods exist for which types in Python "
|
||
"2 & 3 simultaneously (for text that's ``unicode`` in Python 2 and ``str`` in "
|
||
"Python 3, for binary that's ``str``/``bytes`` in Python 2 and ``bytes`` in "
|
||
"Python 3). The following table lists the **unique** methods of each data "
|
||
"type across Python 2 & 3 (e.g., the ``decode()`` method is usable on the "
|
||
"equivalent binary data type in either Python 2 or 3, but it can't be used by "
|
||
"the text data type consistently between Python 2 and 3 because ``str`` in "
|
||
"Python 3 doesn't have the method). Do note that as of Python 3.5 the "
|
||
"``__mod__`` method was added to the bytes type."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:214
|
||
msgid "**Text data**"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:214
|
||
msgid "**Binary data**"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:216
|
||
msgid "\\"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:216
|
||
msgid "decode"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:218
|
||
msgid "encode"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:220
|
||
msgid "format"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:222
|
||
msgid "isdecimal"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:224
|
||
msgid "isnumeric"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:227
|
||
msgid ""
|
||
"Making the distinction easier to handle can be accomplished by encoding and "
|
||
"decoding between binary data and text at the edge of your code. This means "
|
||
"that when you receive text in binary data, you should immediately decode it. "
|
||
"And if your code needs to send text as binary data then encode it as late as "
|
||
"possible. This allows your code to work with only text internally and thus "
|
||
"eliminates having to keep track of what type of data you are working with."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:234
|
||
msgid ""
|
||
"The next issue is making sure you know whether the string literals in your "
|
||
"code represent text or binary data. At minimum you should add a ``b`` prefix "
|
||
"to any literal that presents binary data. For text you should either use the "
|
||
"``from __future__ import unicode_literals`` statement or add a ``u`` prefix "
|
||
"to the text literal."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:240
|
||
msgid ""
|
||
"As part of this dichotomy you also need to be careful about opening files. "
|
||
"Unless you have been working on Windows, there is a chance you have not "
|
||
"always bothered to add the ``b`` mode when opening a binary file (e.g., "
|
||
"``rb`` for binary reading). Under Python 3, binary files and text files are "
|
||
"clearly distinct and mutually incompatible; see the :mod:`io` module for "
|
||
"details. Therefore, you **must** make a decision of whether a file will be "
|
||
"used for binary access (allowing binary data to be read and/or written) or "
|
||
"text access (allowing text data to be read and/or written). You should also "
|
||
"use :func:`io.open` for opening files instead of the built-in :func:`open` "
|
||
"function as the :mod:`io` module is consistent from Python 2 to 3 while the "
|
||
"built-in :func:`open` function is not (in Python 3 it's actually :func:`io."
|
||
"open`)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:252
|
||
msgid ""
|
||
"The constructors of both ``str`` and ``bytes`` have different semantics for "
|
||
"the same arguments between Python 2 & 3. Passing an integer to ``bytes`` in "
|
||
"Python 2 will give you the string representation of the integer: ``bytes(3) "
|
||
"== '3'``. But in Python 3, an integer argument to ``bytes`` will give you a "
|
||
"bytes object as long as the integer specified, filled with null bytes: "
|
||
"``bytes(3) == b'\\x00\\x00\\x00'``. A similar worry is necessary when "
|
||
"passing a bytes object to ``str``. In Python 2 you just get the bytes object "
|
||
"back: ``str(b'3') == b'3'``. But in Python 3 you get the string "
|
||
"representation of the bytes object: ``str(b'3') == \"b'3'\"``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:262
|
||
msgid ""
|
||
"Finally, the indexing of binary data requires careful handling (slicing does "
|
||
"**not** require any special handling). In Python 2, ``b'123'[1] == b'2'`` "
|
||
"while in Python 3 ``b'123'[1] == 50``. Because binary data is simply a "
|
||
"collection of binary numbers, Python 3 returns the integer value for the "
|
||
"byte you index on. But in Python 2 because ``bytes == str``, indexing "
|
||
"returns a one-item slice of bytes. The six_ project has a function named "
|
||
"``six.indexbytes()`` which will return an integer like in Python 3: ``six."
|
||
"indexbytes(b'123', 1)``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:271
|
||
msgid "To summarize:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:273
|
||
msgid "Decide which of your APIs take text and which take binary data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:274
|
||
msgid ""
|
||
"Make sure that your code that works with text also works with ``unicode`` "
|
||
"and code for binary data works with ``bytes`` in Python 2 (see the table "
|
||
"above for what methods you cannot use for each type)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:277
|
||
msgid ""
|
||
"Mark all binary literals with a ``b`` prefix, use a ``u`` prefix or :mod:"
|
||
"`__future__` import statement for text literals"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:279
|
||
msgid ""
|
||
"Decode binary data to text as soon as possible, encode text as binary data "
|
||
"as late as possible"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:281
|
||
msgid ""
|
||
"Open files using :func:`io.open` and make sure to specify the ``b`` mode "
|
||
"when appropriate"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:283
|
||
msgid "Be careful when indexing binary data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:287
|
||
msgid "Use feature detection instead of version detection"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:288
|
||
msgid ""
|
||
"Inevitably you will have code that has to choose what to do based on what "
|
||
"version of Python is running. The best way to do this is with feature "
|
||
"detection of whether the version of Python you're running under supports "
|
||
"what you need. If for some reason that doesn't work then you should make the "
|
||
"version check is against Python 2 and not Python 3. To help explain this, "
|
||
"let's look at an example."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:295
|
||
msgid ""
|
||
"Let's pretend that you need access to a feature of importlib_ that is "
|
||
"available in Python's standard library since Python 3.3 and available for "
|
||
"Python 2 through importlib2_ on PyPI. You might be tempted to write code to "
|
||
"access e.g. the ``importlib.abc`` module by doing the following::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:307
|
||
msgid ""
|
||
"The problem with this code is what happens when Python 4 comes out? It would "
|
||
"be better to treat Python 2 as the exceptional case instead of Python 3 and "
|
||
"assume that future Python versions will be more compatible with Python 3 "
|
||
"than Python 2::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:319
|
||
msgid ""
|
||
"The best solution, though, is to do no version detection at all and instead "
|
||
"rely on feature detection. That avoids any potential issues of getting the "
|
||
"version detection wrong and helps keep you future-compatible::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:330
|
||
msgid "Prevent compatibility regressions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:332
|
||
msgid ""
|
||
"Once you have fully translated your code to be compatible with Python 3, you "
|
||
"will want to make sure your code doesn't regress and stop working under "
|
||
"Python 3. This is especially true if you have a dependency which is blocking "
|
||
"you from actually running under Python 3 at the moment."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:337
|
||
msgid ""
|
||
"To help with staying compatible, any new modules you create should have at "
|
||
"least the following block of code at the top of it::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:345
|
||
msgid ""
|
||
"You can also run Python 2 with the ``-3`` flag to be warned about various "
|
||
"compatibility issues your code triggers during execution. If you turn "
|
||
"warnings into errors with ``-Werror`` then you can make sure that you don't "
|
||
"accidentally miss a warning."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:351
|
||
msgid ""
|
||
"You can also use the Pylint_ project and its ``--py3k`` flag to lint your "
|
||
"code to receive warnings when your code begins to deviate from Python 3 "
|
||
"compatibility. This also prevents you from having to run Modernize_ or "
|
||
"Futurize_ over your code regularly to catch compatibility regressions. This "
|
||
"does require you only support Python 2.7 and Python 3.4 or newer as that is "
|
||
"Pylint's minimum Python version support."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:360
|
||
msgid "Check which dependencies block your transition"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:362
|
||
msgid ""
|
||
"**After** you have made your code compatible with Python 3 you should begin "
|
||
"to care about whether your dependencies have also been ported. The "
|
||
"caniusepython3_ project was created to help you determine which projects -- "
|
||
"directly or indirectly -- are blocking you from supporting Python 3. There "
|
||
"is both a command-line tool as well as a web interface at https://"
|
||
"caniusepython3.com ."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:369
|
||
msgid ""
|
||
"The project also provides code which you can integrate into your test suite "
|
||
"so that you will have a failing test when you no longer have dependencies "
|
||
"blocking you from using Python 3. This allows you to avoid having to "
|
||
"manually check your dependencies and to be notified quickly when you can "
|
||
"start running on Python 3."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:375
|
||
msgid "Update your ``setup.py`` file to denote Python 3 compatibility"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:377
|
||
msgid ""
|
||
"Once your code works under Python 3, you should update the classifiers in "
|
||
"your ``setup.py`` to contain ``Programming Language :: Python :: 3`` and to "
|
||
"not specify sole Python 2 support. This will tell anyone using your code "
|
||
"that you support Python 2 **and** 3. Ideally you will also want to add "
|
||
"classifiers for each major/minor version of Python you now support."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:385
|
||
msgid "Use continuous integration to stay compatible"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:387
|
||
msgid ""
|
||
"Once you are able to fully run under Python 3 you will want to make sure "
|
||
"your code always works under both Python 2 & 3. Probably the best tool for "
|
||
"running your tests under multiple Python interpreters is tox_. You can then "
|
||
"integrate tox with your continuous integration system so that you never "
|
||
"accidentally break Python 2 or 3 support."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:393
|
||
msgid ""
|
||
"You may also want to use the ``-bb`` flag with the Python 3 interpreter to "
|
||
"trigger an exception when you are comparing bytes to strings or bytes to an "
|
||
"int (the latter is available starting in Python 3.5). By default type-"
|
||
"differing comparisons simply return ``False``, but if you made a mistake in "
|
||
"your separation of text/binary data handling or indexing on bytes you "
|
||
"wouldn't easily find the mistake. This flag will raise an exception when "
|
||
"these kinds of comparisons occur, making the mistake much easier to track "
|
||
"down."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:401
|
||
msgid ""
|
||
"And that's mostly it! At this point your code base is compatible with both "
|
||
"Python 2 and 3 simultaneously. Your testing will also be set up so that you "
|
||
"don't accidentally break Python 2 or 3 compatibility regardless of which "
|
||
"version you typically run your tests under while developing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:408
|
||
msgid "Dropping Python 2 support completely"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:410
|
||
msgid ""
|
||
"If you are able to fully drop support for Python 2, then the steps required "
|
||
"to transition to Python 3 simplify greatly."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:413
|
||
msgid "Update your code to only support Python 2.7"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:414
|
||
msgid "Make sure you have good test coverage (coverage.py_ can help)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:416
|
||
msgid "Use 2to3_ to rewrite your code to run only under Python 3"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:418
|
||
msgid ""
|
||
"After this your code will be fully Python 3 compliant but in a way that is "
|
||
"not supported by Python 2. You should also update the classifiers in your "
|
||
"``setup.py`` to contain ``Programming Language :: Python :: 3 :: Only``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:5
|
||
msgid "Regular Expression HOWTO"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:7
|
||
msgid "A.M. Kuchling <amk@amk.ca>"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:18
|
||
msgid ""
|
||
"This document is an introductory tutorial to using regular expressions in "
|
||
"Python with the :mod:`re` module. It provides a gentler introduction than "
|
||
"the corresponding section in the Library Reference."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:26
|
||
msgid ""
|
||
"Regular expressions (called REs, or regexes, or regex patterns) are "
|
||
"essentially a tiny, highly specialized programming language embedded inside "
|
||
"Python and made available through the :mod:`re` module. Using this little "
|
||
"language, you specify the rules for the set of possible strings that you "
|
||
"want to match; this set might contain English sentences, or e-mail "
|
||
"addresses, or TeX commands, or anything you like. You can then ask "
|
||
"questions such as \"Does this string match the pattern?\", or \"Is there a "
|
||
"match for the pattern anywhere in this string?\". You can also use REs to "
|
||
"modify a string or to split it apart in various ways."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:35
|
||
msgid ""
|
||
"Regular expression patterns are compiled into a series of bytecodes which "
|
||
"are then executed by a matching engine written in C. For advanced use, it "
|
||
"may be necessary to pay careful attention to how the engine will execute a "
|
||
"given RE, and write the RE in a certain way in order to produce bytecode "
|
||
"that runs faster. Optimization isn't covered in this document, because it "
|
||
"requires that you have a good understanding of the matching engine's "
|
||
"internals."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:42
|
||
msgid ""
|
||
"The regular expression language is relatively small and restricted, so not "
|
||
"all possible string processing tasks can be done using regular expressions. "
|
||
"There are also tasks that *can* be done with regular expressions, but the "
|
||
"expressions turn out to be very complicated. In these cases, you may be "
|
||
"better off writing Python code to do the processing; while Python code will "
|
||
"be slower than an elaborate regular expression, it will also probably be "
|
||
"more understandable."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:51
|
||
msgid "Simple Patterns"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:53
|
||
msgid ""
|
||
"We'll start by learning about the simplest possible regular expressions. "
|
||
"Since regular expressions are used to operate on strings, we'll begin with "
|
||
"the most common task: matching characters."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:57
|
||
msgid ""
|
||
"For a detailed explanation of the computer science underlying regular "
|
||
"expressions (deterministic and non-deterministic finite automata), you can "
|
||
"refer to almost any textbook on writing compilers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:63
|
||
msgid "Matching Characters"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:65
|
||
msgid ""
|
||
"Most letters and characters will simply match themselves. For example, the "
|
||
"regular expression ``test`` will match the string ``test`` exactly. (You "
|
||
"can enable a case-insensitive mode that would let this RE match ``Test`` or "
|
||
"``TEST`` as well; more about this later.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:70
|
||
msgid ""
|
||
"There are exceptions to this rule; some characters are special :dfn:"
|
||
"`metacharacters`, and don't match themselves. Instead, they signal that "
|
||
"some out-of-the-ordinary thing should be matched, or they affect other "
|
||
"portions of the RE by repeating them or changing their meaning. Much of "
|
||
"this document is devoted to discussing various metacharacters and what they "
|
||
"do."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:76
|
||
msgid ""
|
||
"Here's a complete list of the metacharacters; their meanings will be "
|
||
"discussed in the rest of this HOWTO."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:83
|
||
msgid ""
|
||
"The first metacharacters we'll look at are ``[`` and ``]``. They're used for "
|
||
"specifying a character class, which is a set of characters that you wish to "
|
||
"match. Characters can be listed individually, or a range of characters can "
|
||
"be indicated by giving two characters and separating them by a ``'-'``. For "
|
||
"example, ``[abc]`` will match any of the characters ``a``, ``b``, or ``c``; "
|
||
"this is the same as ``[a-c]``, which uses a range to express the same set of "
|
||
"characters. If you wanted to match only lowercase letters, your RE would be "
|
||
"``[a-z]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:92
|
||
msgid ""
|
||
"Metacharacters are not active inside classes. For example, ``[akm$]`` will "
|
||
"match any of the characters ``'a'``, ``'k'``, ``'m'``, or ``'$'``; ``'$'`` "
|
||
"is usually a metacharacter, but inside a character class it's stripped of "
|
||
"its special nature."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:97
|
||
msgid ""
|
||
"You can match the characters not listed within the class by :dfn:"
|
||
"`complementing` the set. This is indicated by including a ``'^'`` as the "
|
||
"first character of the class; ``'^'`` outside a character class will simply "
|
||
"match the ``'^'`` character. For example, ``[^5]`` will match any character "
|
||
"except ``'5'``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:102
|
||
msgid ""
|
||
"Perhaps the most important metacharacter is the backslash, ``\\``. As in "
|
||
"Python string literals, the backslash can be followed by various characters "
|
||
"to signal various special sequences. It's also used to escape all the "
|
||
"metacharacters so you can still match them in patterns; for example, if you "
|
||
"need to match a ``[`` or ``\\``, you can precede them with a backslash to "
|
||
"remove their special meaning: ``\\[`` or ``\\\\``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:109
|
||
msgid ""
|
||
"Some of the special sequences beginning with ``'\\'`` represent predefined "
|
||
"sets of characters that are often useful, such as the set of digits, the set "
|
||
"of letters, or the set of anything that isn't whitespace."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:114
|
||
msgid ""
|
||
"Let's take an example: ``\\w`` matches any alphanumeric character. If the "
|
||
"regex pattern is expressed in bytes, this is equivalent to the class ``[a-zA-"
|
||
"Z0-9_]``. If the regex pattern is a string, ``\\w`` will match all the "
|
||
"characters marked as letters in the Unicode database provided by the :mod:"
|
||
"`unicodedata` module. You can use the more restricted definition of ``\\w`` "
|
||
"in a string pattern by supplying the :const:`re.ASCII` flag when compiling "
|
||
"the regular expression."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:122
|
||
msgid ""
|
||
"The following list of special sequences isn't complete. For a complete list "
|
||
"of sequences and expanded class definitions for Unicode string patterns, see "
|
||
"the last part of :ref:`Regular Expression Syntax <re-syntax>` in the "
|
||
"Standard Library reference. In general, the Unicode versions match any "
|
||
"character that's in the appropriate category in the Unicode database."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:130
|
||
msgid "``\\d``"
|
||
msgstr "``\\d``"
|
||
|
||
#: ../Doc/howto/regex.rst:130
|
||
msgid "Matches any decimal digit; this is equivalent to the class ``[0-9]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:133
|
||
msgid "``\\D``"
|
||
msgstr "``\\D``"
|
||
|
||
#: ../Doc/howto/regex.rst:133
|
||
msgid ""
|
||
"Matches any non-digit character; this is equivalent to the class ``[^0-9]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:137
|
||
msgid "``\\s``"
|
||
msgstr "``\\s``"
|
||
|
||
#: ../Doc/howto/regex.rst:136
|
||
msgid ""
|
||
"Matches any whitespace character; this is equivalent to the class ``[ \\t\\n"
|
||
"\\r\\f\\v]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:141
|
||
msgid "``\\S``"
|
||
msgstr "``\\S``"
|
||
|
||
#: ../Doc/howto/regex.rst:140
|
||
msgid ""
|
||
"Matches any non-whitespace character; this is equivalent to the class ``[^ "
|
||
"\\t\\n\\r\\f\\v]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:145
|
||
msgid "``\\w``"
|
||
msgstr "``\\w``"
|
||
|
||
#: ../Doc/howto/regex.rst:144
|
||
msgid ""
|
||
"Matches any alphanumeric character; this is equivalent to the class ``[a-zA-"
|
||
"Z0-9_]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:149
|
||
msgid "``\\W``"
|
||
msgstr "``\\W``"
|
||
|
||
#: ../Doc/howto/regex.rst:148
|
||
msgid ""
|
||
"Matches any non-alphanumeric character; this is equivalent to the class "
|
||
"``[^a-zA-Z0-9_]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:151
|
||
msgid ""
|
||
"These sequences can be included inside a character class. For example, "
|
||
"``[\\s,.]`` is a character class that will match any whitespace character, "
|
||
"or ``','`` or ``'.'``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:155
|
||
msgid ""
|
||
"The final metacharacter in this section is ``.``. It matches anything "
|
||
"except a newline character, and there's an alternate mode (``re.DOTALL``) "
|
||
"where it will match even a newline. ``'.'`` is often used where you want to "
|
||
"match \"any character\"."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:162
|
||
msgid "Repeating Things"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:164
|
||
msgid ""
|
||
"Being able to match varying sets of characters is the first thing regular "
|
||
"expressions can do that isn't already possible with the methods available on "
|
||
"strings. However, if that was the only additional capability of regexes, "
|
||
"they wouldn't be much of an advance. Another capability is that you can "
|
||
"specify that portions of the RE must be repeated a certain number of times."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:170
|
||
msgid ""
|
||
"The first metacharacter for repeating things that we'll look at is ``*``. "
|
||
"``*`` doesn't match the literal character ``*``; instead, it specifies that "
|
||
"the previous character can be matched zero or more times, instead of exactly "
|
||
"once."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:174
|
||
msgid ""
|
||
"For example, ``ca*t`` will match ``ct`` (0 ``a`` characters), ``cat`` (1 "
|
||
"``a``), ``caaat`` (3 ``a`` characters), and so forth. The RE engine has "
|
||
"various internal limitations stemming from the size of C's ``int`` type that "
|
||
"will prevent it from matching over 2 billion ``a`` characters; patterns are "
|
||
"usually not written to match that much data."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:180
|
||
msgid ""
|
||
"Repetitions such as ``*`` are :dfn:`greedy`; when repeating a RE, the "
|
||
"matching engine will try to repeat it as many times as possible. If later "
|
||
"portions of the pattern don't match, the matching engine will then back up "
|
||
"and try again with fewer repetitions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:185
|
||
msgid ""
|
||
"A step-by-step example will make this more obvious. Let's consider the "
|
||
"expression ``a[bcd]*b``. This matches the letter ``'a'``, zero or more "
|
||
"letters from the class ``[bcd]``, and finally ends with a ``'b'``. Now "
|
||
"imagine matching this RE against the string ``abcbd``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:191
|
||
msgid "Step"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:191
|
||
msgid "Matched"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:191
|
||
msgid "Explanation"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:193
|
||
msgid "1"
|
||
msgstr "1"
|
||
|
||
#: ../Doc/howto/regex.rst:193
|
||
msgid "``a``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:193
|
||
msgid "The ``a`` in the RE matches."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:195
|
||
msgid "2"
|
||
msgstr "2"
|
||
|
||
#: ../Doc/howto/regex.rst:195
|
||
msgid "``abcbd``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:195
|
||
msgid ""
|
||
"The engine matches ``[bcd]*``, going as far as it can, which is to the end "
|
||
"of the string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:199
|
||
msgid "3"
|
||
msgstr "3"
|
||
|
||
#: ../Doc/howto/regex.rst:199 ../Doc/howto/regex.rst:207
|
||
msgid "*Failure*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:199
|
||
msgid ""
|
||
"The engine tries to match ``b``, but the current position is at the end of "
|
||
"the string, so it fails."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:204
|
||
msgid "4"
|
||
msgstr "4"
|
||
|
||
#: ../Doc/howto/regex.rst:204 ../Doc/howto/regex.rst:215
|
||
msgid "``abcb``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:204
|
||
msgid "Back up, so that ``[bcd]*`` matches one less character."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:207
|
||
msgid "5"
|
||
msgstr "5"
|
||
|
||
#: ../Doc/howto/regex.rst:207
|
||
msgid ""
|
||
"Try ``b`` again, but the current position is at the last character, which is "
|
||
"a ``'d'``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:211 ../Doc/howto/regex.rst:215
|
||
msgid "6"
|
||
msgstr "6"
|
||
|
||
#: ../Doc/howto/regex.rst:211
|
||
msgid "``abc``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:211
|
||
msgid "Back up again, so that ``[bcd]*`` is only matching ``bc``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:215
|
||
msgid ""
|
||
"Try ``b`` again. This time the character at the current position is "
|
||
"``'b'``, so it succeeds."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:221
|
||
msgid ""
|
||
"The end of the RE has now been reached, and it has matched ``abcb``. This "
|
||
"demonstrates how the matching engine goes as far as it can at first, and if "
|
||
"no match is found it will then progressively back up and retry the rest of "
|
||
"the RE again and again. It will back up until it has tried zero matches for "
|
||
"``[bcd]*``, and if that subsequently fails, the engine will conclude that "
|
||
"the string doesn't match the RE at all."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:228
|
||
msgid ""
|
||
"Another repeating metacharacter is ``+``, which matches one or more times. "
|
||
"Pay careful attention to the difference between ``*`` and ``+``; ``*`` "
|
||
"matches *zero* or more times, so whatever's being repeated may not be "
|
||
"present at all, while ``+`` requires at least *one* occurrence. To use a "
|
||
"similar example, ``ca+t`` will match ``cat`` (1 ``a``), ``caaat`` (3 "
|
||
"``a``'s), but won't match ``ct``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:235
|
||
msgid ""
|
||
"There are two more repeating qualifiers. The question mark character, ``?"
|
||
"``, matches either once or zero times; you can think of it as marking "
|
||
"something as being optional. For example, ``home-?brew`` matches either "
|
||
"``homebrew`` or ``home-brew``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:240
|
||
msgid ""
|
||
"The most complicated repeated qualifier is ``{m,n}``, where *m* and *n* are "
|
||
"decimal integers. This qualifier means there must be at least *m* "
|
||
"repetitions, and at most *n*. For example, ``a/{1,3}b`` will match ``a/b``, "
|
||
"``a//b``, and ``a///b``. It won't match ``ab``, which has no slashes, or "
|
||
"``a////b``, which has four."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:246
|
||
msgid ""
|
||
"You can omit either *m* or *n*; in that case, a reasonable value is assumed "
|
||
"for the missing value. Omitting *m* is interpreted as a lower limit of 0, "
|
||
"while omitting *n* results in an upper bound of infinity --- actually, the "
|
||
"upper bound is the 2-billion limit mentioned earlier, but that might as well "
|
||
"be infinity."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:251
|
||
msgid ""
|
||
"Readers of a reductionist bent may notice that the three other qualifiers "
|
||
"can all be expressed using this notation. ``{0,}`` is the same as ``*``, "
|
||
"``{1,}`` is equivalent to ``+``, and ``{0,1}`` is the same as ``?``. It's "
|
||
"better to use ``*``, ``+``, or ``?`` when you can, simply because they're "
|
||
"shorter and easier to read."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:259
|
||
msgid "Using Regular Expressions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:261
|
||
msgid ""
|
||
"Now that we've looked at some simple regular expressions, how do we actually "
|
||
"use them in Python? The :mod:`re` module provides an interface to the "
|
||
"regular expression engine, allowing you to compile REs into objects and then "
|
||
"perform matches with them."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:268
|
||
msgid "Compiling Regular Expressions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:270
|
||
msgid ""
|
||
"Regular expressions are compiled into pattern objects, which have methods "
|
||
"for various operations such as searching for pattern matches or performing "
|
||
"string substitutions. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:279
|
||
msgid ""
|
||
":func:`re.compile` also accepts an optional *flags* argument, used to enable "
|
||
"various special features and syntax variations. We'll go over the available "
|
||
"settings later, but for now a single example will do::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:285
|
||
msgid ""
|
||
"The RE is passed to :func:`re.compile` as a string. REs are handled as "
|
||
"strings because regular expressions aren't part of the core Python language, "
|
||
"and no special syntax was created for expressing them. (There are "
|
||
"applications that don't need REs at all, so there's no need to bloat the "
|
||
"language specification by including them.) Instead, the :mod:`re` module is "
|
||
"simply a C extension module included with Python, just like the :mod:"
|
||
"`socket` or :mod:`zlib` modules."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:292
|
||
msgid ""
|
||
"Putting REs in strings keeps the Python language simpler, but has one "
|
||
"disadvantage which is the topic of the next section."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:297
|
||
msgid "The Backslash Plague"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:299
|
||
msgid ""
|
||
"As stated earlier, regular expressions use the backslash character "
|
||
"(``'\\'``) to indicate special forms or to allow special characters to be "
|
||
"used without invoking their special meaning. This conflicts with Python's "
|
||
"usage of the same character for the same purpose in string literals."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:304
|
||
msgid ""
|
||
"Let's say you want to write a RE that matches the string ``\\section``, "
|
||
"which might be found in a LaTeX file. To figure out what to write in the "
|
||
"program code, start with the desired string to be matched. Next, you must "
|
||
"escape any backslashes and other metacharacters by preceding them with a "
|
||
"backslash, resulting in the string ``\\\\section``. The resulting string "
|
||
"that must be passed to :func:`re.compile` must be ``\\\\section``. However, "
|
||
"to express this as a Python string literal, both backslashes must be escaped "
|
||
"*again*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:313
|
||
msgid "Characters"
|
||
msgstr "Caractères"
|
||
|
||
#: ../Doc/howto/regex.rst:313
|
||
msgid "Stage"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:315
|
||
msgid "``\\section``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:315
|
||
msgid "Text string to be matched"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:317
|
||
msgid "``\\\\section``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:317
|
||
msgid "Escaped backslash for :func:`re.compile`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:319 ../Doc/howto/regex.rst:339
|
||
msgid "``\"\\\\\\\\section\"``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:319
|
||
msgid "Escaped backslashes for a string literal"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:322
|
||
msgid ""
|
||
"In short, to match a literal backslash, one has to write ``'\\\\\\\\'`` as "
|
||
"the RE string, because the regular expression must be ``\\\\``, and each "
|
||
"backslash must be expressed as ``\\\\`` inside a regular Python string "
|
||
"literal. In REs that feature backslashes repeatedly, this leads to lots of "
|
||
"repeated backslashes and makes the resulting strings difficult to understand."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:328
|
||
msgid ""
|
||
"The solution is to use Python's raw string notation for regular expressions; "
|
||
"backslashes are not handled in any special way in a string literal prefixed "
|
||
"with ``'r'``, so ``r\"\\n\"`` is a two-character string containing ``'\\'`` "
|
||
"and ``'n'``, while ``\"\\n\"`` is a one-character string containing a "
|
||
"newline. Regular expressions will often be written in Python code using this "
|
||
"raw string notation."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:335
|
||
msgid "Regular String"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:335
|
||
msgid "Raw string"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:337
|
||
msgid "``\"ab*\"``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:337
|
||
msgid "``r\"ab*\"``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:339
|
||
msgid "``r\"\\\\section\"``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:341
|
||
msgid "``\"\\\\w+\\\\s+\\\\1\"``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:341
|
||
msgid "``r\"\\w+\\s+\\1\"``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:346
|
||
msgid "Performing Matches"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:348
|
||
msgid ""
|
||
"Once you have an object representing a compiled regular expression, what do "
|
||
"you do with it? Pattern objects have several methods and attributes. Only "
|
||
"the most significant ones will be covered here; consult the :mod:`re` docs "
|
||
"for a complete listing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:354 ../Doc/howto/regex.rst:412
|
||
#: ../Doc/howto/regex.rst:1029
|
||
msgid "Method/Attribute"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:354 ../Doc/howto/regex.rst:412
|
||
#: ../Doc/howto/regex.rst:1029
|
||
msgid "Purpose"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:356
|
||
msgid "``match()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:356
|
||
msgid "Determine if the RE matches at the beginning of the string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:359
|
||
msgid "``search()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:359
|
||
msgid "Scan through a string, looking for any location where this RE matches."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:362
|
||
msgid "``findall()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:362
|
||
msgid "Find all substrings where the RE matches, and returns them as a list."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:365
|
||
msgid "``finditer()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:365
|
||
msgid ""
|
||
"Find all substrings where the RE matches, and returns them as an :term:"
|
||
"`iterator`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:369
|
||
msgid ""
|
||
":meth:`~re.regex.match` and :meth:`~re.regex.search` return ``None`` if no "
|
||
"match can be found. If they're successful, a :ref:`match object <match-"
|
||
"objects>` instance is returned, containing information about the match: "
|
||
"where it starts and ends, the substring it matched, and more."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:374
|
||
msgid ""
|
||
"You can learn about this by interactively experimenting with the :mod:`re` "
|
||
"module. If you have :mod:`tkinter` available, you may also want to look at :"
|
||
"source:`Tools/demo/redemo.py`, a demonstration program included with the "
|
||
"Python distribution. It allows you to enter REs and strings, and displays "
|
||
"whether the RE matches or fails. :file:`redemo.py` can be quite useful when "
|
||
"trying to debug a complicated RE."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:381
|
||
msgid ""
|
||
"This HOWTO uses the standard Python interpreter for its examples. First, run "
|
||
"the Python interpreter, import the :mod:`re` module, and compile a RE::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:389
|
||
msgid ""
|
||
"Now, you can try matching various strings against the RE ``[a-z]+``. An "
|
||
"empty string shouldn't match at all, since ``+`` means 'one or more "
|
||
"repetitions'. :meth:`match` should return ``None`` in this case, which will "
|
||
"cause the interpreter to print no output. You can explicitly print the "
|
||
"result of :meth:`match` to make this clear. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:399
|
||
msgid ""
|
||
"Now, let's try it on a string that it should match, such as ``tempo``. In "
|
||
"this case, :meth:`match` will return a :ref:`match object <match-objects>`, "
|
||
"so you should store the result in a variable for later use. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:407
|
||
msgid ""
|
||
"Now you can query the :ref:`match object <match-objects>` for information "
|
||
"about the matching string. :ref:`match object <match-objects>` instances "
|
||
"also have several methods and attributes; the most important ones are:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:414
|
||
msgid "``group()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:414
|
||
msgid "Return the string matched by the RE"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:416
|
||
msgid "``start()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:416
|
||
msgid "Return the starting position of the match"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:418
|
||
msgid "``end()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:418
|
||
msgid "Return the ending position of the match"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:420
|
||
msgid "``span()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:420
|
||
msgid "Return a tuple containing the (start, end) positions of the match"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:424
|
||
msgid "Trying these methods will soon clarify their meaning::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:433
|
||
msgid ""
|
||
":meth:`~re.match.group` returns the substring that was matched by the RE. :"
|
||
"meth:`~re.match.start` and :meth:`~re.match.end` return the starting and "
|
||
"ending index of the match. :meth:`~re.match.span` returns both start and end "
|
||
"indexes in a single tuple. Since the :meth:`match` method only checks if "
|
||
"the RE matches at the start of a string, :meth:`start` will always be zero. "
|
||
"However, the :meth:`search` method of patterns scans through the string, so "
|
||
"the match may not start at zero in that case. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:450
|
||
msgid ""
|
||
"In actual programs, the most common style is to store the :ref:`match object "
|
||
"<match-objects>` in a variable, and then check if it was ``None``. This "
|
||
"usually looks like::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:461
|
||
msgid ""
|
||
"Two pattern methods return all of the matches for a pattern. :meth:`~re."
|
||
"regex.findall` returns a list of matching strings::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:468
|
||
msgid ""
|
||
":meth:`findall` has to create the entire list before it can be returned as "
|
||
"the result. The :meth:`~re.regex.finditer` method returns a sequence of :"
|
||
"ref:`match object <match-objects>` instances as an :term:`iterator`::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:484
|
||
msgid "Module-Level Functions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:486
|
||
msgid ""
|
||
"You don't have to create a pattern object and call its methods; the :mod:"
|
||
"`re` module also provides top-level functions called :func:`~re.match`, :"
|
||
"func:`~re.search`, :func:`~re.findall`, :func:`~re.sub`, and so forth. "
|
||
"These functions take the same arguments as the corresponding pattern method "
|
||
"with the RE string added as the first argument, and still return either "
|
||
"``None`` or a :ref:`match object <match-objects>` instance. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:498
|
||
msgid ""
|
||
"Under the hood, these functions simply create a pattern object for you and "
|
||
"call the appropriate method on it. They also store the compiled object in a "
|
||
"cache, so future calls using the same RE won't need to parse the pattern "
|
||
"again and again."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:503
|
||
msgid ""
|
||
"Should you use these module-level functions, or should you get the pattern "
|
||
"and call its methods yourself? If you're accessing a regex within a loop, "
|
||
"pre-compiling it will save a few function calls. Outside of loops, there's "
|
||
"not much difference thanks to the internal cache."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:511
|
||
msgid "Compilation Flags"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:513
|
||
msgid ""
|
||
"Compilation flags let you modify some aspects of how regular expressions "
|
||
"work. Flags are available in the :mod:`re` module under two names, a long "
|
||
"name such as :const:`IGNORECASE` and a short, one-letter form such as :const:"
|
||
"`I`. (If you're familiar with Perl's pattern modifiers, the one-letter "
|
||
"forms use the same letters; the short form of :const:`re.VERBOSE` is :const:"
|
||
"`re.X`, for example.) Multiple flags can be specified by bitwise OR-ing "
|
||
"them; ``re.I | re.M`` sets both the :const:`I` and :const:`M` flags, for "
|
||
"example."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:521
|
||
msgid ""
|
||
"Here's a table of the available flags, followed by a more detailed "
|
||
"explanation of each one."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:525
|
||
msgid "Flag"
|
||
msgstr "Option"
|
||
|
||
#: ../Doc/howto/regex.rst:525
|
||
msgid "Meaning"
|
||
msgstr "Signification"
|
||
|
||
#: ../Doc/howto/regex.rst:527
|
||
msgid ":const:`ASCII`, :const:`A`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:527
|
||
msgid ""
|
||
"Makes several escapes like ``\\w``, ``\\b``, ``\\s`` and ``\\d`` match only "
|
||
"on ASCII characters with the respective property."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:531
|
||
msgid ":const:`DOTALL`, :const:`S`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:531
|
||
msgid "Make ``.`` match any character, including newlines"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:534
|
||
msgid ":const:`IGNORECASE`, :const:`I`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:534
|
||
msgid "Do case-insensitive matches"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:536
|
||
msgid ":const:`LOCALE`, :const:`L`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:536
|
||
msgid "Do a locale-aware match"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:538
|
||
msgid ":const:`MULTILINE`, :const:`M`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:538
|
||
msgid "Multi-line matching, affecting ``^`` and ``$``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:541
|
||
msgid ":const:`VERBOSE`, :const:`X` (for 'extended')"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:541
|
||
msgid ""
|
||
"Enable verbose REs, which can be organized more cleanly and understandably."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:550
|
||
msgid ""
|
||
"Perform case-insensitive matching; character class and literal strings will "
|
||
"match letters by ignoring case. For example, ``[A-Z]`` will match lowercase "
|
||
"letters, too, and ``Spam`` will match ``Spam``, ``spam``, or ``spAM``. This "
|
||
"lowercasing doesn't take the current locale into account; it will if you "
|
||
"also set the :const:`LOCALE` flag."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:561
|
||
msgid ""
|
||
"Make ``\\w``, ``\\W``, ``\\b``, and ``\\B``, dependent on the current locale "
|
||
"instead of the Unicode database."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:564
|
||
msgid ""
|
||
"Locales are a feature of the C library intended to help in writing programs "
|
||
"that take account of language differences. For example, if you're "
|
||
"processing French text, you'd want to be able to write ``\\w+`` to match "
|
||
"words, but ``\\w`` only matches the character class ``[A-Za-z]``; it won't "
|
||
"match ``'é'`` or ``'ç'``. If your system is configured properly and a "
|
||
"French locale is selected, certain C functions will tell the program that "
|
||
"``'é'`` should also be considered a letter. Setting the :const:`LOCALE` flag "
|
||
"when compiling a regular expression will cause the resulting compiled object "
|
||
"to use these C functions for ``\\w``; this is slower, but also enables ``\\w"
|
||
"+`` to match French words as you'd expect."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:579
|
||
msgid ""
|
||
"(``^`` and ``$`` haven't been explained yet; they'll be introduced in "
|
||
"section :ref:`more-metacharacters`.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:582
|
||
msgid ""
|
||
"Usually ``^`` matches only at the beginning of the string, and ``$`` matches "
|
||
"only at the end of the string and immediately before the newline (if any) at "
|
||
"the end of the string. When this flag is specified, ``^`` matches at the "
|
||
"beginning of the string and at the beginning of each line within the string, "
|
||
"immediately following each newline. Similarly, the ``$`` metacharacter "
|
||
"matches either at the end of the string and at the end of each line "
|
||
"(immediately preceding each newline)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:595
|
||
msgid ""
|
||
"Makes the ``'.'`` special character match any character at all, including a "
|
||
"newline; without this flag, ``'.'`` will match anything *except* a newline."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:603
|
||
msgid ""
|
||
"Make ``\\w``, ``\\W``, ``\\b``, ``\\B``, ``\\s`` and ``\\S`` perform ASCII-"
|
||
"only matching instead of full Unicode matching. This is only meaningful for "
|
||
"Unicode patterns, and is ignored for byte patterns."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:612
|
||
msgid ""
|
||
"This flag allows you to write regular expressions that are more readable by "
|
||
"granting you more flexibility in how you can format them. When this flag "
|
||
"has been specified, whitespace within the RE string is ignored, except when "
|
||
"the whitespace is in a character class or preceded by an unescaped "
|
||
"backslash; this lets you organize and indent the RE more clearly. This flag "
|
||
"also lets you put comments within a RE that will be ignored by the engine; "
|
||
"comments are marked by a ``'#'`` that's neither in a character class or "
|
||
"preceded by an unescaped backslash."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:621
|
||
msgid ""
|
||
"For example, here's a RE that uses :const:`re.VERBOSE`; see how much easier "
|
||
"it is to read? ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:634
|
||
msgid "Without the verbose setting, the RE would look like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:640
|
||
msgid ""
|
||
"In the above example, Python's automatic concatenation of string literals "
|
||
"has been used to break up the RE into smaller pieces, but it's still more "
|
||
"difficult to understand than the version using :const:`re.VERBOSE`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:646
|
||
msgid "More Pattern Power"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:648
|
||
msgid ""
|
||
"So far we've only covered a part of the features of regular expressions. In "
|
||
"this section, we'll cover some new metacharacters, and how to use groups to "
|
||
"retrieve portions of the text that was matched."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:656
|
||
msgid "More Metacharacters"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:658
|
||
msgid ""
|
||
"There are some metacharacters that we haven't covered yet. Most of them "
|
||
"will be covered in this section."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:661
|
||
msgid ""
|
||
"Some of the remaining metacharacters to be discussed are :dfn:`zero-width "
|
||
"assertions`. They don't cause the engine to advance through the string; "
|
||
"instead, they consume no characters at all, and simply succeed or fail. For "
|
||
"example, ``\\b`` is an assertion that the current position is located at a "
|
||
"word boundary; the position isn't changed by the ``\\b`` at all. This means "
|
||
"that zero-width assertions should never be repeated, because if they match "
|
||
"once at a given location, they can obviously be matched an infinite number "
|
||
"of times."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:677
|
||
msgid "``|``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:670
|
||
msgid ""
|
||
"Alternation, or the \"or\" operator. If A and B are regular expressions, "
|
||
"``A|B`` will match any string that matches either ``A`` or ``B``. ``|`` has "
|
||
"very low precedence in order to make it work reasonably when you're "
|
||
"alternating multi-character strings. ``Crow|Servo`` will match either "
|
||
"``Crow`` or ``Servo``, not ``Cro``, a ``'w'`` or an ``'S'``, and ``ervo``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:676
|
||
msgid ""
|
||
"To match a literal ``'|'``, use ``\\|``, or enclose it inside a character "
|
||
"class, as in ``[|]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:693
|
||
msgid "``^``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:680
|
||
msgid ""
|
||
"Matches at the beginning of lines. Unless the :const:`MULTILINE` flag has "
|
||
"been set, this will only match at the beginning of the string. In :const:"
|
||
"`MULTILINE` mode, this also matches immediately after each newline within "
|
||
"the string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:684
|
||
msgid ""
|
||
"For example, if you wish to match the word ``From`` only at the beginning of "
|
||
"a line, the RE to use is ``^From``. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:707
|
||
msgid "``$``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:696
|
||
msgid ""
|
||
"Matches at the end of a line, which is defined as either the end of the "
|
||
"string, or any location followed by a newline character. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:706
|
||
msgid ""
|
||
"To match a literal ``'$'``, use ``\\$`` or enclose it inside a character "
|
||
"class, as in ``[$]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:713
|
||
msgid "``\\A``"
|
||
msgstr "``\\A``"
|
||
|
||
#: ../Doc/howto/regex.rst:710
|
||
msgid ""
|
||
"Matches only at the start of the string. When not in :const:`MULTILINE` "
|
||
"mode, ``\\A`` and ``^`` are effectively the same. In :const:`MULTILINE` "
|
||
"mode, they're different: ``\\A`` still matches only at the beginning of the "
|
||
"string, but ``^`` may match at any location inside the string that follows a "
|
||
"newline character."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:716
|
||
msgid "``\\Z``"
|
||
msgstr "``\\Z``"
|
||
|
||
#: ../Doc/howto/regex.rst:716
|
||
msgid "Matches only at the end of the string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:751
|
||
msgid "``\\b``"
|
||
msgstr "``\\b``"
|
||
|
||
#: ../Doc/howto/regex.rst:719
|
||
msgid ""
|
||
"Word boundary. This is a zero-width assertion that matches only at the "
|
||
"beginning or end of a word. A word is defined as a sequence of alphanumeric "
|
||
"characters, so the end of a word is indicated by whitespace or a non-"
|
||
"alphanumeric character."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:724
|
||
msgid ""
|
||
"The following example matches ``class`` only when it's a complete word; it "
|
||
"won't match when it's contained inside another word. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:735
|
||
msgid ""
|
||
"There are two subtleties you should remember when using this special "
|
||
"sequence. First, this is the worst collision between Python's string "
|
||
"literals and regular expression sequences. In Python's string literals, ``"
|
||
"\\b`` is the backspace character, ASCII value 8. If you're not using raw "
|
||
"strings, then Python will convert the ``\\b`` to a backspace, and your RE "
|
||
"won't match as you expect it to. The following example looks the same as our "
|
||
"previous RE, but omits the ``'r'`` in front of the RE string. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:749
|
||
msgid ""
|
||
"Second, inside a character class, where there's no use for this assertion, ``"
|
||
"\\b`` represents the backspace character, for compatibility with Python's "
|
||
"string literals."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:756
|
||
msgid "``\\B``"
|
||
msgstr "``\\B``"
|
||
|
||
#: ../Doc/howto/regex.rst:754
|
||
msgid ""
|
||
"Another zero-width assertion, this is the opposite of ``\\b``, only matching "
|
||
"when the current position is not at a word boundary."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:759
|
||
msgid "Grouping"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:761
|
||
msgid ""
|
||
"Frequently you need to obtain more information than just whether the RE "
|
||
"matched or not. Regular expressions are often used to dissect strings by "
|
||
"writing a RE divided into several subgroups which match different components "
|
||
"of interest. For example, an RFC-822 header line is divided into a header "
|
||
"name and a value, separated by a ``':'``, like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:772
|
||
msgid ""
|
||
"This can be handled by writing a regular expression which matches an entire "
|
||
"header line, and has one group which matches the header name, and another "
|
||
"group which matches the header's value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:776
|
||
msgid ""
|
||
"Groups are marked by the ``'('``, ``')'`` metacharacters. ``'('`` and "
|
||
"``')'`` have much the same meaning as they do in mathematical expressions; "
|
||
"they group together the expressions contained inside them, and you can "
|
||
"repeat the contents of a group with a repeating qualifier, such as ``*``, ``"
|
||
"+``, ``?``, or ``{m,n}``. For example, ``(ab)*`` will match zero or more "
|
||
"repetitions of ``ab``. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:787
|
||
msgid ""
|
||
"Groups indicated with ``'('``, ``')'`` also capture the starting and ending "
|
||
"index of the text that they match; this can be retrieved by passing an "
|
||
"argument to :meth:`group`, :meth:`start`, :meth:`end`, and :meth:`span`. "
|
||
"Groups are numbered starting with 0. Group 0 is always present; it's the "
|
||
"whole RE, so :ref:`match object <match-objects>` methods all have group 0 as "
|
||
"their default argument. Later we'll see how to express groups that don't "
|
||
"capture the span of text that they match. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:802
|
||
msgid ""
|
||
"Subgroups are numbered from left to right, from 1 upward. Groups can be "
|
||
"nested; to determine the number, just count the opening parenthesis "
|
||
"characters, going from left to right. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:815
|
||
msgid ""
|
||
":meth:`group` can be passed multiple group numbers at a time, in which case "
|
||
"it will return a tuple containing the corresponding values for those "
|
||
"groups. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:821
|
||
msgid ""
|
||
"The :meth:`groups` method returns a tuple containing the strings for all the "
|
||
"subgroups, from 1 up to however many there are. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:827
|
||
msgid ""
|
||
"Backreferences in a pattern allow you to specify that the contents of an "
|
||
"earlier capturing group must also be found at the current location in the "
|
||
"string. For example, ``\\1`` will succeed if the exact contents of group 1 "
|
||
"can be found at the current position, and fails otherwise. Remember that "
|
||
"Python's string literals also use a backslash followed by numbers to allow "
|
||
"including arbitrary characters in a string, so be sure to use a raw string "
|
||
"when incorporating backreferences in a RE."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:835
|
||
msgid "For example, the following RE detects doubled words in a string. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:841
|
||
msgid ""
|
||
"Backreferences like this aren't often useful for just searching through a "
|
||
"string --- there are few text formats which repeat data in this way --- but "
|
||
"you'll soon find out that they're *very* useful when performing string "
|
||
"substitutions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:847
|
||
msgid "Non-capturing and Named Groups"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:849
|
||
msgid ""
|
||
"Elaborate REs may use many groups, both to capture substrings of interest, "
|
||
"and to group and structure the RE itself. In complex REs, it becomes "
|
||
"difficult to keep track of the group numbers. There are two features which "
|
||
"help with this problem. Both of them use a common syntax for regular "
|
||
"expression extensions, so we'll look at that first."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:855
|
||
msgid ""
|
||
"Perl 5 is well known for its powerful additions to standard regular "
|
||
"expressions. For these new features the Perl developers couldn't choose new "
|
||
"single-keystroke metacharacters or new special sequences beginning with ``"
|
||
"\\`` without making Perl's regular expressions confusingly different from "
|
||
"standard REs. If they chose ``&`` as a new metacharacter, for example, old "
|
||
"expressions would be assuming that ``&`` was a regular character and "
|
||
"wouldn't have escaped it by writing ``\\&`` or ``[&]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:862
|
||
msgid ""
|
||
"The solution chosen by the Perl developers was to use ``(?...)`` as the "
|
||
"extension syntax. ``?`` immediately after a parenthesis was a syntax error "
|
||
"because the ``?`` would have nothing to repeat, so this didn't introduce any "
|
||
"compatibility problems. The characters immediately after the ``?`` "
|
||
"indicate what extension is being used, so ``(?=foo)`` is one thing (a "
|
||
"positive lookahead assertion) and ``(?:foo)`` is something else (a non-"
|
||
"capturing group containing the subexpression ``foo``)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:870
|
||
msgid ""
|
||
"Python supports several of Perl's extensions and adds an extension syntax to "
|
||
"Perl's extension syntax. If the first character after the question mark is "
|
||
"a ``P``, you know that it's an extension that's specific to Python."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:875
|
||
msgid ""
|
||
"Now that we've looked at the general extension syntax, we can return to the "
|
||
"features that simplify working with groups in complex REs."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:878
|
||
msgid ""
|
||
"Sometimes you'll want to use a group to denote a part of a regular "
|
||
"expression, but aren't interested in retrieving the group's contents. You "
|
||
"can make this fact explicit by using a non-capturing group: ``(?:...)``, "
|
||
"where you can replace the ``...`` with any other regular expression. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:890
|
||
msgid ""
|
||
"Except for the fact that you can't retrieve the contents of what the group "
|
||
"matched, a non-capturing group behaves exactly the same as a capturing "
|
||
"group; you can put anything inside it, repeat it with a repetition "
|
||
"metacharacter such as ``*``, and nest it within other groups (capturing or "
|
||
"non-capturing). ``(?:...)`` is particularly useful when modifying an "
|
||
"existing pattern, since you can add new groups without changing how all the "
|
||
"other groups are numbered. It should be mentioned that there's no "
|
||
"performance difference in searching between capturing and non-capturing "
|
||
"groups; neither form is any faster than the other."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:899
|
||
msgid ""
|
||
"A more significant feature is named groups: instead of referring to them by "
|
||
"numbers, groups can be referenced by a name."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:902
|
||
msgid ""
|
||
"The syntax for a named group is one of the Python-specific extensions: ``(?"
|
||
"P<name>...)``. *name* is, obviously, the name of the group. Named groups "
|
||
"behave exactly like capturing groups, and additionally associate a name with "
|
||
"a group. The :ref:`match object <match-objects>` methods that deal with "
|
||
"capturing groups all accept either integers that refer to the group by "
|
||
"number or strings that contain the desired group's name. Named groups are "
|
||
"still given numbers, so you can retrieve information about a group in two "
|
||
"ways::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:917
|
||
msgid ""
|
||
"Named groups are handy because they let you use easily-remembered names, "
|
||
"instead of having to remember numbers. Here's an example RE from the :mod:"
|
||
"`imaplib` module::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:928
|
||
msgid ""
|
||
"It's obviously much easier to retrieve ``m.group('zonem')``, instead of "
|
||
"having to remember to retrieve group 9."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:931
|
||
msgid ""
|
||
"The syntax for backreferences in an expression such as ``(...)\\1`` refers "
|
||
"to the number of the group. There's naturally a variant that uses the group "
|
||
"name instead of the number. This is another Python extension: ``(?P=name)`` "
|
||
"indicates that the contents of the group called *name* should again be "
|
||
"matched at the current point. The regular expression for finding doubled "
|
||
"words, ``(\\b\\w+)\\s+\\1`` can also be written as ``(?P<word>\\b\\w+)\\s+(?"
|
||
"P=word)``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:944
|
||
msgid "Lookahead Assertions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:946
|
||
msgid ""
|
||
"Another zero-width assertion is the lookahead assertion. Lookahead "
|
||
"assertions are available in both positive and negative form, and look like "
|
||
"this:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:954
|
||
msgid "``(?=...)``"
|
||
msgstr "``(?=...)``"
|
||
|
||
#: ../Doc/howto/regex.rst:950
|
||
msgid ""
|
||
"Positive lookahead assertion. This succeeds if the contained regular "
|
||
"expression, represented here by ``...``, successfully matches at the current "
|
||
"location, and fails otherwise. But, once the contained expression has been "
|
||
"tried, the matching engine doesn't advance at all; the rest of the pattern "
|
||
"is tried right where the assertion started."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:959
|
||
msgid "``(?!...)``"
|
||
msgstr "``(?!...)``"
|
||
|
||
#: ../Doc/howto/regex.rst:957
|
||
msgid ""
|
||
"Negative lookahead assertion. This is the opposite of the positive "
|
||
"assertion; it succeeds if the contained expression *doesn't* match at the "
|
||
"current position in the string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:961
|
||
msgid ""
|
||
"To make this concrete, let's look at a case where a lookahead is useful. "
|
||
"Consider a simple pattern to match a filename and split it apart into a base "
|
||
"name and an extension, separated by a ``.``. For example, in ``news.rc``, "
|
||
"``news`` is the base name, and ``rc`` is the filename's extension."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:966
|
||
msgid "The pattern to match this is quite simple:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:968
|
||
msgid "``.*[.].*$``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:970
|
||
msgid ""
|
||
"Notice that the ``.`` needs to be treated specially because it's a "
|
||
"metacharacter, so it's inside a character class to only match that specific "
|
||
"character. Also notice the trailing ``$``; this is added to ensure that all "
|
||
"the rest of the string must be included in the extension. This regular "
|
||
"expression matches ``foo.bar`` and ``autoexec.bat`` and ``sendmail.cf`` and "
|
||
"``printers.conf``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:977
|
||
msgid ""
|
||
"Now, consider complicating the problem a bit; what if you want to match "
|
||
"filenames where the extension is not ``bat``? Some incorrect attempts:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:980
|
||
msgid ""
|
||
"``.*[.][^b].*$`` The first attempt above tries to exclude ``bat`` by "
|
||
"requiring that the first character of the extension is not a ``b``. This is "
|
||
"wrong, because the pattern also doesn't match ``foo.bar``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:984
|
||
msgid "``.*[.]([^b]..|.[^a].|..[^t])$``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:986
|
||
msgid ""
|
||
"The expression gets messier when you try to patch up the first solution by "
|
||
"requiring one of the following cases to match: the first character of the "
|
||
"extension isn't ``b``; the second character isn't ``a``; or the third "
|
||
"character isn't ``t``. This accepts ``foo.bar`` and rejects ``autoexec."
|
||
"bat``, but it requires a three-letter extension and won't accept a filename "
|
||
"with a two-letter extension such as ``sendmail.cf``. We'll complicate the "
|
||
"pattern again in an effort to fix it."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:994
|
||
msgid "``.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:996
|
||
msgid ""
|
||
"In the third attempt, the second and third letters are all made optional in "
|
||
"order to allow matching extensions shorter than three characters, such as "
|
||
"``sendmail.cf``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1000
|
||
msgid ""
|
||
"The pattern's getting really complicated now, which makes it hard to read "
|
||
"and understand. Worse, if the problem changes and you want to exclude both "
|
||
"``bat`` and ``exe`` as extensions, the pattern would get even more "
|
||
"complicated and confusing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1005
|
||
msgid "A negative lookahead cuts through all this confusion:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1007
|
||
msgid ""
|
||
"``.*[.](?!bat$)[^.]*$`` The negative lookahead means: if the expression "
|
||
"``bat`` doesn't match at this point, try the rest of the pattern; if ``bat"
|
||
"$`` does match, the whole pattern will fail. The trailing ``$`` is required "
|
||
"to ensure that something like ``sample.batch``, where the extension only "
|
||
"starts with ``bat``, will be allowed. The ``[^.]*`` makes sure that the "
|
||
"pattern works when there are multiple dots in the filename."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1014
|
||
msgid ""
|
||
"Excluding another filename extension is now easy; simply add it as an "
|
||
"alternative inside the assertion. The following pattern excludes filenames "
|
||
"that end in either ``bat`` or ``exe``:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1018
|
||
msgid "``.*[.](?!bat$|exe$)[^.]*$``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1022
|
||
msgid "Modifying Strings"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1024
|
||
msgid ""
|
||
"Up to this point, we've simply performed searches against a static string. "
|
||
"Regular expressions are also commonly used to modify strings in various "
|
||
"ways, using the following pattern methods:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1031
|
||
msgid "``split()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1031
|
||
msgid "Split the string into a list, splitting it wherever the RE matches"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1034
|
||
msgid "``sub()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1034
|
||
msgid ""
|
||
"Find all substrings where the RE matches, and replace them with a different "
|
||
"string"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1037
|
||
msgid "``subn()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1037
|
||
msgid ""
|
||
"Does the same thing as :meth:`sub`, but returns the new string and the "
|
||
"number of replacements"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1044
|
||
msgid "Splitting Strings"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1046
|
||
msgid ""
|
||
"The :meth:`split` method of a pattern splits a string apart wherever the RE "
|
||
"matches, returning a list of the pieces. It's similar to the :meth:`split` "
|
||
"method of strings but provides much more generality in the delimiters that "
|
||
"you can split by; string :meth:`split` only supports splitting by whitespace "
|
||
"or by a fixed string. As you'd expect, there's a module-level :func:`re."
|
||
"split` function, too."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1057
|
||
msgid ""
|
||
"Split *string* by the matches of the regular expression. If capturing "
|
||
"parentheses are used in the RE, then their contents will also be returned as "
|
||
"part of the resulting list. If *maxsplit* is nonzero, at most *maxsplit* "
|
||
"splits are performed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1062
|
||
msgid ""
|
||
"You can limit the number of splits made, by passing a value for *maxsplit*. "
|
||
"When *maxsplit* is nonzero, at most *maxsplit* splits will be made, and the "
|
||
"remainder of the string is returned as the final element of the list. In "
|
||
"the following example, the delimiter is any sequence of non-alphanumeric "
|
||
"characters. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1074
|
||
msgid ""
|
||
"Sometimes you're not only interested in what the text between delimiters is, "
|
||
"but also need to know what the delimiter was. If capturing parentheses are "
|
||
"used in the RE, then their values are also returned as part of the list. "
|
||
"Compare the following calls::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1086
|
||
msgid ""
|
||
"The module-level function :func:`re.split` adds the RE to be used as the "
|
||
"first argument, but is otherwise the same. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1098
|
||
msgid "Search and Replace"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1100
|
||
msgid ""
|
||
"Another common task is to find all the matches for a pattern, and replace "
|
||
"them with a different string. The :meth:`sub` method takes a replacement "
|
||
"value, which can be either a string or a function, and the string to be "
|
||
"processed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1107
|
||
msgid ""
|
||
"Returns the string obtained by replacing the leftmost non-overlapping "
|
||
"occurrences of the RE in *string* by the replacement *replacement*. If the "
|
||
"pattern isn't found, *string* is returned unchanged."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1111
|
||
msgid ""
|
||
"The optional argument *count* is the maximum number of pattern occurrences "
|
||
"to be replaced; *count* must be a non-negative integer. The default value "
|
||
"of 0 means to replace all occurrences."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1115
|
||
msgid ""
|
||
"Here's a simple example of using the :meth:`sub` method. It replaces colour "
|
||
"names with the word ``colour``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1124
|
||
msgid ""
|
||
"The :meth:`subn` method does the same work, but returns a 2-tuple containing "
|
||
"the new string value and the number of replacements that were performed::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1133
|
||
msgid ""
|
||
"Empty matches are replaced only when they're not adjacent to a previous "
|
||
"match. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1140
|
||
msgid ""
|
||
"If *replacement* is a string, any backslash escapes in it are processed. "
|
||
"That is, ``\\n`` is converted to a single newline character, ``\\r`` is "
|
||
"converted to a carriage return, and so forth. Unknown escapes such as ``"
|
||
"\\&`` are left alone. Backreferences, such as ``\\6``, are replaced with the "
|
||
"substring matched by the corresponding group in the RE. This lets you "
|
||
"incorporate portions of the original text in the resulting replacement "
|
||
"string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1147
|
||
msgid ""
|
||
"This example matches the word ``section`` followed by a string enclosed in "
|
||
"``{``, ``}``, and changes ``section`` to ``subsection``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1154
|
||
msgid ""
|
||
"There's also a syntax for referring to named groups as defined by the ``(?"
|
||
"P<name>...)`` syntax. ``\\g<name>`` will use the substring matched by the "
|
||
"group named ``name``, and ``\\g<number>`` uses the corresponding group "
|
||
"number. ``\\g<2>`` is therefore equivalent to ``\\2``, but isn't ambiguous "
|
||
"in a replacement string such as ``\\g<2>0``. (``\\20`` would be interpreted "
|
||
"as a reference to group 20, not a reference to group 2 followed by the "
|
||
"literal character ``'0'``.) The following substitutions are all equivalent, "
|
||
"but use all three variations of the replacement string. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1171
|
||
msgid ""
|
||
"*replacement* can also be a function, which gives you even more control. If "
|
||
"*replacement* is a function, the function is called for every non-"
|
||
"overlapping occurrence of *pattern*. On each call, the function is passed "
|
||
"a :ref:`match object <match-objects>` argument for the match and can use "
|
||
"this information to compute the desired replacement string and return it."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1177
|
||
msgid ""
|
||
"In the following example, the replacement function translates decimals into "
|
||
"hexadecimal::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1189
|
||
msgid ""
|
||
"When using the module-level :func:`re.sub` function, the pattern is passed "
|
||
"as the first argument. The pattern may be provided as an object or as a "
|
||
"string; if you need to specify regular expression flags, you must either use "
|
||
"a pattern object as the first parameter, or use embedded modifiers in the "
|
||
"pattern string, e.g. ``sub(\"(?i)b+\", \"x\", \"bbbb BBBB\")`` returns ``'x "
|
||
"x'``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1197
|
||
msgid "Common Problems"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1199
|
||
msgid ""
|
||
"Regular expressions are a powerful tool for some applications, but in some "
|
||
"ways their behaviour isn't intuitive and at times they don't behave the way "
|
||
"you may expect them to. This section will point out some of the most common "
|
||
"pitfalls."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1205
|
||
msgid "Use String Methods"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1207
|
||
msgid ""
|
||
"Sometimes using the :mod:`re` module is a mistake. If you're matching a "
|
||
"fixed string, or a single character class, and you're not using any :mod:"
|
||
"`re` features such as the :const:`IGNORECASE` flag, then the full power of "
|
||
"regular expressions may not be required. Strings have several methods for "
|
||
"performing operations with fixed strings and they're usually much faster, "
|
||
"because the implementation is a single small C loop that's been optimized "
|
||
"for the purpose, instead of the large, more generalized regular expression "
|
||
"engine."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1215
|
||
msgid ""
|
||
"One example might be replacing a single fixed string with another one; for "
|
||
"example, you might replace ``word`` with ``deed``. ``re.sub()`` seems like "
|
||
"the function to use for this, but consider the :meth:`replace` method. Note "
|
||
"that :func:`replace` will also replace ``word`` inside words, turning "
|
||
"``swordfish`` into ``sdeedfish``, but the naive RE ``word`` would have done "
|
||
"that, too. (To avoid performing the substitution on parts of words, the "
|
||
"pattern would have to be ``\\bword\\b``, in order to require that ``word`` "
|
||
"have a word boundary on either side. This takes the job beyond :meth:"
|
||
"`replace`'s abilities.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1224
|
||
msgid ""
|
||
"Another common task is deleting every occurrence of a single character from "
|
||
"a string or replacing it with another single character. You might do this "
|
||
"with something like ``re.sub('\\n', ' ', S)``, but :meth:`translate` is "
|
||
"capable of doing both tasks and will be faster than any regular expression "
|
||
"operation can be."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1230
|
||
msgid ""
|
||
"In short, before turning to the :mod:`re` module, consider whether your "
|
||
"problem can be solved with a faster and simpler string method."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1235
|
||
msgid "match() versus search()"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1237
|
||
msgid ""
|
||
"The :func:`match` function only checks if the RE matches at the beginning of "
|
||
"the string while :func:`search` will scan forward through the string for a "
|
||
"match. It's important to keep this distinction in mind. Remember, :func:"
|
||
"`match` will only report a successful match which will start at 0; if the "
|
||
"match wouldn't start at zero, :func:`match` will *not* report it. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1248
|
||
msgid ""
|
||
"On the other hand, :func:`search` will scan forward through the string, "
|
||
"reporting the first match it finds. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1256
|
||
msgid ""
|
||
"Sometimes you'll be tempted to keep using :func:`re.match`, and just add ``."
|
||
"*`` to the front of your RE. Resist this temptation and use :func:`re."
|
||
"search` instead. The regular expression compiler does some analysis of REs "
|
||
"in order to speed up the process of looking for a match. One such analysis "
|
||
"figures out what the first character of a match must be; for example, a "
|
||
"pattern starting with ``Crow`` must match starting with a ``'C'``. The "
|
||
"analysis lets the engine quickly scan through the string looking for the "
|
||
"starting character, only trying the full match if a ``'C'`` is found."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1265
|
||
msgid ""
|
||
"Adding ``.*`` defeats this optimization, requiring scanning to the end of "
|
||
"the string and then backtracking to find a match for the rest of the RE. "
|
||
"Use :func:`re.search` instead."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1271
|
||
msgid "Greedy versus Non-Greedy"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1273
|
||
msgid ""
|
||
"When repeating a regular expression, as in ``a*``, the resulting action is "
|
||
"to consume as much of the pattern as possible. This fact often bites you "
|
||
"when you're trying to match a pair of balanced delimiters, such as the angle "
|
||
"brackets surrounding an HTML tag. The naive pattern for matching a single "
|
||
"HTML tag doesn't work because of the greedy nature of ``.*``. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1287
|
||
msgid ""
|
||
"The RE matches the ``'<'`` in ``<html>``, and the ``.*`` consumes the rest "
|
||
"of the string. There's still more left in the RE, though, and the ``>`` "
|
||
"can't match at the end of the string, so the regular expression engine has "
|
||
"to backtrack character by character until it finds a match for the ``>``. "
|
||
"The final match extends from the ``'<'`` in ``<html>`` to the ``'>'`` in ``</"
|
||
"title>``, which isn't what you want."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1294
|
||
msgid ""
|
||
"In this case, the solution is to use the non-greedy qualifiers ``*?``, ``+?"
|
||
"``, ``??``, or ``{m,n}?``, which match as *little* text as possible. In the "
|
||
"above example, the ``'>'`` is tried immediately after the first ``'<'`` "
|
||
"matches, and when it fails, the engine advances a character at a time, "
|
||
"retrying the ``'>'`` at every step. This produces just the right result::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1303
|
||
msgid ""
|
||
"(Note that parsing HTML or XML with regular expressions is painful. Quick-"
|
||
"and-dirty patterns will handle common cases, but HTML and XML have special "
|
||
"cases that will break the obvious regular expression; by the time you've "
|
||
"written a regular expression that handles all of the possible cases, the "
|
||
"patterns will be *very* complicated. Use an HTML or XML parser module for "
|
||
"such tasks.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1311
|
||
msgid "Using re.VERBOSE"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1313
|
||
msgid ""
|
||
"By now you've probably noticed that regular expressions are a very compact "
|
||
"notation, but they're not terribly readable. REs of moderate complexity can "
|
||
"become lengthy collections of backslashes, parentheses, and metacharacters, "
|
||
"making them difficult to read and understand."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1318
|
||
msgid ""
|
||
"For such REs, specifying the ``re.VERBOSE`` flag when compiling the regular "
|
||
"expression can be helpful, because it allows you to format the regular "
|
||
"expression more clearly."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1322
|
||
msgid ""
|
||
"The ``re.VERBOSE`` flag has several effects. Whitespace in the regular "
|
||
"expression that *isn't* inside a character class is ignored. This means "
|
||
"that an expression such as ``dog | cat`` is equivalent to the less readable "
|
||
"``dog|cat``, but ``[a b]`` will still match the characters ``'a'``, ``'b'``, "
|
||
"or a space. In addition, you can also put comments inside a RE; comments "
|
||
"extend from a ``#`` character to the next newline. When used with triple-"
|
||
"quoted strings, this enables REs to be formatted more neatly::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1339
|
||
msgid "This is far more readable than::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1345
|
||
msgid "Feedback"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1347
|
||
msgid ""
|
||
"Regular expressions are a complicated topic. Did this document help you "
|
||
"understand them? Were there parts that were unclear, or Problems you "
|
||
"encountered that weren't covered here? If so, please send suggestions for "
|
||
"improvements to the author."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1352
|
||
msgid ""
|
||
"The most complete book on regular expressions is almost certainly Jeffrey "
|
||
"Friedl's Mastering Regular Expressions, published by O'Reilly. "
|
||
"Unfortunately, it exclusively concentrates on Perl and Java's flavours of "
|
||
"regular expressions, and doesn't contain any Python material at all, so it "
|
||
"won't be useful as a reference for programming in Python. (The first "
|
||
"edition covered Python's now-removed :mod:`regex` module, which won't help "
|
||
"you much.) Consider checking it out from your library."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:5
|
||
msgid "Socket Programming HOWTO"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:7
|
||
msgid "Gordon McMillan"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:12
|
||
msgid ""
|
||
"Sockets are used nearly everywhere, but are one of the most severely "
|
||
"misunderstood technologies around. This is a 10,000 foot overview of "
|
||
"sockets. It's not really a tutorial - you'll still have work to do in "
|
||
"getting things operational. It doesn't cover the fine points (and there are "
|
||
"a lot of them), but I hope it will give you enough background to begin using "
|
||
"them decently."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:20
|
||
msgid "Sockets"
|
||
msgstr "Interfaces de connexion (*sockets*)"
|
||
|
||
#: ../Doc/howto/sockets.rst:22
|
||
msgid ""
|
||
"I'm only going to talk about INET (i.e. IPv4) sockets, but they account for "
|
||
"at least 99% of the sockets in use. And I'll only talk about STREAM (i.e. "
|
||
"TCP) sockets - unless you really know what you're doing (in which case this "
|
||
"HOWTO isn't for you!), you'll get better behavior and performance from a "
|
||
"STREAM socket than anything else. I will try to clear up the mystery of what "
|
||
"a socket is, as well as some hints on how to work with blocking and non-"
|
||
"blocking sockets. But I'll start by talking about blocking sockets. You'll "
|
||
"need to know how they work before dealing with non-blocking sockets."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:31
|
||
msgid ""
|
||
"Part of the trouble with understanding these things is that \"socket\" can "
|
||
"mean a number of subtly different things, depending on context. So first, "
|
||
"let's make a distinction between a \"client\" socket - an endpoint of a "
|
||
"conversation, and a \"server\" socket, which is more like a switchboard "
|
||
"operator. The client application (your browser, for example) uses \"client\" "
|
||
"sockets exclusively; the web server it's talking to uses both \"server\" "
|
||
"sockets and \"client\" sockets."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:40
|
||
msgid "History"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:42
|
||
msgid ""
|
||
"Of the various forms of :abbr:`IPC (Inter Process Communication)`, sockets "
|
||
"are by far the most popular. On any given platform, there are likely to be "
|
||
"other forms of IPC that are faster, but for cross-platform communication, "
|
||
"sockets are about the only game in town."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:47
|
||
msgid ""
|
||
"They were invented in Berkeley as part of the BSD flavor of Unix. They "
|
||
"spread like wildfire with the Internet. With good reason --- the combination "
|
||
"of sockets with INET makes talking to arbitrary machines around the world "
|
||
"unbelievably easy (at least compared to other schemes)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:54
|
||
msgid "Creating a Socket"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:56
|
||
msgid ""
|
||
"Roughly speaking, when you clicked on the link that brought you to this "
|
||
"page, your browser did something like the following::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:64
|
||
msgid ""
|
||
"When the ``connect`` completes, the socket ``s`` can be used to send in a "
|
||
"request for the text of the page. The same socket will read the reply, and "
|
||
"then be destroyed. That's right, destroyed. Client sockets are normally only "
|
||
"used for one exchange (or a small set of sequential exchanges)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:70
|
||
msgid ""
|
||
"What happens in the web server is a bit more complex. First, the web server "
|
||
"creates a \"server socket\"::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:80
|
||
msgid ""
|
||
"A couple things to notice: we used ``socket.gethostname()`` so that the "
|
||
"socket would be visible to the outside world. If we had used ``s."
|
||
"bind(('localhost', 80))`` or ``s.bind(('127.0.0.1', 80))`` we would still "
|
||
"have a \"server\" socket, but one that was only visible within the same "
|
||
"machine. ``s.bind(('', 80))`` specifies that the socket is reachable by any "
|
||
"address the machine happens to have."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:87
|
||
msgid ""
|
||
"A second thing to note: low number ports are usually reserved for \"well "
|
||
"known\" services (HTTP, SNMP etc). If you're playing around, use a nice high "
|
||
"number (4 digits)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:91
|
||
msgid ""
|
||
"Finally, the argument to ``listen`` tells the socket library that we want it "
|
||
"to queue up as many as 5 connect requests (the normal max) before refusing "
|
||
"outside connections. If the rest of the code is written properly, that "
|
||
"should be plenty."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:95
|
||
msgid ""
|
||
"Now that we have a \"server\" socket, listening on port 80, we can enter the "
|
||
"mainloop of the web server::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:106
|
||
msgid ""
|
||
"There's actually 3 general ways in which this loop could work - dispatching "
|
||
"a thread to handle ``clientsocket``, create a new process to handle "
|
||
"``clientsocket``, or restructure this app to use non-blocking sockets, and "
|
||
"multiplex between our \"server\" socket and any active ``clientsocket``\\ s "
|
||
"using ``select``. More about that later. The important thing to understand "
|
||
"now is this: this is *all* a \"server\" socket does. It doesn't send any "
|
||
"data. It doesn't receive any data. It just produces \"client\" sockets. Each "
|
||
"``clientsocket`` is created in response to some *other* \"client\" socket "
|
||
"doing a ``connect()`` to the host and port we're bound to. As soon as we've "
|
||
"created that ``clientsocket``, we go back to listening for more connections. "
|
||
"The two \"clients\" are free to chat it up - they are using some dynamically "
|
||
"allocated port which will be recycled when the conversation ends."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:121
|
||
msgid "IPC"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:123
|
||
msgid ""
|
||
"If you need fast IPC between two processes on one machine, you should look "
|
||
"into pipes or shared memory. If you do decide to use AF_INET sockets, bind "
|
||
"the \"server\" socket to ``'localhost'``. On most platforms, this will take "
|
||
"a shortcut around a couple of layers of network code and be quite a bit "
|
||
"faster."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:129
|
||
msgid ""
|
||
"The :mod:`multiprocessing` integrates cross-platform IPC into a higher-level "
|
||
"API."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:134
|
||
msgid "Using a Socket"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:136
|
||
msgid ""
|
||
"The first thing to note, is that the web browser's \"client\" socket and the "
|
||
"web server's \"client\" socket are identical beasts. That is, this is a "
|
||
"\"peer to peer\" conversation. Or to put it another way, *as the designer, "
|
||
"you will have to decide what the rules of etiquette are for a conversation*. "
|
||
"Normally, the ``connect``\\ ing socket starts the conversation, by sending "
|
||
"in a request, or perhaps a signon. But that's a design decision - it's not a "
|
||
"rule of sockets."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:143
|
||
msgid ""
|
||
"Now there are two sets of verbs to use for communication. You can use "
|
||
"``send`` and ``recv``, or you can transform your client socket into a file-"
|
||
"like beast and use ``read`` and ``write``. The latter is the way Java "
|
||
"presents its sockets. I'm not going to talk about it here, except to warn "
|
||
"you that you need to use ``flush`` on sockets. These are buffered \"files\", "
|
||
"and a common mistake is to ``write`` something, and then ``read`` for a "
|
||
"reply. Without a ``flush`` in there, you may wait forever for the reply, "
|
||
"because the request may still be in your output buffer."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:152
|
||
msgid ""
|
||
"Now we come to the major stumbling block of sockets - ``send`` and ``recv`` "
|
||
"operate on the network buffers. They do not necessarily handle all the bytes "
|
||
"you hand them (or expect from them), because their major focus is handling "
|
||
"the network buffers. In general, they return when the associated network "
|
||
"buffers have been filled (``send``) or emptied (``recv``). They then tell "
|
||
"you how many bytes they handled. It is *your* responsibility to call them "
|
||
"again until your message has been completely dealt with."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:160
|
||
msgid ""
|
||
"When a ``recv`` returns 0 bytes, it means the other side has closed (or is "
|
||
"in the process of closing) the connection. You will not receive any more "
|
||
"data on this connection. Ever. You may be able to send data successfully; "
|
||
"I'll talk more about this later."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:165
|
||
msgid ""
|
||
"A protocol like HTTP uses a socket for only one transfer. The client sends a "
|
||
"request, then reads a reply. That's it. The socket is discarded. This means "
|
||
"that a client can detect the end of the reply by receiving 0 bytes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:169
|
||
msgid ""
|
||
"But if you plan to reuse your socket for further transfers, you need to "
|
||
"realize that *there is no* :abbr:`EOT (End of Transfer)` *on a socket.* I "
|
||
"repeat: if a socket ``send`` or ``recv`` returns after handling 0 bytes, the "
|
||
"connection has been broken. If the connection has *not* been broken, you "
|
||
"may wait on a ``recv`` forever, because the socket will *not* tell you that "
|
||
"there's nothing more to read (for now). Now if you think about that a bit, "
|
||
"you'll come to realize a fundamental truth of sockets: *messages must either "
|
||
"be fixed length* (yuck), *or be delimited* (shrug), *or indicate how long "
|
||
"they are* (much better), *or end by shutting down the connection*. The "
|
||
"choice is entirely yours, (but some ways are righter than others)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:180
|
||
msgid ""
|
||
"Assuming you don't want to end the connection, the simplest solution is a "
|
||
"fixed length message::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:217
|
||
msgid ""
|
||
"The sending code here is usable for almost any messaging scheme - in Python "
|
||
"you send strings, and you can use ``len()`` to determine its length (even if "
|
||
"it has embedded ``\\0`` characters). It's mostly the receiving code that "
|
||
"gets more complex. (And in C, it's not much worse, except you can't use "
|
||
"``strlen`` if the message has embedded ``\\0``\\ s.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:223
|
||
msgid ""
|
||
"The easiest enhancement is to make the first character of the message an "
|
||
"indicator of message type, and have the type determine the length. Now you "
|
||
"have two ``recv``\\ s - the first to get (at least) that first character so "
|
||
"you can look up the length, and the second in a loop to get the rest. If you "
|
||
"decide to go the delimited route, you'll be receiving in some arbitrary "
|
||
"chunk size, (4096 or 8192 is frequently a good match for network buffer "
|
||
"sizes), and scanning what you've received for a delimiter."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:231
|
||
msgid ""
|
||
"One complication to be aware of: if your conversational protocol allows "
|
||
"multiple messages to be sent back to back (without some kind of reply), and "
|
||
"you pass ``recv`` an arbitrary chunk size, you may end up reading the start "
|
||
"of a following message. You'll need to put that aside and hold onto it, "
|
||
"until it's needed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:237
|
||
msgid ""
|
||
"Prefixing the message with its length (say, as 5 numeric characters) gets "
|
||
"more complex, because (believe it or not), you may not get all 5 characters "
|
||
"in one ``recv``. In playing around, you'll get away with it; but in high "
|
||
"network loads, your code will very quickly break unless you use two ``recv`` "
|
||
"loops - the first to determine the length, the second to get the data part "
|
||
"of the message. Nasty. This is also when you'll discover that ``send`` does "
|
||
"not always manage to get rid of everything in one pass. And despite having "
|
||
"read this, you will eventually get bit by it!"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:246
|
||
msgid ""
|
||
"In the interests of space, building your character, (and preserving my "
|
||
"competitive position), these enhancements are left as an exercise for the "
|
||
"reader. Lets move on to cleaning up."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:252
|
||
msgid "Binary Data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:254
|
||
msgid ""
|
||
"It is perfectly possible to send binary data over a socket. The major "
|
||
"problem is that not all machines use the same formats for binary data. For "
|
||
"example, a Motorola chip will represent a 16 bit integer with the value 1 as "
|
||
"the two hex bytes 00 01. Intel and DEC, however, are byte-reversed - that "
|
||
"same 1 is 01 00. Socket libraries have calls for converting 16 and 32 bit "
|
||
"integers - ``ntohl, htonl, ntohs, htons`` where \"n\" means *network* and \"h"
|
||
"\" means *host*, \"s\" means *short* and \"l\" means *long*. Where network "
|
||
"order is host order, these do nothing, but where the machine is byte-"
|
||
"reversed, these swap the bytes around appropriately."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:264
|
||
msgid ""
|
||
"In these days of 32 bit machines, the ascii representation of binary data is "
|
||
"frequently smaller than the binary representation. That's because a "
|
||
"surprising amount of the time, all those longs have the value 0, or maybe 1. "
|
||
"The string \"0\" would be two bytes, while binary is four. Of course, this "
|
||
"doesn't fit well with fixed-length messages. Decisions, decisions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:272
|
||
msgid "Disconnecting"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:274
|
||
msgid ""
|
||
"Strictly speaking, you're supposed to use ``shutdown`` on a socket before "
|
||
"you ``close`` it. The ``shutdown`` is an advisory to the socket at the "
|
||
"other end. Depending on the argument you pass it, it can mean \"I'm not "
|
||
"going to send anymore, but I'll still listen\", or \"I'm not listening, good "
|
||
"riddance!\". Most socket libraries, however, are so used to programmers "
|
||
"neglecting to use this piece of etiquette that normally a ``close`` is the "
|
||
"same as ``shutdown(); close()``. So in most situations, an explicit "
|
||
"``shutdown`` is not needed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:282
|
||
msgid ""
|
||
"One way to use ``shutdown`` effectively is in an HTTP-like exchange. The "
|
||
"client sends a request and then does a ``shutdown(1)``. This tells the "
|
||
"server \"This client is done sending, but can still receive.\" The server "
|
||
"can detect \"EOF\" by a receive of 0 bytes. It can assume it has the "
|
||
"complete request. The server sends a reply. If the ``send`` completes "
|
||
"successfully then, indeed, the client was still receiving."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:289
|
||
msgid ""
|
||
"Python takes the automatic shutdown a step further, and says that when a "
|
||
"socket is garbage collected, it will automatically do a ``close`` if it's "
|
||
"needed. But relying on this is a very bad habit. If your socket just "
|
||
"disappears without doing a ``close``, the socket at the other end may hang "
|
||
"indefinitely, thinking you're just being slow. *Please* ``close`` your "
|
||
"sockets when you're done."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:297
|
||
msgid "When Sockets Die"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:299
|
||
msgid ""
|
||
"Probably the worst thing about using blocking sockets is what happens when "
|
||
"the other side comes down hard (without doing a ``close``). Your socket is "
|
||
"likely to hang. TCP is a reliable protocol, and it will wait a long, long "
|
||
"time before giving up on a connection. If you're using threads, the entire "
|
||
"thread is essentially dead. There's not much you can do about it. As long as "
|
||
"you aren't doing something dumb, like holding a lock while doing a blocking "
|
||
"read, the thread isn't really consuming much in the way of resources. Do "
|
||
"*not* try to kill the thread - part of the reason that threads are more "
|
||
"efficient than processes is that they avoid the overhead associated with the "
|
||
"automatic recycling of resources. In other words, if you do manage to kill "
|
||
"the thread, your whole process is likely to be screwed up."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:313
|
||
msgid "Non-blocking Sockets"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:315
|
||
msgid ""
|
||
"If you've understood the preceding, you already know most of what you need "
|
||
"to know about the mechanics of using sockets. You'll still use the same "
|
||
"calls, in much the same ways. It's just that, if you do it right, your app "
|
||
"will be almost inside-out."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:320
|
||
msgid ""
|
||
"In Python, you use ``socket.setblocking(0)`` to make it non-blocking. In C, "
|
||
"it's more complex, (for one thing, you'll need to choose between the BSD "
|
||
"flavor ``O_NONBLOCK`` and the almost indistinguishable Posix flavor "
|
||
"``O_NDELAY``, which is completely different from ``TCP_NODELAY``), but it's "
|
||
"the exact same idea. You do this after creating the socket, but before using "
|
||
"it. (Actually, if you're nuts, you can switch back and forth.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:327
|
||
msgid ""
|
||
"The major mechanical difference is that ``send``, ``recv``, ``connect`` and "
|
||
"``accept`` can return without having done anything. You have (of course) a "
|
||
"number of choices. You can check return code and error codes and generally "
|
||
"drive yourself crazy. If you don't believe me, try it sometime. Your app "
|
||
"will grow large, buggy and suck CPU. So let's skip the brain-dead solutions "
|
||
"and do it right."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:334
|
||
msgid "Use ``select``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:336
|
||
msgid ""
|
||
"In C, coding ``select`` is fairly complex. In Python, it's a piece of cake, "
|
||
"but it's close enough to the C version that if you understand ``select`` in "
|
||
"Python, you'll have little trouble with it in C::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:347
|
||
msgid ""
|
||
"You pass ``select`` three lists: the first contains all sockets that you "
|
||
"might want to try reading; the second all the sockets you might want to try "
|
||
"writing to, and the last (normally left empty) those that you want to check "
|
||
"for errors. You should note that a socket can go into more than one list. "
|
||
"The ``select`` call is blocking, but you can give it a timeout. This is "
|
||
"generally a sensible thing to do - give it a nice long timeout (say a "
|
||
"minute) unless you have good reason to do otherwise."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:355
|
||
msgid ""
|
||
"In return, you will get three lists. They contain the sockets that are "
|
||
"actually readable, writable and in error. Each of these lists is a subset "
|
||
"(possibly empty) of the corresponding list you passed in."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:359
|
||
msgid ""
|
||
"If a socket is in the output readable list, you can be as-close-to-certain-"
|
||
"as-we-ever-get-in-this-business that a ``recv`` on that socket will return "
|
||
"*something*. Same idea for the writable list. You'll be able to send "
|
||
"*something*. Maybe not all you want to, but *something* is better than "
|
||
"nothing. (Actually, any reasonably healthy socket will return as writable - "
|
||
"it just means outbound network buffer space is available.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:366
|
||
msgid ""
|
||
"If you have a \"server\" socket, put it in the potential_readers list. If it "
|
||
"comes out in the readable list, your ``accept`` will (almost certainly) "
|
||
"work. If you have created a new socket to ``connect`` to someone else, put "
|
||
"it in the potential_writers list. If it shows up in the writable list, you "
|
||
"have a decent chance that it has connected."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:372
|
||
msgid ""
|
||
"Actually, ``select`` can be handy even with blocking sockets. It's one way "
|
||
"of determining whether you will block - the socket returns as readable when "
|
||
"there's something in the buffers. However, this still doesn't help with the "
|
||
"problem of determining whether the other end is done, or just busy with "
|
||
"something else."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:377
|
||
msgid ""
|
||
"**Portability alert**: On Unix, ``select`` works both with the sockets and "
|
||
"files. Don't try this on Windows. On Windows, ``select`` works with sockets "
|
||
"only. Also note that in C, many of the more advanced socket options are done "
|
||
"differently on Windows. In fact, on Windows I usually use threads (which "
|
||
"work very, very well) with my sockets."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:4
|
||
msgid "Sorting HOW TO"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:6
|
||
msgid "Andrew Dalke and Raymond Hettinger"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:7
|
||
msgid "0.1"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:10
|
||
msgid ""
|
||
"Python lists have a built-in :meth:`list.sort` method that modifies the list "
|
||
"in-place. There is also a :func:`sorted` built-in function that builds a "
|
||
"new sorted list from an iterable."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:14
|
||
msgid ""
|
||
"In this document, we explore the various techniques for sorting data using "
|
||
"Python."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:18
|
||
msgid "Sorting Basics"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:20
|
||
msgid ""
|
||
"A simple ascending sort is very easy: just call the :func:`sorted` function. "
|
||
"It returns a new sorted list::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:26
|
||
msgid ""
|
||
"You can also use the :meth:`list.sort` method. It modifies the list in-place "
|
||
"(and returns *None* to avoid confusion). Usually it's less convenient than :"
|
||
"func:`sorted` - but if you don't need the original list, it's slightly more "
|
||
"efficient."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:36
|
||
msgid ""
|
||
"Another difference is that the :meth:`list.sort` method is only defined for "
|
||
"lists. In contrast, the :func:`sorted` function accepts any iterable."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:43
|
||
msgid "Key Functions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:45
|
||
msgid ""
|
||
"Both :meth:`list.sort` and :func:`sorted` have a *key* parameter to specify "
|
||
"a function to be called on each list element prior to making comparisons."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:48
|
||
msgid "For example, here's a case-insensitive string comparison:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:53
|
||
msgid ""
|
||
"The value of the *key* parameter should be a function that takes a single "
|
||
"argument and returns a key to use for sorting purposes. This technique is "
|
||
"fast because the key function is called exactly once for each input record."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:57
|
||
msgid ""
|
||
"A common pattern is to sort complex objects using some of the object's "
|
||
"indices as keys. For example:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:68
|
||
msgid ""
|
||
"The same technique works for objects with named attributes. For example:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:87
|
||
msgid "Operator Module Functions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:89
|
||
msgid ""
|
||
"The key-function patterns shown above are very common, so Python provides "
|
||
"convenience functions to make accessor functions easier and faster. The :mod:"
|
||
"`operator` module has :func:`~operator.itemgetter`, :func:`~operator."
|
||
"attrgetter`, and a :func:`~operator.methodcaller` function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:94
|
||
msgid "Using those functions, the above examples become simpler and faster:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:104
|
||
msgid ""
|
||
"The operator module functions allow multiple levels of sorting. For example, "
|
||
"to sort by *grade* then by *age*:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:114
|
||
msgid "Ascending and Descending"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:116
|
||
msgid ""
|
||
"Both :meth:`list.sort` and :func:`sorted` accept a *reverse* parameter with "
|
||
"a boolean value. This is used to flag descending sorts. For example, to get "
|
||
"the student data in reverse *age* order:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:127
|
||
msgid "Sort Stability and Complex Sorts"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:129
|
||
msgid ""
|
||
"Sorts are guaranteed to be `stable <https://en.wikipedia.org/wiki/"
|
||
"Sorting_algorithm#Stability>`_\\. That means that when multiple records have "
|
||
"the same key, their original order is preserved."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:137
|
||
msgid ""
|
||
"Notice how the two records for *blue* retain their original order so that "
|
||
"``('blue', 1)`` is guaranteed to precede ``('blue', 2)``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:140
|
||
msgid ""
|
||
"This wonderful property lets you build complex sorts in a series of sorting "
|
||
"steps. For example, to sort the student data by descending *grade* and then "
|
||
"ascending *age*, do the *age* sort first and then sort again using *grade*:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:148
|
||
msgid ""
|
||
"The `Timsort <https://en.wikipedia.org/wiki/Timsort>`_ algorithm used in "
|
||
"Python does multiple sorts efficiently because it can take advantage of any "
|
||
"ordering already present in a dataset."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:153
|
||
msgid "The Old Way Using Decorate-Sort-Undecorate"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:155
|
||
msgid "This idiom is called Decorate-Sort-Undecorate after its three steps:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:157
|
||
msgid ""
|
||
"First, the initial list is decorated with new values that control the sort "
|
||
"order."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:159
|
||
msgid "Second, the decorated list is sorted."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:161
|
||
msgid ""
|
||
"Finally, the decorations are removed, creating a list that contains only the "
|
||
"initial values in the new order."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:164
|
||
msgid ""
|
||
"For example, to sort the student data by *grade* using the DSU approach:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:171
|
||
msgid ""
|
||
"This idiom works because tuples are compared lexicographically; the first "
|
||
"items are compared; if they are the same then the second items are compared, "
|
||
"and so on."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:175
|
||
msgid ""
|
||
"It is not strictly necessary in all cases to include the index *i* in the "
|
||
"decorated list, but including it gives two benefits:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:178
|
||
msgid ""
|
||
"The sort is stable -- if two items have the same key, their order will be "
|
||
"preserved in the sorted list."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:181
|
||
msgid ""
|
||
"The original items do not have to be comparable because the ordering of the "
|
||
"decorated tuples will be determined by at most the first two items. So for "
|
||
"example the original list could contain complex numbers which cannot be "
|
||
"sorted directly."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:186
|
||
msgid ""
|
||
"Another name for this idiom is `Schwartzian transform <https://en.wikipedia."
|
||
"org/wiki/Schwartzian_transform>`_\\, after Randal L. Schwartz, who "
|
||
"popularized it among Perl programmers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:190
|
||
msgid ""
|
||
"Now that Python sorting provides key-functions, this technique is not often "
|
||
"needed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:194
|
||
msgid "The Old Way Using the *cmp* Parameter"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:196
|
||
msgid ""
|
||
"Many constructs given in this HOWTO assume Python 2.4 or later. Before that, "
|
||
"there was no :func:`sorted` builtin and :meth:`list.sort` took no keyword "
|
||
"arguments. Instead, all of the Py2.x versions supported a *cmp* parameter to "
|
||
"handle user specified comparison functions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:201
|
||
msgid ""
|
||
"In Py3.0, the *cmp* parameter was removed entirely (as part of a larger "
|
||
"effort to simplify and unify the language, eliminating the conflict between "
|
||
"rich comparisons and the :meth:`__cmp__` magic method)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:205
|
||
msgid ""
|
||
"In Py2.x, sort allowed an optional function which can be called for doing "
|
||
"the comparisons. That function should take two arguments to be compared and "
|
||
"then return a negative value for less-than, return zero if they are equal, "
|
||
"or return a positive value for greater-than. For example, we can do:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:215
|
||
msgid "Or you can reverse the order of comparison with:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:222
|
||
msgid ""
|
||
"When porting code from Python 2.x to 3.x, the situation can arise when you "
|
||
"have the user supplying a comparison function and you need to convert that "
|
||
"to a key function. The following wrapper makes that easy to do::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:245
|
||
msgid "To convert to a key function, just wrap the old comparison function:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:256
|
||
msgid ""
|
||
"In Python 3.2, the :func:`functools.cmp_to_key` function was added to the :"
|
||
"mod:`functools` module in the standard library."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:260
|
||
msgid "Odd and Ends"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:262
|
||
msgid ""
|
||
"For locale aware sorting, use :func:`locale.strxfrm` for a key function or :"
|
||
"func:`locale.strcoll` for a comparison function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:265
|
||
msgid ""
|
||
"The *reverse* parameter still maintains sort stability (so that records with "
|
||
"equal keys retain the original order). Interestingly, that effect can be "
|
||
"simulated without the parameter by using the builtin :func:`reversed` "
|
||
"function twice:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:277
|
||
msgid ""
|
||
"The sort routines are guaranteed to use :meth:`__lt__` when making "
|
||
"comparisons between two objects. So, it is easy to add a standard sort order "
|
||
"to a class by defining an :meth:`__lt__` method::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:285
|
||
msgid ""
|
||
"Key functions need not depend directly on the objects being sorted. A key "
|
||
"function can also access external resources. For instance, if the student "
|
||
"grades are stored in a dictionary, they can be used to sort a separate list "
|
||
"of student names:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:5
|
||
msgid "Unicode HOWTO"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:7
|
||
msgid "1.12"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:9
|
||
msgid ""
|
||
"This HOWTO discusses Python support for Unicode, and explains various "
|
||
"problems that people commonly encounter when trying to work with Unicode."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:14
|
||
msgid "Introduction to Unicode"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:17
|
||
msgid "History of Character Codes"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:19
|
||
msgid ""
|
||
"In 1968, the American Standard Code for Information Interchange, better "
|
||
"known by its acronym ASCII, was standardized. ASCII defined numeric codes "
|
||
"for various characters, with the numeric values running from 0 to 127. For "
|
||
"example, the lowercase letter 'a' is assigned 97 as its code value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:24
|
||
msgid ""
|
||
"ASCII was an American-developed standard, so it only defined unaccented "
|
||
"characters. There was an 'e', but no 'é' or 'Í'. This meant that languages "
|
||
"which required accented characters couldn't be faithfully represented in "
|
||
"ASCII. (Actually the missing accents matter for English, too, which contains "
|
||
"words such as 'naïve' and 'café', and some publications have house styles "
|
||
"which require spellings such as 'coöperate'.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:31
|
||
msgid ""
|
||
"For a while people just wrote programs that didn't display accents. In the "
|
||
"mid-1980s an Apple II BASIC program written by a French speaker might have "
|
||
"lines like these::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:38
|
||
msgid ""
|
||
"Those messages should contain accents (terminée, paramètre, enregistrés) and "
|
||
"they just look wrong to someone who can read French."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:41
|
||
msgid ""
|
||
"In the 1980s, almost all personal computers were 8-bit, meaning that bytes "
|
||
"could hold values ranging from 0 to 255. ASCII codes only went up to 127, "
|
||
"so some machines assigned values between 128 and 255 to accented "
|
||
"characters. Different machines had different codes, however, which led to "
|
||
"problems exchanging files. Eventually various commonly used sets of values "
|
||
"for the 128--255 range emerged. Some were true standards, defined by the "
|
||
"International Standards Organization, and some were *de facto* conventions "
|
||
"that were invented by one company or another and managed to catch on."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:50
|
||
msgid ""
|
||
"255 characters aren't very many. For example, you can't fit both the "
|
||
"accented characters used in Western Europe and the Cyrillic alphabet used "
|
||
"for Russian into the 128--255 range because there are more than 128 such "
|
||
"characters."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:54
|
||
msgid ""
|
||
"You could write files using different codes (all your Russian files in a "
|
||
"coding system called KOI8, all your French files in a different coding "
|
||
"system called Latin1), but what if you wanted to write a French document "
|
||
"that quotes some Russian text? In the 1980s people began to want to solve "
|
||
"this problem, and the Unicode standardization effort began."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:60
|
||
msgid ""
|
||
"Unicode started out using 16-bit characters instead of 8-bit characters. 16 "
|
||
"bits means you have 2^16 = 65,536 distinct values available, making it "
|
||
"possible to represent many different characters from many different "
|
||
"alphabets; an initial goal was to have Unicode contain the alphabets for "
|
||
"every single human language. It turns out that even 16 bits isn't enough to "
|
||
"meet that goal, and the modern Unicode specification uses a wider range of "
|
||
"codes, 0 through 1,114,111 ( ``0x10FFFF`` in base 16)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:68
|
||
msgid ""
|
||
"There's a related ISO standard, ISO 10646. Unicode and ISO 10646 were "
|
||
"originally separate efforts, but the specifications were merged with the 1.1 "
|
||
"revision of Unicode."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:72
|
||
msgid ""
|
||
"(This discussion of Unicode's history is highly simplified. The precise "
|
||
"historical details aren't necessary for understanding how to use Unicode "
|
||
"effectively, but if you're curious, consult the Unicode consortium site "
|
||
"listed in the References or the `Wikipedia entry for Unicode <https://en."
|
||
"wikipedia.org/wiki/Unicode#History>`_ for more information.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:81
|
||
msgid "Definitions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:83
|
||
msgid ""
|
||
"A **character** is the smallest possible component of a text. 'A', 'B', "
|
||
"'C', etc., are all different characters. So are 'È' and 'Í'. Characters "
|
||
"are abstractions, and vary depending on the language or context you're "
|
||
"talking about. For example, the symbol for ohms (Ω) is usually drawn much "
|
||
"like the capital letter omega (Ω) in the Greek alphabet (they may even be "
|
||
"the same in some fonts), but these are two different characters that have "
|
||
"different meanings."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:91
|
||
msgid ""
|
||
"The Unicode standard describes how characters are represented by **code "
|
||
"points**. A code point is an integer value, usually denoted in base 16. In "
|
||
"the standard, a code point is written using the notation ``U+12CA`` to mean "
|
||
"the character with value ``0x12ca`` (4,810 decimal). The Unicode standard "
|
||
"contains a lot of tables listing characters and their corresponding code "
|
||
"points:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:105
|
||
msgid ""
|
||
"Strictly, these definitions imply that it's meaningless to say 'this is "
|
||
"character ``U+12CA``'. ``U+12CA`` is a code point, which represents some "
|
||
"particular character; in this case, it represents the character 'ETHIOPIC "
|
||
"SYLLABLE WI'. In informal contexts, this distinction between code points "
|
||
"and characters will sometimes be forgotten."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:111
|
||
msgid ""
|
||
"A character is represented on a screen or on paper by a set of graphical "
|
||
"elements that's called a **glyph**. The glyph for an uppercase A, for "
|
||
"example, is two diagonal strokes and a horizontal stroke, though the exact "
|
||
"details will depend on the font being used. Most Python code doesn't need "
|
||
"to worry about glyphs; figuring out the correct glyph to display is "
|
||
"generally the job of a GUI toolkit or a terminal's font renderer."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:120
|
||
msgid "Encodings"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:122
|
||
msgid ""
|
||
"To summarize the previous section: a Unicode string is a sequence of code "
|
||
"points, which are numbers from 0 through ``0x10FFFF`` (1,114,111 decimal). "
|
||
"This sequence needs to be represented as a set of bytes (meaning, values "
|
||
"from 0 through 255) in memory. The rules for translating a Unicode string "
|
||
"into a sequence of bytes are called an **encoding**."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:128
|
||
msgid ""
|
||
"The first encoding you might think of is an array of 32-bit integers. In "
|
||
"this representation, the string \"Python\" would look like this:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:137
|
||
msgid ""
|
||
"This representation is straightforward but using it presents a number of "
|
||
"problems."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:140
|
||
msgid "It's not portable; different processors order the bytes differently."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:142
|
||
msgid ""
|
||
"It's very wasteful of space. In most texts, the majority of the code points "
|
||
"are less than 127, or less than 255, so a lot of space is occupied by "
|
||
"``0x00`` bytes. The above string takes 24 bytes compared to the 6 bytes "
|
||
"needed for an ASCII representation. Increased RAM usage doesn't matter too "
|
||
"much (desktop computers have gigabytes of RAM, and strings aren't usually "
|
||
"that large), but expanding our usage of disk and network bandwidth by a "
|
||
"factor of 4 is intolerable."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:150
|
||
msgid ""
|
||
"It's not compatible with existing C functions such as ``strlen()``, so a new "
|
||
"family of wide string functions would need to be used."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:153
|
||
msgid ""
|
||
"Many Internet standards are defined in terms of textual data, and can't "
|
||
"handle content with embedded zero bytes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:156
|
||
msgid ""
|
||
"Generally people don't use this encoding, instead choosing other encodings "
|
||
"that are more efficient and convenient. UTF-8 is probably the most commonly "
|
||
"supported encoding; it will be discussed below."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:160
|
||
msgid ""
|
||
"Encodings don't have to handle every possible Unicode character, and most "
|
||
"encodings don't. The rules for converting a Unicode string into the ASCII "
|
||
"encoding, for example, are simple; for each code point:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:164
|
||
msgid ""
|
||
"If the code point is < 128, each byte is the same as the value of the code "
|
||
"point."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:167
|
||
msgid ""
|
||
"If the code point is 128 or greater, the Unicode string can't be represented "
|
||
"in this encoding. (Python raises a :exc:`UnicodeEncodeError` exception in "
|
||
"this case.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:171
|
||
msgid ""
|
||
"Latin-1, also known as ISO-8859-1, is a similar encoding. Unicode code "
|
||
"points 0--255 are identical to the Latin-1 values, so converting to this "
|
||
"encoding simply requires converting code points to byte values; if a code "
|
||
"point larger than 255 is encountered, the string can't be encoded into "
|
||
"Latin-1."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:176
|
||
msgid ""
|
||
"Encodings don't have to be simple one-to-one mappings like Latin-1. "
|
||
"Consider IBM's EBCDIC, which was used on IBM mainframes. Letter values "
|
||
"weren't in one block: 'a' through 'i' had values from 129 to 137, but 'j' "
|
||
"through 'r' were 145 through 153. If you wanted to use EBCDIC as an "
|
||
"encoding, you'd probably use some sort of lookup table to perform the "
|
||
"conversion, but this is largely an internal detail."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:183
|
||
msgid ""
|
||
"UTF-8 is one of the most commonly used encodings. UTF stands for \"Unicode "
|
||
"Transformation Format\", and the '8' means that 8-bit numbers are used in "
|
||
"the encoding. (There are also a UTF-16 and UTF-32 encodings, but they are "
|
||
"less frequently used than UTF-8.) UTF-8 uses the following rules:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:188
|
||
msgid ""
|
||
"If the code point is < 128, it's represented by the corresponding byte value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:189
|
||
msgid ""
|
||
"If the code point is >= 128, it's turned into a sequence of two, three, or "
|
||
"four bytes, where each byte of the sequence is between 128 and 255."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:192
|
||
msgid "UTF-8 has several convenient properties:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:194
|
||
msgid "It can handle any Unicode code point."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:195
|
||
msgid ""
|
||
"A Unicode string is turned into a sequence of bytes containing no embedded "
|
||
"zero bytes. This avoids byte-ordering issues, and means UTF-8 strings can "
|
||
"be processed by C functions such as ``strcpy()`` and sent through protocols "
|
||
"that can't handle zero bytes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:199
|
||
msgid "A string of ASCII text is also valid UTF-8 text."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:200
|
||
msgid ""
|
||
"UTF-8 is fairly compact; the majority of commonly used characters can be "
|
||
"represented with one or two bytes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:202
|
||
msgid ""
|
||
"If bytes are corrupted or lost, it's possible to determine the start of the "
|
||
"next UTF-8-encoded code point and resynchronize. It's also unlikely that "
|
||
"random 8-bit data will look like valid UTF-8."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:211
|
||
msgid ""
|
||
"The `Unicode Consortium site <http://www.unicode.org>`_ has character "
|
||
"charts, a glossary, and PDF versions of the Unicode specification. Be "
|
||
"prepared for some difficult reading. `A chronology <http://www.unicode.org/"
|
||
"history/>`_ of the origin and development of Unicode is also available on "
|
||
"the site."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:216
|
||
msgid ""
|
||
"To help understand the standard, Jukka Korpela has written `an introductory "
|
||
"guide <https://www.cs.tut.fi/~jkorpela/unicode/guide.html>`_ to reading the "
|
||
"Unicode character tables."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:220
|
||
msgid ""
|
||
"Another `good introductory article <http://www.joelonsoftware.com/articles/"
|
||
"Unicode.html>`_ was written by Joel Spolsky. If this introduction didn't "
|
||
"make things clear to you, you should try reading this alternate article "
|
||
"before continuing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:225
|
||
msgid ""
|
||
"Wikipedia entries are often helpful; see the entries for \"`character "
|
||
"encoding <https://en.wikipedia.org/wiki/Character_encoding>`_\" and `UTF-8 "
|
||
"<https://en.wikipedia.org/wiki/UTF-8>`_, for example."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:231
|
||
msgid "Python's Unicode Support"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:233
|
||
msgid ""
|
||
"Now that you've learned the rudiments of Unicode, we can look at Python's "
|
||
"Unicode features."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:237
|
||
msgid "The String Type"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:239
|
||
msgid ""
|
||
"Since Python 3.0, the language features a :class:`str` type that contain "
|
||
"Unicode characters, meaning any string created using ``\"unicode rocks!\"``, "
|
||
"``'unicode rocks!'``, or the triple-quoted string syntax is stored as "
|
||
"Unicode."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:243
|
||
msgid ""
|
||
"The default encoding for Python source code is UTF-8, so you can simply "
|
||
"include a Unicode character in a string literal::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:253
|
||
msgid ""
|
||
"You can use a different encoding from UTF-8 by putting a specially-formatted "
|
||
"comment as the first or second line of the source code::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:258
|
||
msgid ""
|
||
"Side note: Python 3 also supports using Unicode characters in identifiers::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:264
|
||
msgid ""
|
||
"If you can't enter a particular character in your editor or want to keep the "
|
||
"source code ASCII-only for some reason, you can also use escape sequences in "
|
||
"string literals. (Depending on your system, you may see the actual capital-"
|
||
"delta glyph instead of a \\u escape.) ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:276
|
||
msgid ""
|
||
"In addition, one can create a string using the :func:`~bytes.decode` method "
|
||
"of :class:`bytes`. This method takes an *encoding* argument, such as "
|
||
"``UTF-8``, and optionally an *errors* argument."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:280
|
||
msgid ""
|
||
"The *errors* argument specifies the response when the input string can't be "
|
||
"converted according to the encoding's rules. Legal values for this argument "
|
||
"are ``'strict'`` (raise a :exc:`UnicodeDecodeError` exception), "
|
||
"``'replace'`` (use ``U+FFFD``, ``REPLACEMENT CHARACTER``), ``'ignore'`` "
|
||
"(just leave the character out of the Unicode result), or "
|
||
"``'backslashreplace'`` (inserts a ``\\xNN`` escape sequence). The following "
|
||
"examples show the differences::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:300
|
||
msgid ""
|
||
"Encodings are specified as strings containing the encoding's name. Python "
|
||
"3.2 comes with roughly 100 different encodings; see the Python Library "
|
||
"Reference at :ref:`standard-encodings` for a list. Some encodings have "
|
||
"multiple names; for example, ``'latin-1'``, ``'iso_8859_1'`` and ``'8859``' "
|
||
"are all synonyms for the same encoding."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:306
|
||
msgid ""
|
||
"One-character Unicode strings can also be created with the :func:`chr` built-"
|
||
"in function, which takes integers and returns a Unicode string of length 1 "
|
||
"that contains the corresponding code point. The reverse operation is the "
|
||
"built-in :func:`ord` function that takes a one-character Unicode string and "
|
||
"returns the code point value::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:318
|
||
msgid "Converting to Bytes"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:320
|
||
msgid ""
|
||
"The opposite method of :meth:`bytes.decode` is :meth:`str.encode`, which "
|
||
"returns a :class:`bytes` representation of the Unicode string, encoded in "
|
||
"the requested *encoding*."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:324
|
||
msgid ""
|
||
"The *errors* parameter is the same as the parameter of the :meth:`~bytes."
|
||
"decode` method but supports a few more possible handlers. As well as "
|
||
"``'strict'``, ``'ignore'``, and ``'replace'`` (which in this case inserts a "
|
||
"question mark instead of the unencodable character), there is also "
|
||
"``'xmlcharrefreplace'`` (inserts an XML character reference), "
|
||
"``backslashreplace`` (inserts a ``\\uNNNN`` escape sequence) and "
|
||
"``namereplace`` (inserts a ``\\N{...}`` escape sequence)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:332
|
||
msgid "The following example shows the different results::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:353
|
||
msgid ""
|
||
"The low-level routines for registering and accessing the available encodings "
|
||
"are found in the :mod:`codecs` module. Implementing new encodings also "
|
||
"requires understanding the :mod:`codecs` module. However, the encoding and "
|
||
"decoding functions returned by this module are usually more low-level than "
|
||
"is comfortable, and writing new encodings is a specialized task, so the "
|
||
"module won't be covered in this HOWTO."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:362
|
||
msgid "Unicode Literals in Python Source Code"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:364
|
||
msgid ""
|
||
"In Python source code, specific Unicode code points can be written using the "
|
||
"``\\u`` escape sequence, which is followed by four hex digits giving the "
|
||
"code point. The ``\\U`` escape sequence is similar, but expects eight hex "
|
||
"digits, not four::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:376
|
||
msgid ""
|
||
"Using escape sequences for code points greater than 127 is fine in small "
|
||
"doses, but becomes an annoyance if you're using many accented characters, as "
|
||
"you would in a program with messages in French or some other accent-using "
|
||
"language. You can also assemble strings using the :func:`chr` built-in "
|
||
"function, but this is even more tedious."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:382
|
||
msgid ""
|
||
"Ideally, you'd want to be able to write literals in your language's natural "
|
||
"encoding. You could then edit Python source code with your favorite editor "
|
||
"which would display the accented characters naturally, and have the right "
|
||
"characters used at runtime."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:387
|
||
msgid ""
|
||
"Python supports writing source code in UTF-8 by default, but you can use "
|
||
"almost any encoding if you declare the encoding being used. This is done by "
|
||
"including a special comment as either the first or second line of the source "
|
||
"file::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:397
|
||
msgid ""
|
||
"The syntax is inspired by Emacs's notation for specifying variables local to "
|
||
"a file. Emacs supports many different variables, but Python only supports "
|
||
"'coding'. The ``-*-`` symbols indicate to Emacs that the comment is "
|
||
"special; they have no significance to Python but are a convention. Python "
|
||
"looks for ``coding: name`` or ``coding=name`` in the comment."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:403
|
||
msgid ""
|
||
"If you don't include such a comment, the default encoding used will be UTF-8 "
|
||
"as already mentioned. See also :pep:`263` for more information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:408
|
||
msgid "Unicode Properties"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:410
|
||
msgid ""
|
||
"The Unicode specification includes a database of information about code "
|
||
"points. For each defined code point, the information includes the "
|
||
"character's name, its category, the numeric value if applicable (Unicode has "
|
||
"characters representing the Roman numerals and fractions such as one-third "
|
||
"and four-fifths). There are also properties related to the code point's use "
|
||
"in bidirectional text and other display-related properties."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:417
|
||
msgid ""
|
||
"The following program displays some information about several characters, "
|
||
"and prints the numeric value of one particular character::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:431
|
||
msgid "When run, this prints:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:442
|
||
msgid ""
|
||
"The category codes are abbreviations describing the nature of the character. "
|
||
"These are grouped into categories such as \"Letter\", \"Number\", "
|
||
"\"Punctuation\", or \"Symbol\", which in turn are broken up into "
|
||
"subcategories. To take the codes from the above output, ``'Ll'`` means "
|
||
"'Letter, lowercase', ``'No'`` means \"Number, other\", ``'Mn'`` is \"Mark, "
|
||
"nonspacing\", and ``'So'`` is \"Symbol, other\". See `the General Category "
|
||
"Values section of the Unicode Character Database documentation <http://www."
|
||
"unicode.org/reports/tr44/#General_Category_Values>`_ for a list of category "
|
||
"codes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:453
|
||
msgid "Unicode Regular Expressions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:455
|
||
msgid ""
|
||
"The regular expressions supported by the :mod:`re` module can be provided "
|
||
"either as bytes or strings. Some of the special character sequences such as "
|
||
"``\\d`` and ``\\w`` have different meanings depending on whether the pattern "
|
||
"is supplied as bytes or a string. For example, ``\\d`` will match the "
|
||
"characters ``[0-9]`` in bytes but in strings will match any character that's "
|
||
"in the ``'Nd'`` category."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:462
|
||
msgid ""
|
||
"The string in this example has the number 57 written in both Thai and Arabic "
|
||
"numerals::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:472
|
||
msgid ""
|
||
"When executed, ``\\d+`` will match the Thai numerals and print them out. If "
|
||
"you supply the :const:`re.ASCII` flag to :func:`~re.compile`, ``\\d+`` will "
|
||
"match the substring \"57\" instead."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:476
|
||
msgid ""
|
||
"Similarly, ``\\w`` matches a wide variety of Unicode characters but only "
|
||
"``[a-zA-Z0-9_]`` in bytes or if :const:`re.ASCII` is supplied, and ``\\s`` "
|
||
"will match either Unicode whitespace characters or ``[ \\t\\n\\r\\f\\v]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:487
|
||
msgid "Some good alternative discussions of Python's Unicode support are:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:489
|
||
msgid ""
|
||
"`Processing Text Files in Python 3 <http://python-notes.curiousefficiency."
|
||
"org/en/latest/python3/text_file_processing.html>`_, by Nick Coghlan."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:490
|
||
msgid ""
|
||
"`Pragmatic Unicode <http://nedbatchelder.com/text/unipain.html>`_, a PyCon "
|
||
"2012 presentation by Ned Batchelder."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:492
|
||
msgid ""
|
||
"The :class:`str` type is described in the Python library reference at :ref:"
|
||
"`textseq`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:495
|
||
msgid "The documentation for the :mod:`unicodedata` module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:497
|
||
msgid "The documentation for the :mod:`codecs` module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:499
|
||
msgid ""
|
||
"Marc-André Lemburg gave `a presentation titled \"Python and Unicode\" (PDF "
|
||
"slides) <https://downloads.egenix.com/python/Unicode-EPC2002-Talk.pdf>`_ at "
|
||
"EuroPython 2002. The slides are an excellent overview of the design of "
|
||
"Python 2's Unicode features (where the Unicode string type is called "
|
||
"``unicode`` and literals start with ``u``)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:507
|
||
msgid "Reading and Writing Unicode Data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:509
|
||
msgid ""
|
||
"Once you've written some code that works with Unicode data, the next problem "
|
||
"is input/output. How do you get Unicode strings into your program, and how "
|
||
"do you convert Unicode into a form suitable for storage or transmission?"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:513
|
||
msgid ""
|
||
"It's possible that you may not need to do anything depending on your input "
|
||
"sources and output destinations; you should check whether the libraries used "
|
||
"in your application support Unicode natively. XML parsers often return "
|
||
"Unicode data, for example. Many relational databases also support Unicode-"
|
||
"valued columns and can return Unicode values from an SQL query."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:519
|
||
msgid ""
|
||
"Unicode data is usually converted to a particular encoding before it gets "
|
||
"written to disk or sent over a socket. It's possible to do all the work "
|
||
"yourself: open a file, read an 8-bit bytes object from it, and convert the "
|
||
"bytes with ``bytes.decode(encoding)``. However, the manual approach is not "
|
||
"recommended."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:524
|
||
msgid ""
|
||
"One problem is the multi-byte nature of encodings; one Unicode character can "
|
||
"be represented by several bytes. If you want to read the file in arbitrary-"
|
||
"sized chunks (say, 1024 or 4096 bytes), you need to write error-handling "
|
||
"code to catch the case where only part of the bytes encoding a single "
|
||
"Unicode character are read at the end of a chunk. One solution would be to "
|
||
"read the entire file into memory and then perform the decoding, but that "
|
||
"prevents you from working with files that are extremely large; if you need "
|
||
"to read a 2 GiB file, you need 2 GiB of RAM. (More, really, since for at "
|
||
"least a moment you'd need to have both the encoded string and its Unicode "
|
||
"version in memory.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:534
|
||
msgid ""
|
||
"The solution would be to use the low-level decoding interface to catch the "
|
||
"case of partial coding sequences. The work of implementing this has already "
|
||
"been done for you: the built-in :func:`open` function can return a file-like "
|
||
"object that assumes the file's contents are in a specified encoding and "
|
||
"accepts Unicode parameters for methods such as :meth:`~io.TextIOBase.read` "
|
||
"and :meth:`~io.TextIOBase.write`. This works through :func:`open`\\'s "
|
||
"*encoding* and *errors* parameters which are interpreted just like those in :"
|
||
"meth:`str.encode` and :meth:`bytes.decode`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:543
|
||
msgid "Reading Unicode from a file is therefore simple::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:549
|
||
msgid ""
|
||
"It's also possible to open files in update mode, allowing both reading and "
|
||
"writing::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:557
|
||
msgid ""
|
||
"The Unicode character ``U+FEFF`` is used as a byte-order mark (BOM), and is "
|
||
"often written as the first character of a file in order to assist with "
|
||
"autodetection of the file's byte ordering. Some encodings, such as UTF-16, "
|
||
"expect a BOM to be present at the start of a file; when such an encoding is "
|
||
"used, the BOM will be automatically written as the first character and will "
|
||
"be silently dropped when the file is read. There are variants of these "
|
||
"encodings, such as 'utf-16-le' and 'utf-16-be' for little-endian and big-"
|
||
"endian encodings, that specify one particular byte ordering and don't skip "
|
||
"the BOM."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:566
|
||
msgid ""
|
||
"In some areas, it is also convention to use a \"BOM\" at the start of UTF-8 "
|
||
"encoded files; the name is misleading since UTF-8 is not byte-order "
|
||
"dependent. The mark simply announces that the file is encoded in UTF-8. Use "
|
||
"the 'utf-8-sig' codec to automatically skip the mark if present for reading "
|
||
"such files."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:574
|
||
msgid "Unicode filenames"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:576
|
||
msgid ""
|
||
"Most of the operating systems in common use today support filenames that "
|
||
"contain arbitrary Unicode characters. Usually this is implemented by "
|
||
"converting the Unicode string into some encoding that varies depending on "
|
||
"the system. For example, Mac OS X uses UTF-8 while Windows uses a "
|
||
"configurable encoding; on Windows, Python uses the name \"mbcs\" to refer to "
|
||
"whatever the currently configured encoding is. On Unix systems, there will "
|
||
"only be a filesystem encoding if you've set the ``LANG`` or ``LC_CTYPE`` "
|
||
"environment variables; if you haven't, the default encoding is UTF-8."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:585
|
||
msgid ""
|
||
"The :func:`sys.getfilesystemencoding` function returns the encoding to use "
|
||
"on your current system, in case you want to do the encoding manually, but "
|
||
"there's not much reason to bother. When opening a file for reading or "
|
||
"writing, you can usually just provide the Unicode string as the filename, "
|
||
"and it will be automatically converted to the right encoding for you::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:595
|
||
msgid ""
|
||
"Functions in the :mod:`os` module such as :func:`os.stat` will also accept "
|
||
"Unicode filenames."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:598
|
||
msgid ""
|
||
"The :func:`os.listdir` function returns filenames and raises an issue: "
|
||
"should it return the Unicode version of filenames, or should it return bytes "
|
||
"containing the encoded versions? :func:`os.listdir` will do both, depending "
|
||
"on whether you provided the directory path as bytes or a Unicode string. If "
|
||
"you pass a Unicode string as the path, filenames will be decoded using the "
|
||
"filesystem's encoding and a list of Unicode strings will be returned, while "
|
||
"passing a byte path will return the filenames as bytes. For example, "
|
||
"assuming the default filesystem encoding is UTF-8, running the following "
|
||
"program::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:616
|
||
msgid "will produce the following output:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:624
|
||
msgid ""
|
||
"The first list contains UTF-8-encoded filenames, and the second list "
|
||
"contains the Unicode versions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:627
|
||
msgid ""
|
||
"Note that on most occasions, the Unicode APIs should be used. The bytes "
|
||
"APIs should only be used on systems where undecodable file names can be "
|
||
"present, i.e. Unix systems."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:633
|
||
msgid "Tips for Writing Unicode-aware Programs"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:635
|
||
msgid ""
|
||
"This section provides some suggestions on writing software that deals with "
|
||
"Unicode."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:638
|
||
msgid "The most important tip is:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:640
|
||
msgid ""
|
||
"Software should only work with Unicode strings internally, decoding the "
|
||
"input data as soon as possible and encoding the output only at the end."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:643
|
||
msgid ""
|
||
"If you attempt to write processing functions that accept both Unicode and "
|
||
"byte strings, you will find your program vulnerable to bugs wherever you "
|
||
"combine the two different kinds of strings. There is no automatic encoding "
|
||
"or decoding: if you do e.g. ``str + bytes``, a :exc:`TypeError` will be "
|
||
"raised."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:648
|
||
msgid ""
|
||
"When using data coming from a web browser or some other untrusted source, a "
|
||
"common technique is to check for illegal characters in a string before using "
|
||
"the string in a generated command line or storing it in a database. If "
|
||
"you're doing this, be careful to check the decoded string, not the encoded "
|
||
"bytes data; some encodings may have interesting properties, such as not "
|
||
"being bijective or not being fully ASCII-compatible. This is especially "
|
||
"true if the input data also specifies the encoding, since the attacker can "
|
||
"then choose a clever way to hide malicious text in the encoded bytestream."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:659
|
||
msgid "Converting Between File Encodings"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:661
|
||
msgid ""
|
||
"The :class:`~codecs.StreamRecoder` class can transparently convert between "
|
||
"encodings, taking a stream that returns data in encoding #1 and behaving "
|
||
"like a stream returning data in encoding #2."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:665
|
||
msgid ""
|
||
"For example, if you have an input file *f* that's in Latin-1, you can wrap "
|
||
"it with a :class:`~codecs.StreamRecoder` to return bytes encoded in UTF-8::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:679
|
||
msgid "Files in an Unknown Encoding"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:681
|
||
msgid ""
|
||
"What can you do if you need to make a change to a file, but don't know the "
|
||
"file's encoding? If you know the encoding is ASCII-compatible and only want "
|
||
"to examine or modify the ASCII parts, you can open the file with the "
|
||
"``surrogateescape`` error handler::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:695
|
||
msgid ""
|
||
"The ``surrogateescape`` error handler will decode any non-ASCII bytes as "
|
||
"code points in the Unicode Private Use Area ranging from U+DC80 to U+DCFF. "
|
||
"These private code points will then be turned back into the same bytes when "
|
||
"the ``surrogateescape`` error handler is used when encoding the data and "
|
||
"writing it back out."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:705
|
||
msgid ""
|
||
"One section of `Mastering Python 3 Input/Output <http://pyvideo.org/"
|
||
"video/289/pycon-2010--mastering-python-3-i-o>`_, a PyCon 2010 talk by David "
|
||
"Beazley, discusses text processing and binary data handling."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:709
|
||
msgid ""
|
||
"The `PDF slides for Marc-André Lemburg's presentation \"Writing Unicode-"
|
||
"aware Applications in Python\" <https://downloads.egenix.com/python/LSM2005-"
|
||
"Developing-Unicode-aware-applications-in-Python.pdf>`_ discuss questions of "
|
||
"character encodings as well as how to internationalize and localize an "
|
||
"application. These slides cover Python 2.x only."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:715
|
||
msgid ""
|
||
"`The Guts of Unicode in Python <http://pyvideo.org/video/1768/the-guts-of-"
|
||
"unicode-in-python>`_ is a PyCon 2013 talk by Benjamin Peterson that "
|
||
"discusses the internal Unicode representation in Python 3.3."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:722
|
||
msgid "Acknowledgements"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:724
|
||
msgid ""
|
||
"The initial draft of this document was written by Andrew Kuchling. It has "
|
||
"since been revised further by Alexander Belopolsky, Georg Brandl, Andrew "
|
||
"Kuchling, and Ezio Melotti."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:728
|
||
msgid ""
|
||
"Thanks to the following people who have noted errors or offered suggestions "
|
||
"on this article: Éric Araujo, Nicholas Bastin, Nick Coghlan, Marius "
|
||
"Gedminas, Kent Johnson, Ken Krugler, Marc-André Lemburg, Martin von Löwis, "
|
||
"Terry J. Reedy, Chad Whitacre."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:5
|
||
msgid "HOWTO Fetch Internet Resources Using The urllib Package"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:7
|
||
msgid "`Michael Foord <http://www.voidspace.org.uk/python/index.shtml>`_"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:11
|
||
msgid ""
|
||
"There is a French translation of an earlier revision of this HOWTO, "
|
||
"available at `urllib2 - Le Manuel manquant <http://www.voidspace.org.uk/"
|
||
"python/articles/urllib2_francais.shtml>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:0
|
||
msgid "Related Articles"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:22
|
||
msgid ""
|
||
"You may also find useful the following article on fetching web resources "
|
||
"with Python:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:25
|
||
msgid ""
|
||
"`Basic Authentication <http://www.voidspace.org.uk/python/articles/"
|
||
"authentication.shtml>`_"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:27
|
||
msgid "A tutorial on *Basic Authentication*, with examples in Python."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:29
|
||
msgid ""
|
||
"**urllib.request** is a Python module for fetching URLs (Uniform Resource "
|
||
"Locators). It offers a very simple interface, in the form of the *urlopen* "
|
||
"function. This is capable of fetching URLs using a variety of different "
|
||
"protocols. It also offers a slightly more complex interface for handling "
|
||
"common situations - like basic authentication, cookies, proxies and so on. "
|
||
"These are provided by objects called handlers and openers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:36
|
||
msgid ""
|
||
"urllib.request supports fetching URLs for many \"URL schemes\" (identified "
|
||
"by the string before the \":\" in URL - for example \"ftp\" is the URL "
|
||
"scheme of \"ftp://python.org/\") using their associated network protocols (e."
|
||
"g. FTP, HTTP). This tutorial focuses on the most common case, HTTP."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:41
|
||
msgid ""
|
||
"For straightforward situations *urlopen* is very easy to use. But as soon as "
|
||
"you encounter errors or non-trivial cases when opening HTTP URLs, you will "
|
||
"need some understanding of the HyperText Transfer Protocol. The most "
|
||
"comprehensive and authoritative reference to HTTP is :rfc:`2616`. This is a "
|
||
"technical document and not intended to be easy to read. This HOWTO aims to "
|
||
"illustrate using *urllib*, with enough detail about HTTP to help you "
|
||
"through. It is not intended to replace the :mod:`urllib.request` docs, but "
|
||
"is supplementary to them."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:51
|
||
msgid "Fetching URLs"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:53
|
||
msgid "The simplest way to use urllib.request is as follows::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:59
|
||
msgid ""
|
||
"If you wish to retrieve a resource via URL and store it in a temporary "
|
||
"location, you can do so via the :func:`~urllib.request.urlretrieve` "
|
||
"function::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:66
|
||
msgid ""
|
||
"Many uses of urllib will be that simple (note that instead of an 'http:' URL "
|
||
"we could have used a URL starting with 'ftp:', 'file:', etc.). However, "
|
||
"it's the purpose of this tutorial to explain the more complicated cases, "
|
||
"concentrating on HTTP."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:71
|
||
msgid ""
|
||
"HTTP is based on requests and responses - the client makes requests and "
|
||
"servers send responses. urllib.request mirrors this with a ``Request`` "
|
||
"object which represents the HTTP request you are making. In its simplest "
|
||
"form you create a Request object that specifies the URL you want to fetch. "
|
||
"Calling ``urlopen`` with this Request object returns a response object for "
|
||
"the URL requested. This response is a file-like object, which means you can "
|
||
"for example call ``.read()`` on the response::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:85
|
||
msgid ""
|
||
"Note that urllib.request makes use of the same Request interface to handle "
|
||
"all URL schemes. For example, you can make an FTP request like so::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:90
|
||
msgid ""
|
||
"In the case of HTTP, there are two extra things that Request objects allow "
|
||
"you to do: First, you can pass data to be sent to the server. Second, you "
|
||
"can pass extra information (\"metadata\") *about* the data or the about "
|
||
"request itself, to the server - this information is sent as HTTP \"headers"
|
||
"\". Let's look at each of these in turn."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:97
|
||
msgid "Data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:99
|
||
msgid ""
|
||
"Sometimes you want to send data to a URL (often the URL will refer to a CGI "
|
||
"(Common Gateway Interface) script or other web application). With HTTP, this "
|
||
"is often done using what's known as a **POST** request. This is often what "
|
||
"your browser does when you submit a HTML form that you filled in on the web. "
|
||
"Not all POSTs have to come from forms: you can use a POST to transmit "
|
||
"arbitrary data to your own application. In the common case of HTML forms, "
|
||
"the data needs to be encoded in a standard way, and then passed to the "
|
||
"Request object as the ``data`` argument. The encoding is done using a "
|
||
"function from the :mod:`urllib.parse` library. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:123
|
||
msgid ""
|
||
"Note that other encodings are sometimes required (e.g. for file upload from "
|
||
"HTML forms - see `HTML Specification, Form Submission <https://www.w3.org/TR/"
|
||
"REC-html40/interact/forms.html#h-17.13>`_ for more details)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:128
|
||
msgid ""
|
||
"If you do not pass the ``data`` argument, urllib uses a **GET** request. One "
|
||
"way in which GET and POST requests differ is that POST requests often have "
|
||
"\"side-effects\": they change the state of the system in some way (for "
|
||
"example by placing an order with the website for a hundredweight of tinned "
|
||
"spam to be delivered to your door). Though the HTTP standard makes it clear "
|
||
"that POSTs are intended to *always* cause side-effects, and GET requests "
|
||
"*never* to cause side-effects, nothing prevents a GET request from having "
|
||
"side-effects, nor a POST requests from having no side-effects. Data can also "
|
||
"be passed in an HTTP GET request by encoding it in the URL itself."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:138
|
||
msgid "This is done as follows::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:153
|
||
msgid ""
|
||
"Notice that the full URL is created by adding a ``?`` to the URL, followed "
|
||
"by the encoded values."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:157
|
||
msgid "Headers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:159
|
||
msgid ""
|
||
"We'll discuss here one particular HTTP header, to illustrate how to add "
|
||
"headers to your HTTP request."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:162
|
||
msgid ""
|
||
"Some websites [#]_ dislike being browsed by programs, or send different "
|
||
"versions to different browsers [#]_. By default urllib identifies itself as "
|
||
"``Python-urllib/x.y`` (where ``x`` and ``y`` are the major and minor version "
|
||
"numbers of the Python release, e.g. ``Python-urllib/2.5``), which may "
|
||
"confuse the site, or just plain not work. The way a browser identifies "
|
||
"itself is through the ``User-Agent`` header [#]_. When you create a Request "
|
||
"object you can pass a dictionary of headers in. The following example makes "
|
||
"the same request as above, but identifies itself as a version of Internet "
|
||
"Explorer [#]_. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:189
|
||
msgid ""
|
||
"The response also has two useful methods. See the section on `info and "
|
||
"geturl`_ which comes after we have a look at what happens when things go "
|
||
"wrong."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:194
|
||
msgid "Handling Exceptions"
|
||
msgstr "Gestion des exceptions"
|
||
|
||
#: ../Doc/howto/urllib2.rst:196
|
||
msgid ""
|
||
"*urlopen* raises :exc:`URLError` when it cannot handle a response (though as "
|
||
"usual with Python APIs, built-in exceptions such as :exc:`ValueError`, :exc:"
|
||
"`TypeError` etc. may also be raised)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:200
|
||
msgid ""
|
||
":exc:`HTTPError` is the subclass of :exc:`URLError` raised in the specific "
|
||
"case of HTTP URLs."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:203
|
||
msgid "The exception classes are exported from the :mod:`urllib.error` module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:206
|
||
msgid "URLError"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:208
|
||
msgid ""
|
||
"Often, URLError is raised because there is no network connection (no route "
|
||
"to the specified server), or the specified server doesn't exist. In this "
|
||
"case, the exception raised will have a 'reason' attribute, which is a tuple "
|
||
"containing an error code and a text error message."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:213 ../Doc/howto/urllib2.rst:460
|
||
msgid "e.g. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:224
|
||
msgid "HTTPError"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:226
|
||
msgid ""
|
||
"Every HTTP response from the server contains a numeric \"status code\". "
|
||
"Sometimes the status code indicates that the server is unable to fulfil the "
|
||
"request. The default handlers will handle some of these responses for you "
|
||
"(for example, if the response is a \"redirection\" that requests the client "
|
||
"fetch the document from a different URL, urllib will handle that for you). "
|
||
"For those it can't handle, urlopen will raise an :exc:`HTTPError`. Typical "
|
||
"errors include '404' (page not found), '403' (request forbidden), and "
|
||
"'401' (authentication required)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:234
|
||
msgid "See section 10 of RFC 2616 for a reference on all the HTTP error codes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:236
|
||
msgid ""
|
||
"The :exc:`HTTPError` instance raised will have an integer 'code' attribute, "
|
||
"which corresponds to the error sent by the server."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:240
|
||
msgid "Error Codes"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:242
|
||
msgid ""
|
||
"Because the default handlers handle redirects (codes in the 300 range), and "
|
||
"codes in the 100-299 range indicate success, you will usually only see error "
|
||
"codes in the 400-599 range."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:246
|
||
msgid ""
|
||
":attr:`http.server.BaseHTTPRequestHandler.responses` is a useful dictionary "
|
||
"of response codes in that shows all the response codes used by RFC 2616. The "
|
||
"dictionary is reproduced here for convenience ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:318
|
||
msgid ""
|
||
"When an error is raised the server responds by returning an HTTP error code "
|
||
"*and* an error page. You can use the :exc:`HTTPError` instance as a response "
|
||
"on the page returned. This means that as well as the code attribute, it also "
|
||
"has read, geturl, and info, methods as returned by the ``urllib.response`` "
|
||
"module::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:338
|
||
msgid "Wrapping it Up"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:340
|
||
msgid ""
|
||
"So if you want to be prepared for :exc:`HTTPError` *or* :exc:`URLError` "
|
||
"there are two basic approaches. I prefer the second approach."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:344
|
||
msgid "Number 1"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:366
|
||
msgid ""
|
||
"The ``except HTTPError`` *must* come first, otherwise ``except URLError`` "
|
||
"will *also* catch an :exc:`HTTPError`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:370
|
||
msgid "Number 2"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:391
|
||
msgid "info and geturl"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:393
|
||
msgid ""
|
||
"The response returned by urlopen (or the :exc:`HTTPError` instance) has two "
|
||
"useful methods :meth:`info` and :meth:`geturl` and is defined in the module :"
|
||
"mod:`urllib.response`.."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:397
|
||
msgid ""
|
||
"**geturl** - this returns the real URL of the page fetched. This is useful "
|
||
"because ``urlopen`` (or the opener object used) may have followed a "
|
||
"redirect. The URL of the page fetched may not be the same as the URL "
|
||
"requested."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:401
|
||
msgid ""
|
||
"**info** - this returns a dictionary-like object that describes the page "
|
||
"fetched, particularly the headers sent by the server. It is currently an :"
|
||
"class:`http.client.HTTPMessage` instance."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:405
|
||
msgid ""
|
||
"Typical headers include 'Content-length', 'Content-type', and so on. See the "
|
||
"`Quick Reference to HTTP Headers <https://www.cs.tut.fi/~jkorpela/http."
|
||
"html>`_ for a useful listing of HTTP headers with brief explanations of "
|
||
"their meaning and use."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:412
|
||
msgid "Openers and Handlers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:414
|
||
msgid ""
|
||
"When you fetch a URL you use an opener (an instance of the perhaps "
|
||
"confusingly-named :class:`urllib.request.OpenerDirector`). Normally we have "
|
||
"been using the default opener - via ``urlopen`` - but you can create custom "
|
||
"openers. Openers use handlers. All the \"heavy lifting\" is done by the "
|
||
"handlers. Each handler knows how to open URLs for a particular URL scheme "
|
||
"(http, ftp, etc.), or how to handle an aspect of URL opening, for example "
|
||
"HTTP redirections or HTTP cookies."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:422
|
||
msgid ""
|
||
"You will want to create openers if you want to fetch URLs with specific "
|
||
"handlers installed, for example to get an opener that handles cookies, or to "
|
||
"get an opener that does not handle redirections."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:426
|
||
msgid ""
|
||
"To create an opener, instantiate an ``OpenerDirector``, and then call ``."
|
||
"add_handler(some_handler_instance)`` repeatedly."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:429
|
||
msgid ""
|
||
"Alternatively, you can use ``build_opener``, which is a convenience function "
|
||
"for creating opener objects with a single function call. ``build_opener`` "
|
||
"adds several handlers by default, but provides a quick way to add more and/"
|
||
"or override the default handlers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:434
|
||
msgid ""
|
||
"Other sorts of handlers you might want to can handle proxies, "
|
||
"authentication, and other common but slightly specialised situations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:437
|
||
msgid ""
|
||
"``install_opener`` can be used to make an ``opener`` object the (global) "
|
||
"default opener. This means that calls to ``urlopen`` will use the opener you "
|
||
"have installed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:441
|
||
msgid ""
|
||
"Opener objects have an ``open`` method, which can be called directly to "
|
||
"fetch urls in the same way as the ``urlopen`` function: there's no need to "
|
||
"call ``install_opener``, except as a convenience."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:447
|
||
msgid "Basic Authentication"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:449
|
||
msgid ""
|
||
"To illustrate creating and installing a handler we will use the "
|
||
"``HTTPBasicAuthHandler``. For a more detailed discussion of this subject -- "
|
||
"including an explanation of how Basic Authentication works - see the `Basic "
|
||
"Authentication Tutorial <http://www.voidspace.org.uk/python/articles/"
|
||
"authentication.shtml>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:455
|
||
msgid ""
|
||
"When authentication is required, the server sends a header (as well as the "
|
||
"401 error code) requesting authentication. This specifies the "
|
||
"authentication scheme and a 'realm'. The header looks like: ``WWW-"
|
||
"Authenticate: SCHEME realm=\"REALM\"``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:465
|
||
msgid ""
|
||
"The client should then retry the request with the appropriate name and "
|
||
"password for the realm included as a header in the request. This is 'basic "
|
||
"authentication'. In order to simplify this process we can create an instance "
|
||
"of ``HTTPBasicAuthHandler`` and an opener to use this handler."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:470
|
||
msgid ""
|
||
"The ``HTTPBasicAuthHandler`` uses an object called a password manager to "
|
||
"handle the mapping of URLs and realms to passwords and usernames. If you "
|
||
"know what the realm is (from the authentication header sent by the server), "
|
||
"then you can use a ``HTTPPasswordMgr``. Frequently one doesn't care what the "
|
||
"realm is. In that case, it is convenient to use "
|
||
"``HTTPPasswordMgrWithDefaultRealm``. This allows you to specify a default "
|
||
"username and password for a URL. This will be supplied in the absence of you "
|
||
"providing an alternative combination for a specific realm. We indicate this "
|
||
"by providing ``None`` as the realm argument to the ``add_password`` method."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:480
|
||
msgid ""
|
||
"The top-level URL is the first URL that requires authentication. URLs "
|
||
"\"deeper\" than the URL you pass to .add_password() will also match. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:505
|
||
msgid ""
|
||
"In the above example we only supplied our ``HTTPBasicAuthHandler`` to "
|
||
"``build_opener``. By default openers have the handlers for normal situations "
|
||
"-- ``ProxyHandler`` (if a proxy setting such as an :envvar:`http_proxy` "
|
||
"environment variable is set), ``UnknownHandler``, ``HTTPHandler``, "
|
||
"``HTTPDefaultErrorHandler``, ``HTTPRedirectHandler``, ``FTPHandler``, "
|
||
"``FileHandler``, ``DataHandler``, ``HTTPErrorProcessor``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:512
|
||
msgid ""
|
||
"``top_level_url`` is in fact *either* a full URL (including the 'http:' "
|
||
"scheme component and the hostname and optionally the port number) e.g. "
|
||
"\"http://example.com/\" *or* an \"authority\" (i.e. the hostname, optionally "
|
||
"including the port number) e.g. \"example.com\" or \"example.com:8080\" (the "
|
||
"latter example includes a port number). The authority, if present, must NOT "
|
||
"contain the \"userinfo\" component - for example \"joe:password@example.com"
|
||
"\" is not correct."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:522
|
||
msgid "Proxies"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:524
|
||
msgid ""
|
||
"**urllib** will auto-detect your proxy settings and use those. This is "
|
||
"through the ``ProxyHandler``, which is part of the normal handler chain when "
|
||
"a proxy setting is detected. Normally that's a good thing, but there are "
|
||
"occasions when it may not be helpful [#]_. One way to do this is to setup "
|
||
"our own ``ProxyHandler``, with no proxies defined. This is done using "
|
||
"similar steps to setting up a `Basic Authentication`_ handler: ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:537
|
||
msgid ""
|
||
"Currently ``urllib.request`` *does not* support fetching of ``https`` "
|
||
"locations through a proxy. However, this can be enabled by extending urllib."
|
||
"request as shown in the recipe [#]_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:543
|
||
msgid ""
|
||
"``HTTP_PROXY`` will be ignored if a variable ``REQUEST_METHOD`` is set; see "
|
||
"the documentation on :func:`~urllib.request.getproxies`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:548
|
||
msgid "Sockets and Layers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:550
|
||
msgid ""
|
||
"The Python support for fetching resources from the web is layered. urllib "
|
||
"uses the :mod:`http.client` library, which in turn uses the socket library."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:553
|
||
msgid ""
|
||
"As of Python 2.3 you can specify how long a socket should wait for a "
|
||
"response before timing out. This can be useful in applications which have to "
|
||
"fetch web pages. By default the socket module has *no timeout* and can hang. "
|
||
"Currently, the socket timeout is not exposed at the http.client or urllib."
|
||
"request levels. However, you can set the default timeout globally for all "
|
||
"sockets using ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:576
|
||
msgid "Footnotes"
|
||
msgstr "Notes"
|
||
|
||
#: ../Doc/howto/urllib2.rst:578
|
||
msgid "This document was reviewed and revised by John Lee."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:580
|
||
msgid "Google for example."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:581
|
||
msgid ""
|
||
"Browser sniffing is a very bad practise for website design - building sites "
|
||
"using web standards is much more sensible. Unfortunately a lot of sites "
|
||
"still send different versions to different browsers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:584
|
||
msgid ""
|
||
"The user agent for MSIE 6 is *'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT "
|
||
"5.1; SV1; .NET CLR 1.1.4322)'*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:586
|
||
msgid ""
|
||
"For details of more HTTP request headers, see `Quick Reference to HTTP "
|
||
"Headers`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:588
|
||
msgid ""
|
||
"In my case I have to use a proxy to access the internet at work. If you "
|
||
"attempt to fetch *localhost* URLs through this proxy it blocks them. IE is "
|
||
"set to use the proxy, which urllib picks up on. In order to test scripts "
|
||
"with a localhost server, I have to prevent urllib from using the proxy."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:593
|
||
msgid ""
|
||
"urllib opener for SSL proxy (CONNECT method): `ASPN Cookbook Recipe <https://"
|
||
"code.activestate.com/recipes/456195/>`_."
|
||
msgstr ""
|