forked from AFPy/python-docs-fr
11185 lines
406 KiB
Plaintext
11185 lines
406 KiB
Plaintext
# SOME DESCRIPTIVE TITLE.
|
||
# Copyright (C) 1990-2010, 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: PACKAGE VERSION\n"
|
||
"Report-Msgid-Bugs-To: \n"
|
||
"POT-Creation-Date: 2016-03-12 23:37+0100\n"
|
||
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
||
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
||
"Language-Team: LANGUAGE <LL@li.org>\n"
|
||
"Language: \n"
|
||
"MIME-Version: 1.0\n"
|
||
"Content-Type: text/plain; charset=UTF-8\n"
|
||
"Content-Transfer-Encoding: 8bit\n"
|
||
"X-Generator: Translate Toolkit 1.7.0\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. "
|
||
"This was written for argparse in Python 3. A few details are different in 2."
|
||
"x, especially some exception messages, which were improved in 3.x."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:16
|
||
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:24
|
||
msgid "Concepts"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:26
|
||
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:48
|
||
msgid "A few concepts we can learn from the four commands:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:50
|
||
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:53
|
||
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:62
|
||
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:66
|
||
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:72
|
||
msgid "The basics"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:74
|
||
msgid "Let us start with a very simple example which does (almost) nothing::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:80 ../Doc/howto/argparse.rst:188
|
||
#: ../Doc/howto/argparse.rst:209
|
||
msgid "Following is a result of running the code:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:97 ../Doc/howto/argparse.rst:254
|
||
#: ../Doc/howto/argparse.rst:298
|
||
msgid "Here is what is happening:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:99
|
||
msgid ""
|
||
"Running the script without any options results in nothing displayed to "
|
||
"stdout. Not so useful."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:102
|
||
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:105
|
||
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:112
|
||
msgid "Introducing Positional arguments"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:114
|
||
msgid "An example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:122
|
||
msgid "And running the code:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:140
|
||
msgid "Here is what's happening:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:142
|
||
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:146
|
||
msgid "Calling our program now requires us to specify an option."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:148
|
||
msgid ""
|
||
"The :meth:`parse_args` method actually returns some data from the options "
|
||
"specified, in this case, ``echo``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:151
|
||
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:156
|
||
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:167
|
||
msgid "And we get:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:180
|
||
msgid "Now, how about doing something even more useful::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:198
|
||
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:219
|
||
msgid ""
|
||
"That went well. The program now even helpfully quits on bad illegal input "
|
||
"before proceeding."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:224
|
||
msgid "Introducing Optional arguments"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:226
|
||
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:236 ../Doc/howto/argparse.rst:282
|
||
#: ../Doc/howto/argparse.rst:398 ../Doc/howto/argparse.rst:432
|
||
msgid "And the output:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:256
|
||
msgid ""
|
||
"The program is written so as to display something when ``--verbosity`` is "
|
||
"specified and display nothing when not."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:259
|
||
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:265
|
||
msgid "The help message is a bit different."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:267
|
||
msgid ""
|
||
"When using the ``--verbosity`` option, one must also specify some value, any "
|
||
"value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:270
|
||
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:300
|
||
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:307
|
||
msgid ""
|
||
"It complains when you specify a value, in true spirit of what flags actually "
|
||
"are."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:310
|
||
msgid "Notice the different help text."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:314
|
||
msgid "Short options"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:316
|
||
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:328
|
||
msgid "And here goes:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:341
|
||
msgid "Note that the new ability is also reflected in the help text."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:345
|
||
msgid "Combining Positional and Optional arguments"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:347
|
||
msgid "Our program keeps growing in complexity::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:362
|
||
msgid "And now the output:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:376
|
||
msgid "We've brought back a positional argument, hence the complaint."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:378
|
||
msgid "Note that the order does not matter."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:380
|
||
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:414
|
||
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:450
|
||
msgid ""
|
||
"Note that the change also reflects both in the error message as well as the "
|
||
"help string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:453
|
||
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:472
|
||
msgid ""
|
||
"We have introduced another action, \"count\", to count the number of "
|
||
"occurrences of a specific optional arguments:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:500
|
||
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:503
|
||
msgid "It also behaves similar to \"store_true\" action."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:505
|
||
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:508
|
||
msgid ""
|
||
"And, just like the \"store_true\" action, if you don't specify the ``-v`` "
|
||
"flag, that flag is considered to have ``None`` value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:511
|
||
msgid ""
|
||
"As should be expected, specifying the long form of the flag, we should get "
|
||
"the same output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:514
|
||
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:518
|
||
msgid "That last output exposes a bug in our program."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:521
|
||
msgid "Let's fix::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:540
|
||
msgid "And this is what it gives:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:554
|
||
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:557
|
||
msgid "Third output not so good."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:559
|
||
msgid "Let's fix that bug::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:576
|
||
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:583
|
||
msgid "And:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:590
|
||
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:597
|
||
msgid "Getting a little more advanced"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:599
|
||
msgid ""
|
||
"What if we wanted to expand our tiny program to perform other powers, not "
|
||
"just squares::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:616 ../Doc/howto/argparse.rst:654
|
||
msgid "Output:"
|
||
msgstr "Sortie :"
|
||
|
||
#: ../Doc/howto/argparse.rst:637
|
||
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:668
|
||
msgid "Conflicting options"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:670
|
||
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:696
|
||
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:714
|
||
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:718
|
||
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:739
|
||
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:761
|
||
msgid "Conclusion"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/argparse.rst:763
|
||
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/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:0 ../Doc/howto/curses.rst:0
|
||
#: ../Doc/howto/descriptor.rst:11 ../Doc/howto/doanddont.rst:0
|
||
#: ../Doc/howto/pyporting.rst:0 ../Doc/howto/regex.rst:0
|
||
#: ../Doc/howto/sockets.rst:0 ../Doc/howto/webservers.rst:0
|
||
msgid "Abstract"
|
||
msgstr "Résumé"
|
||
|
||
#: ../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.03"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:13
|
||
msgid ""
|
||
"This document describes how to write text-mode programs with Python 2.x, "
|
||
"using the :mod:`curses` extension module to control the display."
|
||
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 X11 "
|
||
"programs such as xterm and rxvt. 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 X 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 is on small-footprint or embedded Unixes that don't carry an X server. "
|
||
"Another is for tools like OS installers and kernel configurators that may "
|
||
"have to run before X is available."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:35
|
||
msgid ""
|
||
"The curses library hides all the details of different terminals, and "
|
||
"provides the programmer with an abstraction of a display, containing "
|
||
"multiple non-overlapping windows. The contents of a window can be changed "
|
||
"in various ways-- adding text, erasing it, changing its appearance--and the "
|
||
"curses library will automagically figure out what control codes need to be "
|
||
"sent to the terminal to produce the right output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:42
|
||
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:52
|
||
msgid ""
|
||
"No one has made a Windows port of the curses module. On a Windows platform, "
|
||
"try the Console module written by Fredrik Lundh. The Console module "
|
||
"provides cursor-addressable text output, plus full support for mouse and "
|
||
"keyboard input, and is available from http://effbot.org/zone/console-index."
|
||
"htm."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:59
|
||
msgid "The Python curses module"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:61
|
||
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 :func:`addstr`, :func:`mvaddstr`, :func:`mvwaddstr`, into "
|
||
"a single :meth:`addstr` method. You'll see this covered in more detail "
|
||
"later."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:68
|
||
msgid ""
|
||
"This HOWTO is simply 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:75
|
||
msgid "Starting and ending a curses application"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:77
|
||
msgid ""
|
||
"Before doing anything, curses must be initialized. This is done by calling "
|
||
"the :func:`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:87
|
||
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:`noecho` function. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:93
|
||
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:99
|
||
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:108
|
||
msgid ""
|
||
"Terminating a curses application is much easier than starting one. You'll "
|
||
"need to call ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:113
|
||
msgid ""
|
||
"to reverse the curses-friendly terminal settings. Then call the :func:"
|
||
"`endwin` function to restore the terminal to its original operating mode. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:118
|
||
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:124
|
||
msgid ""
|
||
"In Python you can avoid these complications and make debugging much easier "
|
||
"by importing the module :mod:`curses.wrapper`. It supplies a :func:"
|
||
"`wrapper` function that takes a callable. It does the initializations "
|
||
"described above, and also initializes colors if color support is present. "
|
||
"It then runs your provided callable and finally deinitializes "
|
||
"appropriately. The callable is called inside a try-catch clause which "
|
||
"catches exceptions, performs curses deinitialization, and then passes the "
|
||
"exception upwards. Thus, your terminal won't be left in a funny state on "
|
||
"exception."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:135
|
||
msgid "Windows and Pads"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:137
|
||
msgid ""
|
||
"Windows are the basic abstraction in curses. A window object represents a "
|
||
"rectangular area of the screen, and supports various methods to display "
|
||
"text, erase it, allow the user to input strings, and so forth."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:141
|
||
msgid ""
|
||
"The ``stdscr`` object returned by the :func:`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:`newwin` function "
|
||
"creates a new window of a given size, returning the new window object. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:151
|
||
msgid ""
|
||
"A word about the coordinate system used in curses: coordinates are always "
|
||
"passed in the order *y,x*, and the top-left corner of a window is coordinate "
|
||
"(0,0). This breaks a common convention for handling coordinates, where the "
|
||
"*x* coordinate usually 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:158
|
||
msgid ""
|
||
"When you call a method to display or erase text, the effect doesn't "
|
||
"immediately show up on the display. 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 is very "
|
||
"important. This lets curses accumulate changes to the screen, and display "
|
||
"them in the most efficient manner. For example, if your program displays "
|
||
"some characters in a window, and then clears the window, there's no need to "
|
||
"send the original characters because they'd never be visible."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:167
|
||
msgid ""
|
||
"Accordingly, curses requires that you explicitly tell it to redraw windows, "
|
||
"using the :func:`refresh` method of window objects. In practice, this "
|
||
"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 simply "
|
||
"calling ``stdscr.refresh()`` or the :func:`refresh` method of some other "
|
||
"relevant window."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:176
|
||
msgid ""
|
||
"A pad is a special case of a window; it can be larger than the actual "
|
||
"display screen, and only a portion of it displayed at a time. Creating a pad "
|
||
"simply 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:195
|
||
msgid ""
|
||
"The :func:`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:201
|
||
msgid ""
|
||
"If you have multiple windows and pads on screen there is a more efficient "
|
||
"way to go, which will prevent annoying screen flicker at refresh time. Use "
|
||
"the :meth:`noutrefresh` method of each window to update the data structure "
|
||
"representing the desired state of the screen; then change the physical "
|
||
"screen to match the desired state in one go with the function :func:"
|
||
"`doupdate`. The normal :meth:`refresh` method calls :func:`doupdate` as its "
|
||
"last act."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:210
|
||
msgid "Displaying Text"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:212
|
||
msgid ""
|
||
"From a C programmer's point of view, curses may sometimes look like a twisty "
|
||
"maze of functions, all subtly different. For example, :func:`addstr` "
|
||
"displays a string at the current cursor location in the ``stdscr`` window, "
|
||
"while :func:`mvaddstr` moves to a given y,x coordinate first before "
|
||
"displaying the string. :func:`waddstr` is just like :func:`addstr`, but "
|
||
"allows specifying a window to use, instead of using ``stdscr`` by default. :"
|
||
"func:`mvwaddstr` follows similarly."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:220
|
||
msgid ""
|
||
"Fortunately the Python interface hides all these details; ``stdscr`` is a "
|
||
"window object like any other, and methods like :func:`addstr` accept "
|
||
"multiple argument forms. Usually there are four different forms."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:225
|
||
msgid "Form"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:225 ../Doc/howto/curses.rst:283
|
||
msgid "Description"
|
||
msgstr "Description"
|
||
|
||
#: ../Doc/howto/curses.rst:227
|
||
msgid "*str* or *ch*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:227
|
||
msgid "Display the string *str* or character *ch* at the current position"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:230
|
||
msgid "*str* or *ch*, *attr*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:230
|
||
msgid ""
|
||
"Display the string *str* or character *ch*, using attribute *attr* at the "
|
||
"current position"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:234
|
||
msgid "*y*, *x*, *str* or *ch*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:234
|
||
msgid "Move to position *y,x* within the window, and display *str* or *ch*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:237
|
||
msgid "*y*, *x*, *str* or *ch*, *attr*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:237
|
||
msgid ""
|
||
"Move to position *y,x* within the window, and display *str* or *ch*, using "
|
||
"attribute *attr*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:241
|
||
msgid ""
|
||
"Attributes allow displaying text in highlighted forms, such as in boldface, "
|
||
"underline, reverse code, or in color. They'll be explained in more detail "
|
||
"in the next subsection."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:245
|
||
msgid ""
|
||
"The :func:`addstr` function takes a Python string as the value to be "
|
||
"displayed, while the :func:`addch` functions take a character, which can be "
|
||
"either a Python string of length 1 or an integer. If it's a string, you're "
|
||
"limited to displaying characters between 0 and 255. SVr4 curses provides "
|
||
"constants 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)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:253
|
||
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:261
|
||
msgid ""
|
||
"If your application doesn't need a blinking cursor at all, you can call "
|
||
"``curs_set(0)`` to make it invisible. Equivalently, and for compatibility "
|
||
"with older curses versions, there's a ``leaveok(bool)`` function. 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:269
|
||
msgid "Attributes and Color"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:271
|
||
msgid ""
|
||
"Characters can be displayed in different ways. Status lines in a text-based "
|
||
"application are commonly shown in reverse video; 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:276
|
||
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:283
|
||
msgid "Attribute"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:285
|
||
msgid ":const:`A_BLINK`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:285
|
||
msgid "Blinking text"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:287
|
||
msgid ":const:`A_BOLD`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:287
|
||
msgid "Extra bright or bold text"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:289
|
||
msgid ":const:`A_DIM`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:289
|
||
msgid "Half bright text"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:291
|
||
msgid ":const:`A_REVERSE`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:291
|
||
msgid "Reverse-video text"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:293
|
||
msgid ":const:`A_STANDOUT`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:293
|
||
msgid "The best highlighting mode available"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:295
|
||
msgid ":const:`A_UNDERLINE`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:295
|
||
msgid "Underlined text"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:298
|
||
msgid ""
|
||
"So, to display a reverse-video status line on the top line of the screen, "
|
||
"you could code::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:305
|
||
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:309
|
||
msgid ""
|
||
"To use color, you must call the :func:`start_color` function soon after "
|
||
"calling :func:`initscr`, to initialize the default color set (the :func:"
|
||
"`curses.wrapper.wrapper` function does this automatically). Once that's "
|
||
"done, the :func:`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:318
|
||
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:`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:324
|
||
msgid "An example, which displays a line of text using color pair 1::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:329
|
||
msgid ""
|
||
"As I said before, a color pair consists of a foreground and background "
|
||
"color. :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 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:335
|
||
msgid ""
|
||
"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:339
|
||
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:344
|
||
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:350
|
||
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:"
|
||
"`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:360
|
||
msgid "User Input"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:362
|
||
msgid ""
|
||
"The curses library itself offers only very simple input mechanisms. Python's "
|
||
"support adds a text-input widget that makes up some of the lack."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:365
|
||
msgid ""
|
||
"The most common way to get input to a window is to use its :meth:`getch` "
|
||
"method. :meth:`getch` pauses and waits for the user to hit a key, displaying "
|
||
"it if :func:`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:370
|
||
msgid ""
|
||
"It's possible to change this behavior with the method :meth:`nodelay`. After "
|
||
"``nodelay(1)``, :meth:`getch` for the window becomes non-blocking and "
|
||
"returns ``curses.ERR`` (a value of -1) when no input is ready. There's also "
|
||
"a :func:`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:377
|
||
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`. Usually the main loop of "
|
||
"your program will look something like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:393
|
||
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 your command interpreters. 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:400
|
||
msgid ""
|
||
"There's also a method to retrieve an entire string, :const:`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:410
|
||
msgid ""
|
||
"The Python :mod:`curses.textpad` module supplies something better. With it, "
|
||
"you can turn a window into a text box that supports an Emacs-like set of "
|
||
"keybindings. Various methods of :class:`Textbox` class support editing with "
|
||
"input validation and gathering the edit results either with or without "
|
||
"trailing spaces. See the library documentation on :mod:`curses.textpad` "
|
||
"for the details."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:419
|
||
msgid "For More Information"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:421
|
||
msgid ""
|
||
"This HOWTO didn't cover some advanced topics, such as screen-scraping or "
|
||
"capturing mouse events from an xterm instance. But the Python library page "
|
||
"for the curses modules is now pretty complete. You should browse it next."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:425
|
||
msgid ""
|
||
"If you're in doubt about the detailed behavior of any of the ncurses entry "
|
||
"points, 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:431
|
||
msgid ""
|
||
"Because the curses API is so large, some functions aren't supported in the "
|
||
"Python interface, not because they're difficult to implement, but because no "
|
||
"one has needed them yet. Feel free to add them and then submit a patch. "
|
||
"Also, we don't yet have support for the menu library associated with "
|
||
"ncurses; feel free to add that."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:437
|
||
msgid ""
|
||
"If you write an interesting little program, feel free to contribute it as "
|
||
"another demo. We can always use more of them!"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/curses.rst:440
|
||
msgid "The ncurses FAQ: http://invisible-island.net/ncurses/ncurses.faq.html"
|
||
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. Note that descriptors are only invoked for "
|
||
"new style objects or classes (a class is new style if it inherits from :"
|
||
"class:`object` or :class:`type`)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:43
|
||
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:51
|
||
msgid "Descriptor Protocol"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:53
|
||
msgid "``descr.__get__(self, obj, type=None) --> value``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:55
|
||
msgid "``descr.__set__(self, obj, value) --> None``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:57
|
||
msgid "``descr.__delete__(self, obj) --> None``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:59
|
||
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:63
|
||
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:68
|
||
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:74
|
||
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:81
|
||
msgid "Invoking Descriptors"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:83
|
||
msgid ""
|
||
"A descriptor can be called directly by its method name. For example, ``d."
|
||
"__get__(obj)``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:86
|
||
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:91
|
||
msgid ""
|
||
"The details of invocation depend on whether ``obj`` is an object or a class. "
|
||
"Either way, descriptors only work for new style objects and classes. A "
|
||
"class is new style if it is a subclass of :class:`object`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:95
|
||
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:103
|
||
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:114
|
||
msgid "The important points to remember are:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:116
|
||
msgid "descriptors are invoked by the :meth:`__getattribute__` method"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:117
|
||
msgid "overriding :meth:`__getattribute__` prevents automatic descriptor calls"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:118
|
||
msgid ""
|
||
":meth:`__getattribute__` is only available with new style classes and objects"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:119
|
||
msgid ""
|
||
":meth:`object.__getattribute__` and :meth:`type.__getattribute__` make "
|
||
"different calls to :meth:`__get__`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:121
|
||
msgid "data descriptors always override instance dictionaries."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:122
|
||
msgid "non-data descriptors may be overridden by instance dictionaries."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:124
|
||
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:131
|
||
msgid ""
|
||
"Note, in Python 2.2, ``super(B, obj).m()`` would only invoke :meth:`__get__` "
|
||
"if ``m`` was a data descriptor. In Python 2.3, non-data descriptors also "
|
||
"get invoked unless an old-style class is involved. The implementation "
|
||
"details are in :c:func:`super_getattro()` in :source:`Objects/typeobject.c`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:138
|
||
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:147
|
||
msgid "Descriptor Example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:149
|
||
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:187
|
||
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:194
|
||
msgid "Properties"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:196
|
||
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:201
|
||
msgid ""
|
||
"The documentation shows a typical use to define a managed attribute ``x``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:209
|
||
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:249
|
||
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:253
|
||
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:269
|
||
msgid "Functions and Methods"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:271
|
||
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:274
|
||
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:281
|
||
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:293
|
||
msgid ""
|
||
"Running the interpreter shows how the function descriptor works in practice::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:307
|
||
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:313
|
||
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:322
|
||
msgid "Static Methods and Class Methods"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:324
|
||
msgid ""
|
||
"Non-data descriptors provide a simple mechanism for variations on the usual "
|
||
"patterns of binding functions into methods."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:327
|
||
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:332
|
||
msgid "This chart summarizes the binding and its two most useful variants:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:335
|
||
msgid "Transformation"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:335
|
||
msgid "Called from an Object"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:335
|
||
msgid "Called from a Class"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:338
|
||
msgid "function"
|
||
msgstr "fonction"
|
||
|
||
#: ../Doc/howto/descriptor.rst:338
|
||
msgid "f(obj, \\*args)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:338 ../Doc/howto/descriptor.rst:340
|
||
msgid "f(\\*args)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:340
|
||
msgid "staticmethod"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:342
|
||
msgid "classmethod"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:342
|
||
msgid "f(type(obj), \\*args)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:342
|
||
msgid "f(klass, \\*args)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:345
|
||
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:351
|
||
msgid ""
|
||
"Good candidates for static methods are methods that do not reference the "
|
||
"``self`` variable."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:354
|
||
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:363
|
||
msgid ""
|
||
"Since staticmethods return the underlying function with no changes, the "
|
||
"example calls are unexciting::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:376
|
||
msgid ""
|
||
"Using the non-data descriptor protocol, a pure Python version of :func:"
|
||
"`staticmethod` would look like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:388
|
||
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:403
|
||
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:419
|
||
msgid "Now a new dictionary of unique keys can be constructed like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/descriptor.rst:424
|
||
msgid ""
|
||
"Using the non-data descriptor protocol, a pure Python version of :func:"
|
||
"`classmethod` would look like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:3
|
||
msgid "Idioms and Anti-Idioms in Python"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:5
|
||
msgid "Moshe Zadka"
|
||
msgstr "Moshe Zadka"
|
||
|
||
#: ../Doc/howto/doanddont.rst:7
|
||
msgid "This document is placed in the public domain."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:12
|
||
msgid ""
|
||
"This document can be considered a companion to the tutorial. It shows how to "
|
||
"use Python, and even more importantly, how *not* to use Python."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:17
|
||
msgid "Language Constructs You Should Not Use"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:19
|
||
msgid ""
|
||
"While Python has relatively few gotchas compared to other languages, it "
|
||
"still has some constructs which are only useful in corner cases, or are "
|
||
"plain dangerous."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:25
|
||
msgid "from module import \\*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:29
|
||
msgid "Inside Function Definitions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:31
|
||
msgid ""
|
||
"``from module import *`` is *invalid* inside function definitions. While "
|
||
"many versions of Python do not check for the invalidity, it does not make it "
|
||
"more valid, no more than having a smart lawyer makes a man innocent. Do not "
|
||
"use it like that ever. Even in versions where it was accepted, it made the "
|
||
"function execution slower, because the compiler could not be certain which "
|
||
"names were local and which were global. In Python 2.1 this construct causes "
|
||
"warnings, and sometimes even errors."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:41
|
||
msgid "At Module Level"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:43
|
||
msgid ""
|
||
"While it is valid to use ``from module import *`` at module level it is "
|
||
"usually a bad idea. For one, this loses an important property Python "
|
||
"otherwise has --- you can know where each toplevel name is defined by a "
|
||
"simple \"search\" function in your favourite editor. You also open yourself "
|
||
"to trouble in the future, if some module grows additional functions or "
|
||
"classes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:49
|
||
msgid ""
|
||
"One of the most awful questions asked on the newsgroup is why this code::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:54
|
||
msgid ""
|
||
"does not work. Of course, it works just fine (assuming you have a file "
|
||
"called \"www\".) But it does not work if somewhere in the module, the "
|
||
"statement ``from os import *`` is present. The :mod:`os` module has a "
|
||
"function called :func:`open` which returns an integer. While it is very "
|
||
"useful, shadowing a builtin is one of its least useful properties."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:60
|
||
msgid ""
|
||
"Remember, you can never know for sure what names a module exports, so either "
|
||
"take what you need --- ``from module import name1, name2``, or keep them in "
|
||
"the module and access on a per-need basis --- ``import module;print module."
|
||
"name``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:66
|
||
msgid "When It Is Just Fine"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:68
|
||
msgid "There are situations in which ``from module import *`` is just fine:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:70
|
||
msgid ""
|
||
"The interactive prompt. For example, ``from math import *`` makes Python an "
|
||
"amazing scientific calculator."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:73
|
||
msgid "When extending a module in C with a module in Python."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:75
|
||
msgid "When the module advertises itself as ``from import *`` safe."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:79
|
||
msgid "Unadorned :keyword:`exec`, :func:`execfile` and friends"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:81
|
||
msgid ""
|
||
"The word \"unadorned\" refers to the use without an explicit dictionary, in "
|
||
"which case those constructs evaluate code in the *current* environment. This "
|
||
"is dangerous for the same reasons ``from import *`` is dangerous --- it "
|
||
"might step over variables you are counting on and mess up things for the "
|
||
"rest of your code. Simply do not do that."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:87
|
||
msgid "Bad examples::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:97
|
||
msgid "Good examples::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:112
|
||
msgid "from module import name1, name2"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:114
|
||
msgid ""
|
||
"This is a \"don't\" which is much weaker than the previous \"don't\"s but is "
|
||
"still something you should not do if you don't have good reasons to do that. "
|
||
"The reason it is usually a bad idea is because you suddenly have an object "
|
||
"which lives in two separate namespaces. When the binding in one namespace "
|
||
"changes, the binding in the other will not, so there will be a discrepancy "
|
||
"between them. This happens when, for example, one module is reloaded, or "
|
||
"changes the definition of a function at runtime."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:122
|
||
msgid "Bad example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:132
|
||
msgid "Good example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:144
|
||
msgid "except:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:146
|
||
msgid ""
|
||
"Python has the ``except:`` clause, which catches all exceptions. Since "
|
||
"*every* error in Python raises an exception, using ``except:`` can make many "
|
||
"programming errors look like runtime problems, which hinders the debugging "
|
||
"process."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:151
|
||
msgid "The following code shows a great example of why this is bad::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:158
|
||
msgid ""
|
||
"The second line triggers a :exc:`NameError`, which is caught by the except "
|
||
"clause. The program will exit, and the error message the program prints will "
|
||
"make you think the problem is the readability of ``\"file\"`` when in fact "
|
||
"the real error has nothing to do with ``\"file\"``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:163
|
||
msgid "A better way to write the above is ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:170
|
||
msgid ""
|
||
"When this is run, Python will produce a traceback showing the :exc:"
|
||
"`NameError`, and it will be immediately apparent what needs to be fixed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:175
|
||
msgid ""
|
||
"Because ``except:`` catches *all* exceptions, including :exc:`SystemExit`, :"
|
||
"exc:`KeyboardInterrupt`, and :exc:`GeneratorExit` (which is not an error and "
|
||
"should not normally be caught by user code), using a bare ``except:`` is "
|
||
"almost never a good idea. In situations where you need to catch all \"normal"
|
||
"\" errors, such as in a framework that runs callbacks, you can catch the "
|
||
"base class for all normal exceptions, :exc:`Exception`. Unfortunately in "
|
||
"Python 2.x it is possible for third-party code to raise exceptions that do "
|
||
"not inherit from :exc:`Exception`, so in Python 2.x there are some cases "
|
||
"where you may have to use a bare ``except:`` and manually re-raise the "
|
||
"exceptions you don't want to catch."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:188
|
||
msgid "Exceptions"
|
||
msgstr "Les exceptions"
|
||
|
||
#: ../Doc/howto/doanddont.rst:190
|
||
msgid ""
|
||
"Exceptions are a useful feature of Python. You should learn to raise them "
|
||
"whenever something unexpected occurs, and catch them only where you can do "
|
||
"something about them."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:194
|
||
msgid "The following is a very popular anti-idiom ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:202
|
||
msgid ""
|
||
"Consider the case where the file gets deleted between the time the call to :"
|
||
"func:`os.path.exists` is made and the time :func:`open` is called. In that "
|
||
"case the last line will raise an :exc:`IOError`. The same thing would "
|
||
"happen if *file* exists but has no read permission. Since testing this on a "
|
||
"normal machine on existent and non-existent files makes it seem bugless, the "
|
||
"test results will seem fine, and the code will get shipped. Later an "
|
||
"unhandled :exc:`IOError` (or perhaps some other :exc:`EnvironmentError`) "
|
||
"escapes to the user, who gets to watch the ugly traceback."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:211
|
||
msgid "Here is a somewhat better way to do it. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:220
|
||
msgid ""
|
||
"In this version, *either* the file gets opened and the line is read (so it "
|
||
"works even on flaky NFS or SMB connections), or an error message is printed "
|
||
"that provides all the available information on why the open failed, and the "
|
||
"application is aborted."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:225
|
||
msgid ""
|
||
"However, even this version of :func:`get_status` makes too many assumptions "
|
||
"--- that it will only be used in a short running script, and not, say, in a "
|
||
"long running server. Sure, the caller could do something like ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:234
|
||
msgid ""
|
||
"But there is a better way. You should try to use as few ``except`` clauses "
|
||
"in your code as you can --- the ones you do use will usually be inside calls "
|
||
"which should always succeed, or a catch-all in a main function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:238
|
||
msgid "So, an even better version of :func:`get_status()` is probably ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:243
|
||
msgid ""
|
||
"The caller can deal with the exception if it wants (for example, if it tries "
|
||
"several files in a loop), or just let the exception filter upwards to *its* "
|
||
"caller."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:247
|
||
msgid ""
|
||
"But the last version still has a serious problem --- due to implementation "
|
||
"details in CPython, the file would not be closed when an exception is raised "
|
||
"until the exception handler finishes; and, worse, in other implementations "
|
||
"(e.g., Jython) it might not be closed at all regardless of whether or not an "
|
||
"exception is raised."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:253
|
||
msgid ""
|
||
"The best version of this function uses the ``open()`` call as a context "
|
||
"manager, which will ensure that the file gets closed as soon as the function "
|
||
"returns::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:263
|
||
msgid "Using the Batteries"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:265
|
||
msgid ""
|
||
"Every so often, people seem to be writing stuff in the Python library again, "
|
||
"usually poorly. While the occasional module has a poor interface, it is "
|
||
"usually much better to use the rich standard library and data types that "
|
||
"come with Python than inventing your own."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:270
|
||
msgid ""
|
||
"A useful module very few people know about is :mod:`os.path`. It always has "
|
||
"the correct path arithmetic for your operating system, and will usually be "
|
||
"much better than whatever you come up with yourself."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:274
|
||
msgid "Compare::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:281
|
||
msgid ""
|
||
"More useful functions in :mod:`os.path`: :func:`basename`, :func:`dirname` "
|
||
"and :func:`splitext`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:284
|
||
msgid ""
|
||
"There are also many useful built-in functions people seem not to be aware of "
|
||
"for some reason: :func:`min` and :func:`max` can find the minimum/maximum of "
|
||
"any sequence with comparable semantics, for example, yet many people write "
|
||
"their own :func:`max`/:func:`min`. Another highly useful function is :func:"
|
||
"`reduce` which can be used to repeatly apply a binary operation to a "
|
||
"sequence, reducing it to a single value. For example, compute a factorial "
|
||
"with a series of multiply operations::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:297
|
||
msgid ""
|
||
"When it comes to parsing numbers, note that :func:`float`, :func:`int` and :"
|
||
"func:`long` all accept string arguments and will reject ill-formed strings "
|
||
"by raising an :exc:`ValueError`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:303
|
||
msgid "Using Backslash to Continue Statements"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:305
|
||
msgid ""
|
||
"Since Python treats a newline as a statement terminator, and since "
|
||
"statements are often more than is comfortable to put in one line, many "
|
||
"people do::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:312
|
||
msgid ""
|
||
"You should realize that this is dangerous: a stray space after the ``\\`` "
|
||
"would make this line wrong, and stray spaces are notoriously hard to see in "
|
||
"editors. In this case, at least it would be a syntax error, but if the code "
|
||
"was::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:319
|
||
msgid "then it would just be subtly wrong."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:321
|
||
msgid ""
|
||
"It is usually much better to use the implicit continuation inside "
|
||
"parenthesis:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/doanddont.rst:323
|
||
msgid "This version is bulletproof::"
|
||
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.31"
|
||
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:16
|
||
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."
|
||
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:57
|
||
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:65
|
||
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 ``print`` statement or a "
|
||
"``time.sleep(1)`` 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:73
|
||
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:79
|
||
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:88
|
||
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:92
|
||
msgid "Formal provability."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:93
|
||
msgid "Modularity."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:94
|
||
msgid "Composability."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:95
|
||
msgid "Ease of debugging and testing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:99
|
||
msgid "Formal provability"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:101
|
||
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:104
|
||
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:111
|
||
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:119
|
||
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:124
|
||
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:135
|
||
msgid "Modularity"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:137
|
||
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:145
|
||
msgid "Ease of debugging and testing"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:147
|
||
msgid "Testing and debugging a functional-style program is easier."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:149
|
||
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:154
|
||
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:161
|
||
msgid "Composability"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:163
|
||
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:170
|
||
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:176
|
||
msgid "Iterators"
|
||
msgstr "Itérateurs"
|
||
|
||
#: ../Doc/howto/functional.rst:178
|
||
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:181
|
||
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 ``next()`` that takes no arguments and always returns the next "
|
||
"element of the stream. If there are no more elements in the stream, "
|
||
"``next()`` must raise the ``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:189
|
||
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 an **iterable** object if you "
|
||
"can get an iterator for it."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:196
|
||
msgid "You can experiment with the iteration interface manually:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:214
|
||
msgid ""
|
||
"Python expects iterable objects in several different contexts, the most "
|
||
"important being the ``for`` statement. In the statement ``for X in Y``, Y "
|
||
"must be an iterator or some object for which ``iter()`` can create an "
|
||
"iterator. These two statements are equivalent::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:225
|
||
msgid ""
|
||
"Iterators can be materialized as lists or tuples by using the :func:`list` "
|
||
"or :func:`tuple` constructor functions:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:234
|
||
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:243
|
||
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; ``max()``, "
|
||
"``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:251
|
||
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 ``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:261
|
||
msgid "Data Types That Support Iterators"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:263
|
||
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:267
|
||
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 ``iter()`` to a dictionary always loops over the keys, but "
|
||
"dictionaries have methods that return other iterators. If you want to "
|
||
"iterate over keys, values, or key/value pairs, you can explicitly call the "
|
||
"``iterkeys()``, ``itervalues()``, or ``iteritems()`` methods to get an "
|
||
"appropriate iterator."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:299
|
||
msgid ""
|
||
"The :func:`dict` constructor can accept an iterator that returns a finite "
|
||
"stream of ``(key, value)`` tuples:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:306
|
||
msgid ""
|
||
"Files also support iteration by calling the ``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:314
|
||
msgid ""
|
||
"Sets can take their contents from an iterable and let you iterate over the "
|
||
"set's elements::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:324
|
||
msgid "Generator expressions and list comprehensions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:326
|
||
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:332
|
||
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 (http://www.haskell.org/). You can "
|
||
"strip all the whitespace from a stream of strings with the following code::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:345
|
||
msgid ""
|
||
"You can select only certain elements by adding an ``\"if\"`` condition::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:350
|
||
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:357
|
||
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:370
|
||
msgid ""
|
||
"Again, for a list comprehension only the outside brackets are different "
|
||
"(square brackets instead of parentheses)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:373
|
||
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:377
|
||
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:383
|
||
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:389
|
||
msgid ""
|
||
"To put it another way, a list comprehension or generator expression is "
|
||
"equivalent to the following Python code::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:406
|
||
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:421
|
||
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:432
|
||
msgid "Generators"
|
||
msgstr "Générateurs"
|
||
|
||
#: ../Doc/howto/functional.rst:434
|
||
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:438
|
||
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:447
|
||
msgid "Here's the simplest example of a generator function:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:455
|
||
msgid ""
|
||
"Any function containing a ``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:459
|
||
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 ``.next()`` method, the "
|
||
"function will resume executing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:467
|
||
msgid "Here's a sample usage of the ``generate_ints()`` generator:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:484
|
||
msgid ""
|
||
"You could equally write ``for i in generate_ints(5)``, or ``a,b,c = "
|
||
"generate_ints(3)``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:487
|
||
msgid ""
|
||
"Inside a generator function, the ``return`` statement can only be used "
|
||
"without a value, and signals the end of the procession of values; after "
|
||
"executing a ``return`` the generator cannot return any further values. "
|
||
"``return`` with a value, such as ``return 5``, is a syntax error inside a "
|
||
"generator function. The end of the generator's results can also be "
|
||
"indicated by raising ``StopIteration`` manually, or by just letting the flow "
|
||
"of execution fall off the bottom of the function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:495
|
||
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 ``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:502
|
||
msgid ""
|
||
"The test suite included with Python's library, ``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:517
|
||
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:525
|
||
msgid "Passing values into a generator"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:527
|
||
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:534
|
||
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:540
|
||
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:545
|
||
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:551
|
||
msgid ""
|
||
"Values are sent into a generator by calling its ``send(value)`` method. "
|
||
"This method resumes the generator's code and the ``yield`` expression "
|
||
"returns the specified value. If the regular ``next()`` method is called, "
|
||
"the ``yield`` returns ``None``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:556
|
||
msgid ""
|
||
"Here's a simple counter that increments by 1 and allows changing the value "
|
||
"of the internal counter."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:571
|
||
msgid "And here's an example of changing the counter:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:588
|
||
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 ``send()`` method will be the only method used to resume your "
|
||
"generator function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:593
|
||
msgid ""
|
||
"In addition to ``send()``, there are two other new methods on generators:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:595
|
||
msgid ""
|
||
"``throw(type, value=None, traceback=None)`` 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:599
|
||
msgid ""
|
||
"``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`. ``close()`` will also be called by Python's garbage "
|
||
"collector when the generator is garbage-collected."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:606
|
||
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:609
|
||
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:612
|
||
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:619
|
||
msgid "Built-in functions"
|
||
msgstr "Fonctions Natives"
|
||
|
||
#: ../Doc/howto/functional.rst:621
|
||
msgid ""
|
||
"Let's look in more detail at built-in functions often used with iterators."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:623
|
||
msgid ""
|
||
"Two of Python's built-in functions, :func:`map` and :func:`filter`, are "
|
||
"somewhat obsolete; they duplicate the features of list comprehensions but "
|
||
"return actual lists instead of iterators."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:627
|
||
msgid ""
|
||
"``map(f, iterA, iterB, ...)`` returns a list containing ``f(iterA[0], "
|
||
"iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:639
|
||
msgid ""
|
||
"As shown above, you can achieve the same effect with a list comprehension. "
|
||
"The :func:`itertools.imap` function does the same thing but can handle "
|
||
"infinite iterators; it'll be discussed later, in the section on the :mod:"
|
||
"`itertools` module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:643
|
||
msgid ""
|
||
"``filter(predicate, iter)`` returns a list that contains 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:655
|
||
msgid "This can also be written as a list comprehension:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:660
|
||
msgid ""
|
||
":func:`filter` also has a counterpart in the :mod:`itertools` module, :func:"
|
||
"`itertools.ifilter`, that returns an iterator and can therefore handle "
|
||
"infinite sequences just as :func:`itertools.imap` can."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:664
|
||
msgid ""
|
||
"``reduce(func, iter, [initial_value])`` doesn't have a counterpart in the :"
|
||
"mod:`itertools` module because it 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:`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:688
|
||
msgid ""
|
||
"If you use :func:`operator.add` with :func:`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:699
|
||
msgid ""
|
||
"For many uses of :func:`reduce`, though, it can be clearer to just write the "
|
||
"obvious :keyword:`for` loop::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:711
|
||
msgid ""
|
||
"``enumerate(iter)`` counts off the elements in the iterable, returning 2-"
|
||
"tuples containing the count and each element."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:720
|
||
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:728
|
||
msgid ""
|
||
"``sorted(iterable, [cmp=None], [key=None], [reverse=False])`` collects all "
|
||
"the elements of the iterable into a list, sorts the list, and returns the "
|
||
"sorted result. The ``cmp``, ``key``, and ``reverse`` arguments are passed "
|
||
"through to the constructed list's ``.sort()`` method. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:743
|
||
msgid ""
|
||
"(For a more detailed discussion of sorting, see the Sorting mini-HOWTO in "
|
||
"the Python wiki at https://wiki.python.org/moin/HowTo/Sorting.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:746
|
||
msgid ""
|
||
"The ``any(iter)`` and ``all(iter)`` 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:766
|
||
msgid "Small functions and the lambda expression"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:768
|
||
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:771
|
||
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:777
|
||
msgid ""
|
||
"If the function you need doesn't exist, you need to write it. One way to "
|
||
"write small functions is to use the ``lambda`` statement. ``lambda`` takes "
|
||
"a number of parameters and an expression combining these parameters, and "
|
||
"creates a small function that returns the value of the expression::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:788
|
||
msgid ""
|
||
"An alternative is to just use the ``def`` statement and define a function in "
|
||
"the usual way::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:800
|
||
msgid ""
|
||
"Which alternative is preferable? That's a style question; my usual course "
|
||
"is to avoid using ``lambda``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:803
|
||
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:814
|
||
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:823
|
||
msgid "But it would be best of all if I had simply used a ``for`` loop::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:829
|
||
msgid "Or the :func:`sum` built-in and a generator expression::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:833
|
||
msgid "Many uses of :func:`reduce` are clearer when written as ``for`` loops."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:835
|
||
msgid ""
|
||
"Fredrik Lundh once suggested the following set of rules for refactoring uses "
|
||
"of ``lambda``:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:838
|
||
msgid "Write a lambda function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:839
|
||
msgid "Write a comment explaining what the heck that lambda does."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:840
|
||
msgid ""
|
||
"Study the comment for a while, and think of a name that captures the essence "
|
||
"of the comment."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:842
|
||
msgid "Convert the lambda to a def statement, using that name."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:843
|
||
msgid "Remove the comment."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:845
|
||
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:850
|
||
msgid "The itertools module"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:852
|
||
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:856
|
||
msgid "The module's functions fall into a few broad classes:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:858
|
||
msgid "Functions that create a new iterator based on an existing iterator."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:859
|
||
msgid "Functions for treating an iterator's elements as function arguments."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:860
|
||
msgid "Functions for selecting portions of an iterator's output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:861
|
||
msgid "A function for grouping an iterator's output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:864
|
||
msgid "Creating new iterators"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:866
|
||
msgid ""
|
||
"``itertools.count(n)`` 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:874
|
||
msgid ""
|
||
"``itertools.cycle(iter)`` 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:881
|
||
msgid ""
|
||
"``itertools.repeat(elem, [n])`` returns the provided element ``n`` times, or "
|
||
"returns the element endlessly if ``n`` is not provided. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:889
|
||
msgid ""
|
||
"``itertools.chain(iterA, iterB, ...)`` 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:896
|
||
msgid ""
|
||
"``itertools.izip(iterA, iterB, ...)`` takes one element from each iterable "
|
||
"and returns them in a tuple::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:902
|
||
msgid ""
|
||
"It's similar to the built-in :func:`zip` function, but 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 <http://en.wikipedia."
|
||
"org/wiki/Lazy_evaluation>`__.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:908
|
||
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:915
|
||
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:919
|
||
msgid ""
|
||
"``itertools.islice(iter, [start], stop, [step])`` 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:933
|
||
msgid ""
|
||
"``itertools.tee(iter, [n])`` 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:951
|
||
msgid "Calling functions on elements"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:953
|
||
msgid ""
|
||
"Two functions are used for calling other functions on the contents of an "
|
||
"iterable."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:956
|
||
msgid ""
|
||
"``itertools.imap(f, iterA, iterB, ...)`` returns a stream containing "
|
||
"``f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ..."
|
||
"``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:962
|
||
msgid ""
|
||
"The ``operator`` module contains a set of functions corresponding to "
|
||
"Python's operators. Some examples are ``operator.add(a, b)`` (adds two "
|
||
"values), ``operator.ne(a, b)`` (same as ``a!=b``), and ``operator."
|
||
"attrgetter('id')`` (returns a callable that fetches the ``\"id\"`` "
|
||
"attribute)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:967
|
||
msgid ""
|
||
"``itertools.starmap(func, iter)`` assumes that the iterable will return a "
|
||
"stream of tuples, and calls ``f()`` using these tuples as the arguments::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:978
|
||
msgid "Selecting elements"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:980
|
||
msgid ""
|
||
"Another group of functions chooses a subset of an iterator's elements based "
|
||
"on a predicate."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:983
|
||
msgid ""
|
||
"``itertools.ifilter(predicate, iter)`` returns all the elements for which "
|
||
"the predicate returns true::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:992
|
||
msgid ""
|
||
"``itertools.ifilterfalse(predicate, iter)`` is the opposite, returning all "
|
||
"elements for which the predicate returns false::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:998
|
||
msgid ""
|
||
"``itertools.takewhile(predicate, iter)`` 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:1013
|
||
msgid ""
|
||
"``itertools.dropwhile(predicate, iter)`` discards elements while the "
|
||
"predicate returns true, and then returns the rest of the iterable's results."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1026
|
||
msgid "Grouping elements"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1028
|
||
msgid ""
|
||
"The last function I'll discuss, ``itertools.groupby(iter, key_func=None)``, "
|
||
"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:1033
|
||
msgid ""
|
||
"``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:1061
|
||
msgid ""
|
||
"``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:1068
|
||
msgid "The functools module"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1070
|
||
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:1075
|
||
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:1081
|
||
msgid ""
|
||
"The constructor for ``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:1085
|
||
msgid "Here's a small but realistic example::"
|
||
msgstr "Voici un exemple court mais réaliste ::"
|
||
|
||
#: ../Doc/howto/functional.rst:1099
|
||
msgid "The operator module"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1101
|
||
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:1106
|
||
msgid "Some of the functions in this module are:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1108
|
||
msgid ""
|
||
"Math operations: ``add()``, ``sub()``, ``mul()``, ``div()``, ``floordiv()``, "
|
||
"``abs()``, ..."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1110
|
||
msgid "Logical operations: ``not_()``, ``truth()``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1111
|
||
msgid "Bitwise operations: ``and_()``, ``or_()``, ``invert()``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1112
|
||
msgid ""
|
||
"Comparisons: ``eq()``, ``ne()``, ``lt()``, ``le()``, ``gt()``, and ``ge()``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1113
|
||
msgid "Object identity: ``is_()``, ``is_not()``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1115
|
||
msgid "Consult the operator module's documentation for a complete list."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1119 ../Doc/howto/unicode.rst:696
|
||
msgid "Revision History and Acknowledgements"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1121
|
||
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:1126
|
||
msgid "Version 0.1: posted June 30 2006."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1128
|
||
msgid "Version 0.11: posted July 1 2006. Typo fixes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1130
|
||
msgid ""
|
||
"Version 0.2: posted July 10 2006. Merged genexp and listcomp sections into "
|
||
"one. Typo fixes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1133
|
||
msgid ""
|
||
"Version 0.21: Added more references suggested on the tutor mailing list."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1135
|
||
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:1140 ../Doc/howto/unicode.rst:205
|
||
#: ../Doc/howto/unicode.rst:492 ../Doc/howto/unicode.rst:686
|
||
msgid "References"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1143
|
||
msgid "General"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1145
|
||
msgid ""
|
||
"**Structure and Interpretation of Computer Programs**, by Harold Abelson and "
|
||
"Gerald Jay Sussman with Julie Sussman. Full text at http://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:1153
|
||
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:1156
|
||
msgid ""
|
||
"http://en.wikipedia.org/wiki/Functional_programming: General Wikipedia entry "
|
||
"describing functional programming."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1159
|
||
msgid "http://en.wikipedia.org/wiki/Coroutine: Entry for coroutines."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1161
|
||
msgid ""
|
||
"http://en.wikipedia.org/wiki/Currying: Entry for the concept of currying."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1164
|
||
msgid "Python-specific"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1166
|
||
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:1171
|
||
msgid ""
|
||
"Mertz also wrote a 3-part series of articles on functional programming for "
|
||
"IBM's DeveloperWorks site; see"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1174
|
||
msgid ""
|
||
"`part 1 <http://www.ibm.com/developerworks/linux/library/l-prog/index."
|
||
"html>`__, `part 2 <http://www.ibm.com/developerworks/linux/library/l-prog2/"
|
||
"index.html>`__, and `part 3 <http://www.ibm.com/developerworks/linux/library/"
|
||
"l-prog3/index.html>`__,"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1180
|
||
msgid "Python documentation"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1182
|
||
msgid "Documentation for the :mod:`itertools` module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1184
|
||
msgid "Documentation for the :mod:`operator` module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1186
|
||
msgid ":pep:`289`: \"Generator Expressions\""
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/functional.rst:1188
|
||
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/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:794
|
||
msgid "Level"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:69
|
||
msgid "When it's used"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:71 ../Doc/howto/logging.rst:804
|
||
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:802
|
||
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:800
|
||
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:798
|
||
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:796
|
||
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:113
|
||
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:122
|
||
msgid "Logging to a file"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:124
|
||
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:134
|
||
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:141
|
||
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:145
|
||
msgid ""
|
||
"If you want to set the logging level from a command-line option such as::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:149
|
||
msgid ""
|
||
"and you have the value of the parameter passed for ``--log`` in some "
|
||
"variable *loglevel*, you can use::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:154
|
||
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:166
|
||
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:171
|
||
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:178
|
||
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:183
|
||
msgid "Logging from multiple modules"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:185
|
||
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:209
|
||
msgid "If you run *myapp.py*, you should see this in *myapp.log*::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:215
|
||
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:225
|
||
msgid "Logging variable data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:227
|
||
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:233
|
||
msgid "will display::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:237
|
||
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."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:246
|
||
msgid "Changing the format of displayed messages"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:248
|
||
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:257
|
||
msgid "which would print::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:263
|
||
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:272
|
||
msgid "Displaying the date/time in messages"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:274
|
||
msgid ""
|
||
"To display the date and time of an event, you would place '%(asctime)s' in "
|
||
"your format string::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:281
|
||
msgid "which should print something like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:285
|
||
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:293
|
||
msgid "which would display something like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:297
|
||
msgid ""
|
||
"The format of the *datefmt* argument is the same as supported by :func:`time."
|
||
"strftime`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:302
|
||
msgid "Next Steps"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:304
|
||
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:310
|
||
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 http://groups.google.com/group/comp.lang.python) and you "
|
||
"should receive help before too long."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:316
|
||
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:324
|
||
msgid "Advanced Logging Tutorial"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:326
|
||
msgid ""
|
||
"The logging library takes a modular approach and offers several categories "
|
||
"of components: loggers, handlers, filters, and formatters."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:329
|
||
msgid "Loggers expose the interface that application code directly uses."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:330
|
||
msgid ""
|
||
"Handlers send the log records (created by loggers) to the appropriate "
|
||
"destination."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:332
|
||
msgid ""
|
||
"Filters provide a finer grained facility for determining which log records "
|
||
"to output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:334
|
||
msgid "Formatters specify the layout of log records in the final output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:336
|
||
msgid ""
|
||
"Log event information is passed between loggers, handlers, filters and "
|
||
"formatters in a :class:`LogRecord` instance."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:339
|
||
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:346
|
||
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:351
|
||
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:354
|
||
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:360
|
||
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, 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:367
|
||
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:375
|
||
msgid "The default format set by :func:`basicConfig` for messages is::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:379
|
||
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:384
|
||
msgid "Logging Flow"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:386
|
||
msgid ""
|
||
"The flow of log event information in loggers and handlers is illustrated in "
|
||
"the following diagram."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:392
|
||
msgid "Loggers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:394
|
||
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:400
|
||
msgid ""
|
||
"The most widely used methods on logger objects fall into two categories: "
|
||
"configuration and message sending."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:403
|
||
msgid "These are the most common configuration methods:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:405
|
||
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:411
|
||
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:415
|
||
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:419
|
||
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:422
|
||
msgid ""
|
||
"With the logger object configured, the following methods create log messages:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:424
|
||
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 :const:`%s`, :const:`%d`, :const:`%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 :const:`**kwargs`, the "
|
||
"logging methods care only about a keyword of :const:`exc_info` and use it to "
|
||
"determine whether to log exception information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:434
|
||
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:438
|
||
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:442
|
||
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:450
|
||
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:458
|
||
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:469
|
||
msgid "Handlers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:471
|
||
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:481
|
||
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:485
|
||
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:490
|
||
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:496
|
||
msgid ""
|
||
":meth:`~Handler.setFormatter` selects a Formatter object for this handler to "
|
||
"use."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:499
|
||
msgid ""
|
||
":meth:`~Handler.addFilter` and :meth:`~Handler.removeFilter` respectively "
|
||
"configure and deconfigure filter objects on handlers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:502
|
||
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:509
|
||
msgid "Formatters"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:511
|
||
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 two optional arguments -- a message format string and a date format "
|
||
"string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:519
|
||
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:524
|
||
msgid "with the milliseconds tacked on at the end."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:526
|
||
msgid ""
|
||
"The message format string uses ``%(<dictionary key>)s`` styled string "
|
||
"substitution; the possible keys are documented in :ref:`logrecord-"
|
||
"attributes`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:529
|
||
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:535
|
||
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:545
|
||
msgid "Configuring Logging"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:549
|
||
msgid "Programmers can configure logging in three ways:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:551
|
||
msgid ""
|
||
"Creating loggers, handlers, and formatters explicitly using Python code that "
|
||
"calls the configuration methods listed above."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:553
|
||
msgid ""
|
||
"Creating a logging config file and reading it using the :func:`fileConfig` "
|
||
"function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:555
|
||
msgid ""
|
||
"Creating a dictionary of configuration information and passing it to the :"
|
||
"func:`dictConfig` function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:558
|
||
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:588
|
||
msgid ""
|
||
"Running this module from the command line produces the following output::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:597
|
||
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:616
|
||
msgid "Here is the logging.conf file::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:647
|
||
msgid ""
|
||
"The output is nearly identical to that of the non-config-file-based example::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:656
|
||
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:660
|
||
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:668
|
||
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:677
|
||
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:685
|
||
msgid ""
|
||
"In Python 2.7, 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:697
|
||
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:719
|
||
msgid ""
|
||
"For more information about logging using a dictionary, see :ref:`logging-"
|
||
"config-api`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:723
|
||
msgid "What happens if no configuration is provided"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:725
|
||
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:730
|
||
msgid "For Python 2.x, the behaviour is as follows:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:732
|
||
msgid ""
|
||
"If *logging.raiseExceptions* is *False* (production mode), the event is "
|
||
"silently dropped."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:735
|
||
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:741
|
||
msgid "Configuring Logging for a Library"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:743
|
||
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 configure logging, and "
|
||
"library code makes logging calls, then (as described in the previous "
|
||
"section) an error message will be printed to ``sys.stderr``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:750
|
||
msgid ""
|
||
"If for some reason you *don't* want this message 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:759
|
||
msgid ""
|
||
"A do-nothing handler is included in the logging package: :class:`~logging."
|
||
"NullHandler` (since Python 2.7). 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 an error message 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:770
|
||
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:774
|
||
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:785
|
||
msgid "Logging Levels"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:787
|
||
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:794
|
||
msgid "Numeric value"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:796
|
||
msgid "50"
|
||
msgstr "50"
|
||
|
||
#: ../Doc/howto/logging.rst:798
|
||
msgid "40"
|
||
msgstr "40"
|
||
|
||
#: ../Doc/howto/logging.rst:800
|
||
msgid "30"
|
||
msgstr "30"
|
||
|
||
#: ../Doc/howto/logging.rst:802
|
||
msgid "20"
|
||
msgstr "20"
|
||
|
||
#: ../Doc/howto/logging.rst:804
|
||
msgid "10"
|
||
msgstr "10"
|
||
|
||
#: ../Doc/howto/logging.rst:806
|
||
msgid "``NOTSET``"
|
||
msgstr "``NOTSET``"
|
||
|
||
#: ../Doc/howto/logging.rst:806
|
||
msgid "0"
|
||
msgstr "0"
|
||
|
||
#: ../Doc/howto/logging.rst:809
|
||
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:816
|
||
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:820
|
||
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:834
|
||
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:843
|
||
msgid "Custom Levels"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:845
|
||
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:858
|
||
msgid "Useful Handlers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:860
|
||
msgid ""
|
||
"In addition to the base :class:`Handler` class, many useful subclasses are "
|
||
"provided:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:863
|
||
msgid ""
|
||
":class:`StreamHandler` instances send messages to streams (file-like "
|
||
"objects)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:866
|
||
msgid ":class:`FileHandler` instances send messages to disk files."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:868
|
||
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:873
|
||
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:876
|
||
msgid ""
|
||
":class:`~handlers.TimedRotatingFileHandler` instances send messages to disk "
|
||
"files, rotating the log file at certain timed intervals."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:879
|
||
msgid ""
|
||
":class:`~handlers.SocketHandler` instances send messages to TCP/IP sockets."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:882
|
||
msgid ""
|
||
":class:`~handlers.DatagramHandler` instances send messages to UDP sockets."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:885
|
||
msgid ""
|
||
":class:`~handlers.SMTPHandler` instances send messages to a designated email "
|
||
"address."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:888
|
||
msgid ""
|
||
":class:`~handlers.SysLogHandler` instances send messages to a Unix syslog "
|
||
"daemon, possibly on a remote machine."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:891
|
||
msgid ""
|
||
":class:`~handlers.NTEventLogHandler` instances send messages to a Windows "
|
||
"NT/2000/XP event log."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:894
|
||
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:897
|
||
msgid ""
|
||
":class:`~handlers.HTTPHandler` instances send messages to an HTTP server "
|
||
"using either ``GET`` or ``POST`` semantics."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:900
|
||
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:905
|
||
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:911
|
||
msgid "The :class:`NullHandler` class."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:914
|
||
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:919
|
||
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:923
|
||
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:928
|
||
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:935
|
||
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:943
|
||
msgid "Exceptions raised during logging"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:945
|
||
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:950
|
||
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:955
|
||
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:960
|
||
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:969
|
||
msgid "Using arbitrary objects as messages"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:971
|
||
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:982
|
||
msgid "Optimization"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:984
|
||
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:996
|
||
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:999
|
||
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:1008
|
||
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:1014
|
||
msgid "What you don't want to collect"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1014
|
||
msgid "How to avoid collecting it"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1016
|
||
msgid "Information about where calls were made from."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1016
|
||
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`)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1023
|
||
msgid "Threading information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1023
|
||
msgid "Set ``logging.logThreads`` to ``0``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1025
|
||
msgid "Process information."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1025
|
||
msgid "Set ``logging.logProcesses`` to ``0``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1028
|
||
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:1035
|
||
msgid "Module :mod:`logging`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1035
|
||
msgid "API reference for the logging module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1038
|
||
msgid "Module :mod:`logging.config`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1038
|
||
msgid "Configuration API for the logging module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1041
|
||
msgid "Module :mod:`logging.handlers`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1041
|
||
msgid "Useful handlers included with the logging module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging.rst:1043
|
||
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:74
|
||
msgid "The output looks like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:98
|
||
msgid "Logging from multiple threads"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:100
|
||
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:129
|
||
msgid "When run, the script should print something like the following::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:149
|
||
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:153
|
||
msgid "Multiple handlers and formatters"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:155
|
||
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:188
|
||
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:191
|
||
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:202
|
||
msgid "Logging to multiple destinations"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:204
|
||
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:242
|
||
msgid "When you run this, on the console you will see ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:249
|
||
msgid "and in the file you will see something like ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:257
|
||
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:260
|
||
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:265
|
||
msgid "Configuration server example"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:267
|
||
msgid "Here is an example of a module using the logging configuration server::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:298
|
||
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:323
|
||
msgid "Sending and receiving logging events across a network"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:325
|
||
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:353
|
||
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:441
|
||
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:451
|
||
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:461
|
||
msgid "Adding contextual information to your logging output"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:465
|
||
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:480
|
||
msgid "Using LoggerAdapters to impart contextual information"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:482
|
||
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:490
|
||
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:506
|
||
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:515
|
||
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:531
|
||
msgid "which you can use like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:536
|
||
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:540
|
||
msgid "Using objects other than dicts to pass contextual information"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:542
|
||
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:551
|
||
msgid "Using Filters to impart contextual information"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:553
|
||
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:558
|
||
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:604
|
||
msgid "which, when run, produces something like::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:623
|
||
msgid "Logging to a single file from multiple processes"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:625
|
||
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:638
|
||
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:649
|
||
msgid "Using file rotation"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:654
|
||
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:686
|
||
msgid ""
|
||
"The result should be 6 separate files, each with part of the log history for "
|
||
"the application::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:696
|
||
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:701
|
||
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:705
|
||
msgid "An example dictionary-based configuration"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:707
|
||
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.3/topics/logging/#configuring-logging>`_. This dictionary is passed to :"
|
||
"func:`~config.dictConfig` to put the configuration into effect::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:763
|
||
msgid ""
|
||
"For more information about this configuration, you can see the `relevant "
|
||
"section <https://docs.djangoproject.com/en/1.6/topics/logging/#configuring-"
|
||
"logging>`_ of the Django documentation."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:768
|
||
msgid "Inserting a BOM into messages sent to a SysLogHandler"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:770
|
||
msgid ""
|
||
"`RFC 5424 <http://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 <http://tools.ietf.org/html/"
|
||
"rfc5424#section-6>`_.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:776
|
||
msgid ""
|
||
"In Python 2.6 and 2.7, 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:782
|
||
msgid ""
|
||
"As this behaviour is broken, the incorrect BOM insertion code is being "
|
||
"removed from Python 2.7.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:788
|
||
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:794
|
||
msgid ""
|
||
"The Unicode code point ``u'\\ufeff'``, when encoded using UTF-8, will be "
|
||
"encoded as a UTF-8 BOM -- the byte-string ``'\\xef\\xbb\\xbf'``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:797
|
||
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:801
|
||
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:805
|
||
msgid ""
|
||
"If the formatted message is Unicode, it *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:813
|
||
msgid "Implementing structured logging"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:815
|
||
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:839
|
||
msgid "If the above script is run, it prints::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:843 ../Doc/howto/logging-cookbook.rst:890
|
||
msgid ""
|
||
"Note that the order of items might be different according to the version of "
|
||
"Python used."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:846
|
||
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:886
|
||
msgid "When the above script is run, it prints::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:899
|
||
msgid "Customizing handlers with :func:`dictConfig`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:901
|
||
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:`os.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:920
|
||
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:953
|
||
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:1000
|
||
msgid "To run this, you will probably need to run as ``root``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1008
|
||
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:1014
|
||
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:1019
|
||
msgid "you could use e.g.::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1023
|
||
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:1028
|
||
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:1032
|
||
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:1040
|
||
msgid "Configuring filters with :func:`dictConfig`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1042
|
||
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:1095
|
||
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:1101
|
||
msgid "which shows that the filter is working as configured."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1103
|
||
msgid "A couple of extra points to note:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1105
|
||
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:1112
|
||
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:1121
|
||
msgid "Customized exception formatting"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1123
|
||
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:1164
|
||
msgid "When run, this produces a file with exactly two lines::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1169
|
||
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:1176
|
||
msgid "Speaking logging messages"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1178
|
||
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:1220
|
||
msgid ""
|
||
"When run, this script should say \"Hello\" and then \"Goodbye\" in a female "
|
||
"voice."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1222
|
||
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:1229
|
||
msgid "Buffering logging messages and outputting them conditionally"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1231
|
||
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:1238
|
||
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:1248
|
||
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 that 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:1254
|
||
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:1262
|
||
msgid "Here's the script::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1325
|
||
msgid "When this script is run, the following output should be observed::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1353
|
||
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:1357
|
||
msgid "You can of course use the conventional means of decoration::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1367
|
||
msgid "Formatting times using UTC (GMT) via configuration"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1369
|
||
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:1378
|
||
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:1421
|
||
msgid "When this script is run, it should print something like::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/logging-cookbook.rst:1426
|
||
msgid ""
|
||
"showing how the time is formatted both as local time and UTC, one for each "
|
||
"handler."
|
||
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 ""
|
||
"Update your code to drop support for Python 2.5 or older (supporting only "
|
||
"Python 2.7 is ideal)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:33
|
||
msgid ""
|
||
"Make sure you have good test coverage (coverage.py_ can help; ``pip install "
|
||
"coverage``)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:35 ../Doc/howto/pyporting.rst:114
|
||
#: ../Doc/howto/pyporting.rst:369
|
||
msgid "Learn the differences between Python 2 & 3"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:36
|
||
msgid ""
|
||
"Use Modernize_ or Futurize_ to update your code (``pip install modernize`` "
|
||
"or ``pip install future``, respectively)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:38
|
||
msgid ""
|
||
"Use Pylint_ to help make sure you don't regress on your Python 3 support (if "
|
||
"only supporting Python 2.7/3.4 or newer; ``pip install pylint``)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:40
|
||
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:42
|
||
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:46
|
||
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:52
|
||
msgid "Details"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:54
|
||
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:60
|
||
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:66
|
||
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:71
|
||
msgid "Drop support for Python 2.5 and older (at least)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:73
|
||
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.6 or newer (and easier still 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:80
|
||
msgid ""
|
||
"If you are able to only support Python 2.6 or newer, 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:86
|
||
msgid ""
|
||
"But please aim for Python 2.7. Bugfixes for that version of Python will "
|
||
"continue until 2020 while Python 2.6 is no longer supported. 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."
|
||
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 its own ``__div__`` method but not "
|
||
"``__floordiv__`` then your code would begin to fail."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:176
|
||
msgid "Text versus binary data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:178
|
||
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:187
|
||
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:196
|
||
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)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:212
|
||
msgid "**Text data**"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:212
|
||
msgid "**Binary data**"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:214
|
||
msgid "__mod__ (``%`` operator)"
|
||
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:286
|
||
msgid "Prevent compatibility regressions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:288
|
||
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:293
|
||
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:301
|
||
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:307
|
||
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:316
|
||
msgid "Check which dependencies block your transition"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:318
|
||
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:325
|
||
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:331
|
||
msgid "Update your ``setup.py`` file to denote Python 3 compatibility"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:333
|
||
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:341
|
||
msgid "Use continuous integration to stay compatible"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:343
|
||
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:349
|
||
msgid ""
|
||
"You may also want to use use the ``-bb`` flag with the Python 3 interpreter "
|
||
"to trigger an exception when you are comparing bytes to strings. Usually "
|
||
"it's simply ``False``, but if you made a mistake in your separation of text/"
|
||
"binary data handling you may be accidentally comparing text and binary data. "
|
||
"This flag will raise an exception when that occurs to help track down such "
|
||
"cases."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:355
|
||
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:362
|
||
msgid "Dropping Python 2 support completely"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:364
|
||
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:367
|
||
msgid "Update your code to only support Python 2.7"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:368
|
||
msgid "Make sure you have good test coverage (coverage.py_ can help)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:370
|
||
msgid "Use 2to3_ to rewrite your code to run only under Python 3"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/pyporting.rst:372
|
||
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 ""
|
||
"The :mod:`re` module was added in Python 1.5, and provides Perl-style "
|
||
"regular expression patterns. Earlier versions of Python came with the :mod:"
|
||
"`regex` module, which provided Emacs-style patterns. The :mod:`regex` "
|
||
"module was removed completely in Python 2.5."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:31
|
||
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:40
|
||
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:47
|
||
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:56
|
||
msgid "Simple Patterns"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:58
|
||
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:62
|
||
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:68
|
||
msgid "Matching Characters"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:70
|
||
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:75
|
||
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:81
|
||
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:86
|
||
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:95
|
||
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:100
|
||
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:105
|
||
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:112
|
||
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. The following "
|
||
"predefined special sequences are a subset of those available. The equivalent "
|
||
"classes are for byte string patterns. 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>`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:121
|
||
msgid "``\\d``"
|
||
msgstr "``\\d``"
|
||
|
||
#: ../Doc/howto/regex.rst:121
|
||
msgid "Matches any decimal digit; this is equivalent to the class ``[0-9]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:124
|
||
msgid "``\\D``"
|
||
msgstr "``\\D``"
|
||
|
||
#: ../Doc/howto/regex.rst:124
|
||
msgid ""
|
||
"Matches any non-digit character; this is equivalent to the class ``[^0-9]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:128
|
||
msgid "``\\s``"
|
||
msgstr "``\\s``"
|
||
|
||
#: ../Doc/howto/regex.rst:127
|
||
msgid ""
|
||
"Matches any whitespace character; this is equivalent to the class ``[ \\t\\n"
|
||
"\\r\\f\\v]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:132
|
||
msgid "``\\S``"
|
||
msgstr "``\\S``"
|
||
|
||
#: ../Doc/howto/regex.rst:131
|
||
msgid ""
|
||
"Matches any non-whitespace character; this is equivalent to the class ``[^ "
|
||
"\\t\\n\\r\\f\\v]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:136
|
||
msgid "``\\w``"
|
||
msgstr "``\\w``"
|
||
|
||
#: ../Doc/howto/regex.rst:135
|
||
msgid ""
|
||
"Matches any alphanumeric character; this is equivalent to the class ``[a-zA-"
|
||
"Z0-9_]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:140
|
||
msgid "``\\W``"
|
||
msgstr "``\\W``"
|
||
|
||
#: ../Doc/howto/regex.rst:139
|
||
msgid ""
|
||
"Matches any non-alphanumeric character; this is equivalent to the class "
|
||
"``[^a-zA-Z0-9_]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:142
|
||
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:146
|
||
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:153
|
||
msgid "Repeating Things"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:155
|
||
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:161
|
||
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:165
|
||
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; you probably "
|
||
"don't have enough memory to construct a string that large, so you shouldn't "
|
||
"run into that limit."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:172
|
||
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:177
|
||
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:183
|
||
msgid "Step"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:183
|
||
msgid "Matched"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:183
|
||
msgid "Explanation"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:185
|
||
msgid "1"
|
||
msgstr "1"
|
||
|
||
#: ../Doc/howto/regex.rst:185
|
||
msgid "``a``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:185
|
||
msgid "The ``a`` in the RE matches."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:187
|
||
msgid "2"
|
||
msgstr "2"
|
||
|
||
#: ../Doc/howto/regex.rst:187
|
||
msgid "``abcbd``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:187
|
||
msgid ""
|
||
"The engine matches ``[bcd]*``, going as far as it can, which is to the end "
|
||
"of the string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:191
|
||
msgid "3"
|
||
msgstr "3"
|
||
|
||
#: ../Doc/howto/regex.rst:191 ../Doc/howto/regex.rst:199
|
||
msgid "*Failure*"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:191
|
||
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:196
|
||
msgid "4"
|
||
msgstr "4"
|
||
|
||
#: ../Doc/howto/regex.rst:196 ../Doc/howto/regex.rst:207
|
||
msgid "``abcb``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:196
|
||
msgid "Back up, so that ``[bcd]*`` matches one less character."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:199
|
||
msgid "5"
|
||
msgstr "5"
|
||
|
||
#: ../Doc/howto/regex.rst:199
|
||
msgid ""
|
||
"Try ``b`` again, but the current position is at the last character, which is "
|
||
"a ``'d'``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:203 ../Doc/howto/regex.rst:207
|
||
msgid "6"
|
||
msgstr "6"
|
||
|
||
#: ../Doc/howto/regex.rst:203
|
||
msgid "``abc``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:203
|
||
msgid "Back up again, so that ``[bcd]*`` is only matching ``bc``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:207
|
||
msgid ""
|
||
"Try ``b`` again. This time the character at the current position is "
|
||
"``'b'``, so it succeeds."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:213
|
||
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:220
|
||
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:227
|
||
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:232
|
||
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:238
|
||
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:243
|
||
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:251
|
||
msgid "Using Regular Expressions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:253
|
||
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:260
|
||
msgid "Compiling Regular Expressions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:262
|
||
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:271
|
||
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:277
|
||
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:284
|
||
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:289
|
||
msgid "The Backslash Plague"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:291
|
||
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:296
|
||
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:305
|
||
msgid "Characters"
|
||
msgstr "Caractères"
|
||
|
||
#: ../Doc/howto/regex.rst:305
|
||
msgid "Stage"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:307
|
||
msgid "``\\section``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:307
|
||
msgid "Text string to be matched"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:309
|
||
msgid "``\\\\section``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:309
|
||
msgid "Escaped backslash for :func:`re.compile`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:311 ../Doc/howto/regex.rst:331
|
||
msgid "``\"\\\\\\\\section\"``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:311
|
||
msgid "Escaped backslashes for a string literal"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:314
|
||
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:320
|
||
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:327
|
||
msgid "Regular String"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:327
|
||
msgid "Raw string"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:329
|
||
msgid "``\"ab*\"``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:329
|
||
msgid "``r\"ab*\"``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:331
|
||
msgid "``r\"\\\\section\"``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:333
|
||
msgid "``\"\\\\w+\\\\s+\\\\1\"``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:333
|
||
msgid "``r\"\\w+\\s+\\1\"``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:338
|
||
msgid "Performing Matches"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:340
|
||
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:346 ../Doc/howto/regex.rst:407
|
||
#: ../Doc/howto/regex.rst:1040
|
||
msgid "Method/Attribute"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:346 ../Doc/howto/regex.rst:407
|
||
#: ../Doc/howto/regex.rst:1040
|
||
msgid "Purpose"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:348
|
||
msgid "``match()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:348
|
||
msgid "Determine if the RE matches at the beginning of the string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:351
|
||
msgid "``search()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:351
|
||
msgid "Scan through a string, looking for any location where this RE matches."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:354
|
||
msgid "``findall()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:354
|
||
msgid "Find all substrings where the RE matches, and returns them as a list."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:357
|
||
msgid "``finditer()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:357
|
||
msgid ""
|
||
"Find all substrings where the RE matches, and returns them as an :term:"
|
||
"`iterator`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:361
|
||
msgid ""
|
||
":meth:`match` and :meth:`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:366
|
||
msgid ""
|
||
"You can learn about this by interactively experimenting with the :mod:`re` "
|
||
"module. If you have Tkinter available, you may also want to look at :source:"
|
||
"`Tools/scripts/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. Phil Schwartz's `Kodos <http://kodos.sourceforge."
|
||
"net/>`_ is also an interactive tool for developing and testing RE patterns."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:375
|
||
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:384
|
||
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:394
|
||
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:402
|
||
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:409
|
||
msgid "``group()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:409
|
||
msgid "Return the string matched by the RE"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:411
|
||
msgid "``start()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:411
|
||
msgid "Return the starting position of the match"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:413
|
||
msgid "``end()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:413
|
||
msgid "Return the ending position of the match"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:415
|
||
msgid "``span()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:415
|
||
msgid "Return a tuple containing the (start, end) positions of the match"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:419
|
||
msgid "Trying these methods will soon clarify their meaning::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:428
|
||
msgid ""
|
||
":meth:`group` returns the substring that was matched by the RE. :meth:"
|
||
"`start` and :meth:`end` return the starting and ending index of the match. :"
|
||
"meth:`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:445
|
||
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:456
|
||
msgid ""
|
||
"Two pattern methods return all of the matches for a pattern. :meth:`findall` "
|
||
"returns a list of matching strings::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:463
|
||
msgid ""
|
||
":meth:`findall` has to create the entire list before it can be returned as "
|
||
"the result. The :meth:`finditer` method returns a sequence of :ref:`match "
|
||
"object <match-objects>` instances as an :term:`iterator`. [#]_ ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:479
|
||
msgid "Module-Level Functions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:481
|
||
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:`match`, :func:"
|
||
"`search`, :func:`findall`, :func:`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:493
|
||
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 are faster."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:497
|
||
msgid ""
|
||
"Should you use these module-level functions, or should you get the pattern "
|
||
"and call its methods yourself? That choice depends on how frequently the RE "
|
||
"will be used, and on your personal coding style. If the RE is being used at "
|
||
"only one point in the code, then the module functions are probably more "
|
||
"convenient. If a program contains a lot of regular expressions, or re-uses "
|
||
"the same ones in several locations, then it might be worthwhile to collect "
|
||
"all the definitions in one place, in a section of code that compiles all the "
|
||
"REs ahead of time. To take an example from the standard library, here's an "
|
||
"extract from the deprecated :mod:`xmllib` module::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:512
|
||
msgid ""
|
||
"I generally prefer to work with the compiled object, even for one-time uses, "
|
||
"but few people will be as much of a purist about this as I am."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:517
|
||
msgid "Compilation Flags"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:519
|
||
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:527
|
||
msgid ""
|
||
"Here's a table of the available flags, followed by a more detailed "
|
||
"explanation of each one."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:531
|
||
msgid "Flag"
|
||
msgstr "Option"
|
||
|
||
#: ../Doc/howto/regex.rst:531
|
||
msgid "Meaning"
|
||
msgstr "Signification"
|
||
|
||
#: ../Doc/howto/regex.rst:533
|
||
msgid ":const:`DOTALL`, :const:`S`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:533
|
||
msgid "Make ``.`` match any character, including newlines"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:536
|
||
msgid ":const:`IGNORECASE`, :const:`I`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:536
|
||
msgid "Do case-insensitive matches"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:538
|
||
msgid ":const:`LOCALE`, :const:`L`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:538
|
||
msgid "Do a locale-aware match"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:540
|
||
msgid ":const:`MULTILINE`, :const:`M`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:540
|
||
msgid "Multi-line matching, affecting ``^`` and ``$``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:543
|
||
msgid ":const:`VERBOSE`, :const:`X`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:543
|
||
msgid ""
|
||
"Enable verbose REs, which can be organized more cleanly and understandably."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:546
|
||
msgid ":const:`UNICODE`, :const:`U`"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:546
|
||
msgid ""
|
||
"Makes several escapes like ``\\w``, ``\\b``, ``\\s`` and ``\\d`` dependent "
|
||
"on the Unicode character database."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:556
|
||
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:567
|
||
msgid ""
|
||
"Make ``\\w``, ``\\W``, ``\\b``, and ``\\B``, dependent on the current locale."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:569
|
||
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:584
|
||
msgid ""
|
||
"(``^`` and ``$`` haven't been explained yet; they'll be introduced in "
|
||
"section :ref:`more-metacharacters`.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:587
|
||
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:600
|
||
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:608
|
||
msgid ""
|
||
"Make ``\\w``, ``\\W``, ``\\b``, ``\\B``, ``\\d``, ``\\D``, ``\\s`` and ``"
|
||
"\\S`` dependent on the Unicode character properties database."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:616
|
||
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:625
|
||
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:638
|
||
msgid "Without the verbose setting, the RE would look like this::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:644
|
||
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:650
|
||
msgid "More Pattern Power"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:652
|
||
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:660
|
||
msgid "More Metacharacters"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:662
|
||
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:665
|
||
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:681
|
||
msgid "``|``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:674
|
||
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:680
|
||
msgid ""
|
||
"To match a literal ``'|'``, use ``\\|``, or enclose it inside a character "
|
||
"class, as in ``[|]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:697
|
||
msgid "``^``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:684
|
||
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:688
|
||
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:711
|
||
msgid "``$``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:700
|
||
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:710
|
||
msgid ""
|
||
"To match a literal ``'$'``, use ``\\$`` or enclose it inside a character "
|
||
"class, as in ``[$]``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:717
|
||
msgid "``\\A``"
|
||
msgstr "``\\A``"
|
||
|
||
#: ../Doc/howto/regex.rst:714
|
||
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:720
|
||
msgid "``\\Z``"
|
||
msgstr "``\\Z``"
|
||
|
||
#: ../Doc/howto/regex.rst:720
|
||
msgid "Matches only at the end of the string."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:755
|
||
msgid "``\\b``"
|
||
msgstr "``\\b``"
|
||
|
||
#: ../Doc/howto/regex.rst:723
|
||
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:728
|
||
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:739
|
||
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:753
|
||
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:760
|
||
msgid "``\\B``"
|
||
msgstr "``\\B``"
|
||
|
||
#: ../Doc/howto/regex.rst:758
|
||
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:763
|
||
msgid "Grouping"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:765
|
||
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:776
|
||
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:780
|
||
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:791
|
||
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:806
|
||
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:819
|
||
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:825
|
||
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:831
|
||
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:839
|
||
msgid "For example, the following RE detects doubled words in a string. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:845
|
||
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:851
|
||
msgid "Non-capturing and Named Groups"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:853
|
||
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:859
|
||
msgid ""
|
||
"Perl 5 added several additional features to standard regular expressions, "
|
||
"and the Python :mod:`re` module supports most of them. It would have been "
|
||
"difficult to choose new single-keystroke metacharacters or new special "
|
||
"sequences beginning with ``\\`` to represent the new features without making "
|
||
"Perl's regular expressions confusingly different from standard REs. If you "
|
||
"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:867
|
||
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:875
|
||
msgid ""
|
||
"Python 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. Currently there are two such "
|
||
"extensions: ``(?P<name>...)`` defines a named group, and ``(?P=name)`` is a "
|
||
"backreference to a named group. If future versions of Perl 5 add similar "
|
||
"features using a different syntax, the :mod:`re` module will be changed to "
|
||
"support the new syntax, while preserving the Python-specific syntax for "
|
||
"compatibility's sake."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:883
|
||
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. Since groups are "
|
||
"numbered from left to right and a complex expression may use many groups, it "
|
||
"can become difficult to keep track of the correct numbering. Modifying such "
|
||
"a complex RE is annoying, too: insert a new group near the beginning and you "
|
||
"change the numbers of everything that follows it."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:890
|
||
msgid ""
|
||
"Sometimes you'll want to use a group to collect 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:902
|
||
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:911
|
||
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:914
|
||
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 "
|
||
"also 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:929
|
||
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:940
|
||
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:943
|
||
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:956
|
||
msgid "Lookahead Assertions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:958
|
||
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:966
|
||
msgid "``(?=...)``"
|
||
msgstr "``(?=...)``"
|
||
|
||
#: ../Doc/howto/regex.rst:962
|
||
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:971
|
||
msgid "``(?!...)``"
|
||
msgstr "``(?!...)``"
|
||
|
||
#: ../Doc/howto/regex.rst:969
|
||
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:973
|
||
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:978
|
||
msgid "The pattern to match this is quite simple:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:980
|
||
msgid "``.*[.].*$``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:982
|
||
msgid ""
|
||
"Notice that the ``.`` needs to be treated specially because it's a "
|
||
"metacharacter; I've put it inside a character class. 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:988
|
||
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:991
|
||
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:995
|
||
msgid "``.*[.]([^b]..|.[^a].|..[^t])$``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:997
|
||
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:1005
|
||
msgid "``.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1007
|
||
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:1011
|
||
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:1016
|
||
msgid "A negative lookahead cuts through all this confusion:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1018
|
||
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:1025
|
||
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:1029
|
||
msgid "``.*[.](?!bat$|exe$)[^.]*$``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1033
|
||
msgid "Modifying Strings"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1035
|
||
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:1042
|
||
msgid "``split()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1042
|
||
msgid "Split the string into a list, splitting it wherever the RE matches"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1045
|
||
msgid "``sub()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1045
|
||
msgid ""
|
||
"Find all substrings where the RE matches, and replace them with a different "
|
||
"string"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1048
|
||
msgid "``subn()``"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1048
|
||
msgid ""
|
||
"Does the same thing as :meth:`sub`, but returns the new string and the "
|
||
"number of replacements"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1055
|
||
msgid "Splitting Strings"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1057
|
||
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; :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:1068
|
||
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:1073
|
||
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:1085
|
||
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:1097
|
||
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:1109
|
||
msgid "Search and Replace"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1111
|
||
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:1119
|
||
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:1123
|
||
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:1127
|
||
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:1136
|
||
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:1145
|
||
msgid ""
|
||
"Empty matches are replaced only when they're not adjacent to a previous "
|
||
"match. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1152
|
||
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 ``"
|
||
"\\j`` 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:1159
|
||
msgid ""
|
||
"This example matches the word ``section`` followed by a string enclosed in "
|
||
"``{``, ``}``, and changes ``section`` to ``subsection``::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1166
|
||
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:1183
|
||
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:1189
|
||
msgid ""
|
||
"In the following example, the replacement function translates decimals into "
|
||
"hexadecimal::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1201
|
||
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:1209
|
||
msgid "Common Problems"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1211
|
||
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:1217
|
||
msgid "Use String Methods"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1219
|
||
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:1227
|
||
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:1236
|
||
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:1242
|
||
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:1247
|
||
msgid "match() versus search()"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1249
|
||
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:1260
|
||
msgid ""
|
||
"On the other hand, :func:`search` will scan forward through the string, "
|
||
"reporting the first match it finds. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1268
|
||
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:1277
|
||
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:1283
|
||
msgid "Greedy versus Non-Greedy"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1285
|
||
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:1299
|
||
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:1306
|
||
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:1315
|
||
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:1323
|
||
msgid "Using re.VERBOSE"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1325
|
||
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:1330
|
||
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:1334
|
||
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:1351
|
||
msgid "This is far more readable than::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1357
|
||
msgid "Feedback"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/regex.rst:1359
|
||
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:1364
|
||
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/regex.rst:1374 ../Doc/howto/urllib2.rst:556
|
||
msgid "Footnotes"
|
||
msgstr "Notes"
|
||
|
||
#: ../Doc/howto/regex.rst:1375
|
||
msgid "Introduced in Python 2.2.2."
|
||
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 sockets, but they account for at least 99% "
|
||
"of the sockets in use. And I'll only talk about STREAM 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:66
|
||
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:72
|
||
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:84
|
||
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:91
|
||
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:95
|
||
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:99
|
||
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:110
|
||
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 "
|
||
"mulitplex 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:125
|
||
msgid "IPC"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:127
|
||
msgid ""
|
||
"If you need fast IPC between two processes on one machine, you should look "
|
||
"into whatever form of shared memory the platform offers. A simple protocol "
|
||
"based around shared memory and locks or semaphores is by far the fastest "
|
||
"technique."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:131
|
||
msgid ""
|
||
"If you do decide to use 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:137
|
||
msgid "Using a Socket"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:139
|
||
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:146
|
||
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:155
|
||
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:163
|
||
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:168
|
||
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:172
|
||
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:183
|
||
msgid ""
|
||
"Assuming you don't want to end the connection, the simplest solution is a "
|
||
"fixed length message::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:220
|
||
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:226
|
||
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:234
|
||
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:240
|
||
msgid ""
|
||
"Prefixing the message with it's 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:249
|
||
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:255
|
||
msgid "Binary Data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:257
|
||
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:267
|
||
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:275
|
||
msgid "Disconnecting"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:277
|
||
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:285
|
||
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:292
|
||
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:300
|
||
msgid "When Sockets Die"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:302
|
||
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. SOCKSTREAM 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:316
|
||
msgid "Non-blocking Sockets"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:318
|
||
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:323
|
||
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:330
|
||
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:337
|
||
msgid "Use ``select``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:339
|
||
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:350
|
||
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:358
|
||
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:362
|
||
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:369
|
||
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:375
|
||
msgid ""
|
||
"One very nasty problem with ``select``: if somewhere in those input lists of "
|
||
"sockets is one which has died a nasty death, the ``select`` will fail. You "
|
||
"then need to loop through every single damn socket in all those lists and do "
|
||
"a ``select([sock],[],[],0)`` until you find the bad one. That timeout of 0 "
|
||
"means it won't take long, but it's ugly."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:381
|
||
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:386
|
||
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. Face it, if you want any kind of "
|
||
"performance, your code will look very different on Windows than on Unix."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:395
|
||
msgid "Performance"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:397
|
||
msgid ""
|
||
"There's no question that the fastest sockets code uses non-blocking sockets "
|
||
"and select to multiplex them. You can put together something that will "
|
||
"saturate a LAN connection without putting any strain on the CPU. The trouble "
|
||
"is that an app written this way can't do much of anything else - it needs to "
|
||
"be ready to shuffle bytes around at all times."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:403
|
||
msgid ""
|
||
"Assuming that your app is actually supposed to do something more than that, "
|
||
"threading is the optimal solution, (and using non-blocking sockets will be "
|
||
"faster than using blocking sockets). Unfortunately, threading support in "
|
||
"Unixes varies both in API and quality. So the normal Unix solution is to "
|
||
"fork a subprocess to deal with each connection. The overhead for this is "
|
||
"significant (and don't do this on Windows - the overhead of process creation "
|
||
"is enormous there). It also means that unless each subprocess is completely "
|
||
"independent, you'll need to use another form of IPC, say a pipe, or shared "
|
||
"memory and semaphores, to communicate between the parent and child processes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sockets.rst:413
|
||
msgid ""
|
||
"Finally, remember that even though blocking sockets are somewhat slower than "
|
||
"non-blocking, in many cases they are the \"right\" solution. After all, if "
|
||
"your app is driven by the data it receives over a socket, there's not much "
|
||
"sense in complicating the logic just so your app can wait on ``select`` "
|
||
"instead of ``recv``."
|
||
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 of a list. 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 ""
|
||
"Starting with Python 2.4, both :meth:`list.sort` and :func:`sorted` added a "
|
||
"*key* parameter to specify a function to be called on each list element "
|
||
"prior to making comparisons."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:49
|
||
msgid "For example, here's a case-insensitive string comparison:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:54
|
||
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:58
|
||
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:69
|
||
msgid ""
|
||
"The same technique works for objects with named attributes. For example:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:88
|
||
msgid "Operator Module Functions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:90
|
||
msgid ""
|
||
"The key-function patterns shown above are very common, so Python provides "
|
||
"convenience functions to make accessor functions easier and faster. The "
|
||
"operator module has :func:`operator.itemgetter`, :func:`operator."
|
||
"attrgetter`, and starting in Python 2.5 a :func:`operator.methodcaller` "
|
||
"function."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:95
|
||
msgid "Using those functions, the above examples become simpler and faster:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:105
|
||
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 ""
|
||
"The :func:`operator.methodcaller` function makes method calls with fixed "
|
||
"parameters for each object being sorted. For example, the :meth:`str.count` "
|
||
"method could be used to compute message priority by counting the number of "
|
||
"exclamation marks in a message:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:124
|
||
msgid "Ascending and Descending"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:126
|
||
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:137
|
||
msgid "Sort Stability and Complex Sorts"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:139
|
||
msgid ""
|
||
"Starting with Python 2.2, sorts are guaranteed to be `stable <http://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:147
|
||
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:150
|
||
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:158
|
||
msgid ""
|
||
"The `Timsort <http://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:163
|
||
msgid "The Old Way Using Decorate-Sort-Undecorate"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:165
|
||
msgid "This idiom is called Decorate-Sort-Undecorate after its three steps:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:167
|
||
msgid ""
|
||
"First, the initial list is decorated with new values that control the sort "
|
||
"order."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:169
|
||
msgid "Second, the decorated list is sorted."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:171
|
||
msgid ""
|
||
"Finally, the decorations are removed, creating a list that contains only the "
|
||
"initial values in the new order."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:174
|
||
msgid ""
|
||
"For example, to sort the student data by *grade* using the DSU approach:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:181
|
||
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:185
|
||
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:188
|
||
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:191
|
||
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:196
|
||
msgid ""
|
||
"Another name for this idiom is `Schwartzian transform <http://en.wikipedia."
|
||
"org/wiki/Schwartzian_transform>`_\\, after Randal L. Schwartz, who "
|
||
"popularized it among Perl programmers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:200
|
||
msgid ""
|
||
"For large lists and lists where the comparison information is expensive to "
|
||
"calculate, and Python versions before 2.4, DSU is likely to be the fastest "
|
||
"way to sort the list. For 2.4 and later, key functions provide the same "
|
||
"functionality."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:206
|
||
msgid "The Old Way Using the *cmp* Parameter"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:208
|
||
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:213
|
||
msgid ""
|
||
"In Python 3, 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:217
|
||
msgid ""
|
||
"In Python 2, :meth:`~list.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:227
|
||
msgid "Or you can reverse the order of comparison with:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:234
|
||
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:257
|
||
msgid "To convert to a key function, just wrap the old comparison function:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:262
|
||
msgid ""
|
||
"In Python 2.7, the :func:`functools.cmp_to_key` function was added to the "
|
||
"functools module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:266
|
||
msgid "Odd and Ends"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:268
|
||
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:271
|
||
msgid ""
|
||
"The *reverse* parameter still maintains sort stability (so that records with "
|
||
"equal keys retain their original order). Interestingly, that effect can be "
|
||
"simulated without the parameter by using the builtin :func:`reversed` "
|
||
"function twice:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:279
|
||
msgid ""
|
||
"To create a standard sort order for a class, just add the appropriate rich "
|
||
"comparison methods:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:291
|
||
msgid ""
|
||
"For general purpose comparisons, the recommended approach is to define all "
|
||
"six rich comparison operators. The :func:`functools.total_ordering` class "
|
||
"decorator makes this easy to implement."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/sorting.rst:295
|
||
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:3
|
||
msgid "Unicode HOWTO"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:5
|
||
msgid "1.03"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:7
|
||
msgid ""
|
||
"This HOWTO discusses Python 2.x's support for Unicode, and explains various "
|
||
"problems that people commonly encounter when trying to work with Unicode. "
|
||
"For the Python 3 version, see <https://docs.python.org/3/howto/unicode.html>."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:13
|
||
msgid "Introduction to Unicode"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:16
|
||
msgid "History of Character Codes"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:18
|
||
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. I "
|
||
"remember looking at Apple ][ BASIC programs, published in French-language "
|
||
"publications in the mid-1980s, that had lines like these::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:38
|
||
msgid ""
|
||
"Those messages should contain accents, 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-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. I don't think "
|
||
"the average Python programmer needs to worry about the historical details; "
|
||
"consult the Unicode consortium site listed in the References for more "
|
||
"information.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:78
|
||
msgid "Definitions"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:80
|
||
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:88
|
||
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 (4810 decimal). The Unicode standard contains a "
|
||
"lot of tables listing characters and their corresponding code points::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:100
|
||
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:106
|
||
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:115
|
||
msgid "Encodings"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:117
|
||
msgid ""
|
||
"To summarize the previous section: a Unicode string is a sequence of code "
|
||
"points, which are numbers from 0 to 0x10ffff. This sequence needs to be "
|
||
"represented as a set of bytes (meaning, values from 0-255) in memory. The "
|
||
"rules for translating a Unicode string into a sequence of bytes are called "
|
||
"an **encoding**."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:123
|
||
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:130
|
||
msgid ""
|
||
"This representation is straightforward but using it presents a number of "
|
||
"problems."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:133
|
||
msgid "It's not portable; different processors order the bytes differently."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:135
|
||
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 zero "
|
||
"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 megabytes 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:143
|
||
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:146
|
||
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:149
|
||
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:153
|
||
msgid ""
|
||
"Encodings don't have to handle every possible Unicode character, and most "
|
||
"encodings don't. For example, Python's default encoding is the 'ascii' "
|
||
"encoding. The rules for converting a Unicode string into the ASCII encoding "
|
||
"are simple; for each code point:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:158
|
||
msgid ""
|
||
"If the code point is < 128, each byte is the same as the value of the code "
|
||
"point."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:161
|
||
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:165
|
||
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:170
|
||
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:177
|
||
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's also a UTF-16 encoding, but it's less frequently "
|
||
"used than UTF-8.) UTF-8 uses the following rules:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:182
|
||
msgid ""
|
||
"If the code point is <128, it's represented by the corresponding byte value."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:183
|
||
msgid ""
|
||
"If the code point is between 128 and 0x7ff, it's turned into two byte values "
|
||
"between 128 and 255."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:185
|
||
msgid ""
|
||
"Code points >0x7ff are turned into three- or four-byte sequences, where each "
|
||
"byte of the sequence is between 128 and 255."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:188
|
||
msgid "UTF-8 has several convenient properties:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:190
|
||
msgid "It can handle any Unicode code point."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:191
|
||
msgid ""
|
||
"A Unicode string is turned into a string 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:195
|
||
msgid "A string of ASCII text is also valid UTF-8 text."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:196
|
||
msgid ""
|
||
"UTF-8 is fairly compact; the majority of code points are turned into two "
|
||
"bytes, and values less than 128 occupy only a single byte."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:198
|
||
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:207
|
||
msgid ""
|
||
"The Unicode Consortium site at <http://www.unicode.org> has character "
|
||
"charts, a glossary, and PDF versions of the Unicode specification. Be "
|
||
"prepared for some difficult reading. <http://www.unicode.org/history/> is a "
|
||
"chronology of the origin and development of Unicode."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:212
|
||
msgid ""
|
||
"To help understand the standard, Jukka Korpela has written an introductory "
|
||
"guide to reading the Unicode character tables, available at <http://www.cs."
|
||
"tut.fi/~jkorpela/unicode/guide.html>."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:216
|
||
msgid ""
|
||
"Another good introductory article was written by Joel Spolsky <http://www."
|
||
"joelonsoftware.com/articles/Unicode.html>. If this introduction didn't make "
|
||
"things clear to you, you should try reading this alternate article before "
|
||
"continuing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:223
|
||
msgid ""
|
||
"Wikipedia entries are often helpful; see the entries for \"character encoding"
|
||
"\" <http://en.wikipedia.org/wiki/Character_encoding> and UTF-8 <http://en."
|
||
"wikipedia.org/wiki/UTF-8>, for example."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:229
|
||
msgid "Python 2.x's Unicode Support"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:231
|
||
msgid ""
|
||
"Now that you've learned the rudiments of Unicode, we can look at Python's "
|
||
"Unicode features."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:236
|
||
msgid "The Unicode Type"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:238
|
||
msgid ""
|
||
"Unicode strings are expressed as instances of the :class:`unicode` type, one "
|
||
"of Python's repertoire of built-in types. It derives from an abstract type "
|
||
"called :class:`basestring`, which is also an ancestor of the :class:`str` "
|
||
"type; you can therefore check if a value is a string type with "
|
||
"``isinstance(value, basestring)``. Under the hood, Python represents "
|
||
"Unicode strings as either 16- or 32-bit integers, depending on how the "
|
||
"Python interpreter was compiled."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:245
|
||
msgid ""
|
||
"The :func:`unicode` constructor has the signature ``unicode(string[, "
|
||
"encoding, errors])``. All of its arguments should be 8-bit strings. The "
|
||
"first argument is converted to Unicode using the specified encoding; if you "
|
||
"leave off the ``encoding`` argument, the ASCII encoding is used for the "
|
||
"conversion, so characters greater than 127 will be treated as errors::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:262
|
||
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 ``UnicodeDecodeError`` exception), "
|
||
"'replace' (add U+FFFD, 'REPLACEMENT CHARACTER'), or 'ignore' (just leave the "
|
||
"character out of the Unicode result). The following examples show the "
|
||
"differences::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:278
|
||
msgid ""
|
||
"Encodings are specified as strings containing the encoding's name. Python "
|
||
"2.7 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:284
|
||
msgid ""
|
||
"One-character Unicode strings can also be created with the :func:`unichr` "
|
||
"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:295
|
||
msgid ""
|
||
"Instances of the :class:`unicode` type have many of the same methods as the "
|
||
"8-bit string type for operations such as searching and formatting::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:310
|
||
msgid ""
|
||
"Note that the arguments to these methods can be Unicode strings or 8-bit "
|
||
"strings. 8-bit strings will be converted to Unicode before carrying out the "
|
||
"operation; Python's default ASCII encoding will be used, so characters "
|
||
"greater than 127 will cause an exception::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:323
|
||
msgid ""
|
||
"Much Python code that operates on strings will therefore work with Unicode "
|
||
"strings without requiring any changes to the code. (Input and output code "
|
||
"needs more updating for Unicode; more on this later.)"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:327
|
||
msgid ""
|
||
"Another important method is ``.encode([encoding], [errors='strict'])``, "
|
||
"which returns an 8-bit string version of the Unicode string, encoded in the "
|
||
"requested encoding. The ``errors`` parameter is the same as the parameter "
|
||
"of the ``unicode()`` constructor, with one additional possibility; as well "
|
||
"as 'strict', 'ignore', and 'replace', you can also pass 'xmlcharrefreplace' "
|
||
"which uses XML's character references. The following example shows the "
|
||
"different results::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:349
|
||
msgid ""
|
||
"Python's 8-bit strings have a ``.decode([encoding], [errors])`` method that "
|
||
"interprets the string using the given encoding::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:360
|
||
msgid ""
|
||
"The low-level routines for registering and accessing the available encodings "
|
||
"are found in the :mod:`codecs` module. However, the encoding and decoding "
|
||
"functions returned by this module are usually more low-level than is "
|
||
"comfortable, so I'm not going to describe the :mod:`codecs` module here. If "
|
||
"you need to implement a completely new encoding, you'll need to learn about "
|
||
"the :mod:`codecs` module interfaces, but implementing encodings is a "
|
||
"specialized task that also won't be covered here. Consult the Python "
|
||
"documentation to learn more about this module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:368
|
||
msgid ""
|
||
"The most commonly used part of the :mod:`codecs` module is the :func:`codecs."
|
||
"open` function which will be discussed in the section on input and output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:374
|
||
msgid "Unicode Literals in Python Source Code"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:376
|
||
msgid ""
|
||
"In Python source code, Unicode literals are written as strings prefixed with "
|
||
"the 'u' or 'U' character: ``u'abcdefghijk'``. Specific 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 8 hex digits, not 4."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:382
|
||
msgid ""
|
||
"Unicode literals can also use the same escape sequences as 8-bit strings, "
|
||
"including ``\\x``, but ``\\x`` only takes two hex digits so it can't express "
|
||
"an arbitrary code point. Octal escapes can go up to U+01ff, which is octal "
|
||
"777."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:396
|
||
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:`unichr` built-in "
|
||
"function, but this is even more tedious."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:402
|
||
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:407
|
||
msgid ""
|
||
"Python supports writing Unicode literals in any encoding, but you have to "
|
||
"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:417
|
||
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:423
|
||
msgid ""
|
||
"If you don't include such a comment, the default encoding used will be "
|
||
"ASCII. Versions of Python before 2.4 were Euro-centric and assumed Latin-1 "
|
||
"as a default encoding for string literals; in Python 2.4, characters greater "
|
||
"than 127 still work but result in a warning. For example, the following "
|
||
"program has no encoding declaration::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:433
|
||
msgid "When you run it with Python 2.4, it will output the following warning::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:440
|
||
msgid "Python 2.5 and higher are stricter and will produce a syntax error::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:450
|
||
msgid "Unicode Properties"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:452
|
||
msgid ""
|
||
"The Unicode specification includes a database of information about code "
|
||
"points. For each code point that's defined, 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:459
|
||
msgid ""
|
||
"The following program displays some information about several characters, "
|
||
"and prints the numeric value of one particular character::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:473
|
||
msgid "When run, this prints::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:482
|
||
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 <http://www.unicode."
|
||
"org/reports/tr44/#General_Category_Values> for a list of category codes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:494
|
||
msgid ""
|
||
"The Unicode and 8-bit string types are described in the Python library "
|
||
"reference at :ref:`typesseq`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:497
|
||
msgid "The documentation for the :mod:`unicodedata` module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:499
|
||
msgid "The documentation for the :mod:`codecs` module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:501
|
||
msgid ""
|
||
"Marc-André Lemburg gave a presentation at EuroPython 2002 titled \"Python "
|
||
"and Unicode\". A PDF version of his slides is available at <https://"
|
||
"downloads.egenix.com/python/Unicode-EPC2002-Talk.pdf>, and is an excellent "
|
||
"overview of the design of Python's Unicode features."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:508
|
||
msgid "Reading and Writing Unicode Data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:510
|
||
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:514
|
||
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:520
|
||
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 string from it, and convert the string "
|
||
"with ``unicode(str, encoding)``. However, the manual approach is not "
|
||
"recommended."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:525
|
||
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, 1K or 4K), 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 2Gb file, "
|
||
"you need 2Gb 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:535
|
||
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 :mod:`codecs` module includes a version of the :func:"
|
||
"`open` function that returns a file-like object that assumes the file's "
|
||
"contents are in a specified encoding and accepts Unicode parameters for "
|
||
"methods such as ``.read()`` and ``.write()``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:542
|
||
msgid ""
|
||
"The function's parameters are ``open(filename, mode='rb', encoding=None, "
|
||
"errors='strict', buffering=1)``. ``mode`` can be ``'r'``, ``'w'``, or "
|
||
"``'a'``, just like the corresponding parameter to the regular built-in "
|
||
"``open()`` function; add a ``'+'`` to update the file. ``buffering`` is "
|
||
"similarly parallel to the standard function's parameter. ``encoding`` is a "
|
||
"string giving the encoding to use; if it's left as ``None``, a regular "
|
||
"Python file object that accepts 8-bit strings is returned. Otherwise, a "
|
||
"wrapper object is returned, and data written to or read from the wrapper "
|
||
"object will be converted as needed. ``errors`` specifies the action for "
|
||
"encoding errors and can be one of the usual values of 'strict', 'ignore', "
|
||
"and 'replace'."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:553
|
||
msgid "Reading Unicode from a file is therefore simple::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:560
|
||
msgid ""
|
||
"It's also possible to open files in update mode, allowing both reading and "
|
||
"writing::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:569
|
||
msgid ""
|
||
"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:580
|
||
msgid "Unicode filenames"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:582
|
||
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 ASCII."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:591
|
||
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:602
|
||
msgid ""
|
||
"Functions in the :mod:`os` module such as :func:`os.stat` will also accept "
|
||
"Unicode filenames."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:605
|
||
msgid ""
|
||
":func:`os.listdir`, which returns filenames, raises an issue: should it "
|
||
"return the Unicode version of filenames, or should it return 8-bit strings "
|
||
"containing the encoded versions? :func:`os.listdir` will do both, depending "
|
||
"on whether you provided the directory path as an 8-bit string 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 an 8-bit path will return the 8-bit versions of the "
|
||
"filenames. For example, assuming the default filesystem encoding is UTF-8, "
|
||
"running the following program::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:622
|
||
msgid "will produce the following output::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:628
|
||
msgid ""
|
||
"The first list contains UTF-8-encoded filenames, and the second list "
|
||
"contains the Unicode versions."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:634
|
||
msgid "Tips for Writing Unicode-aware Programs"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:636
|
||
msgid ""
|
||
"This section provides some suggestions on writing software that deals with "
|
||
"Unicode."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:639
|
||
msgid "The most important tip is:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:641
|
||
msgid ""
|
||
"Software should only work with Unicode strings internally, converting to a "
|
||
"particular encoding on output."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:644
|
||
msgid ""
|
||
"If you attempt to write processing functions that accept both Unicode and 8-"
|
||
"bit strings, you will find your program vulnerable to bugs wherever you "
|
||
"combine the two different kinds of strings. Python's default encoding is "
|
||
"ASCII, so whenever a character with an ASCII value > 127 is in the input "
|
||
"data, you'll get a :exc:`UnicodeDecodeError` because that character can't be "
|
||
"handled by the ASCII encoding."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:651
|
||
msgid ""
|
||
"It's easy to miss such problems if you only test your software with data "
|
||
"that doesn't contain any accents; everything will seem to work, but there's "
|
||
"actually a bug in your program waiting for the first user who attempts to "
|
||
"use characters > 127. A second tip, therefore, is:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:656
|
||
msgid ""
|
||
"Include characters > 127 and, even better, characters > 255 in your test "
|
||
"data."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:659
|
||
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 string once it's in the form that "
|
||
"will be used or stored; it's possible for encodings to be used to disguise "
|
||
"characters. This is especially true if the input data also specifies the "
|
||
"encoding; many encodings leave the commonly checked-for characters alone, "
|
||
"but Python includes some encodings such as ``'base64'`` that modify every "
|
||
"single character."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:668
|
||
msgid ""
|
||
"For example, let's say you have a content management system that takes a "
|
||
"Unicode filename, and you want to disallow paths with a '/' character. You "
|
||
"might write this code::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:679
|
||
msgid ""
|
||
"However, if an attacker could specify the ``'base64'`` encoding, they could "
|
||
"pass ``'L2V0Yy9wYXNzd2Q='``, which is the base-64 encoded form of the string "
|
||
"``'/etc/passwd'``, to read a system file. The above code looks for ``'/'`` "
|
||
"characters in the encoded form and misses the dangerous character in the "
|
||
"resulting decoded form."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:688
|
||
msgid ""
|
||
"The PDF slides for Marc-André Lemburg's presentation \"Writing Unicode-aware "
|
||
"Applications in Python\" are available at <https://downloads.egenix.com/"
|
||
"python/LSM2005-Developing-Unicode-aware-applications-in-Python.pdf> and "
|
||
"discuss questions of character encodings as well as how to internationalize "
|
||
"and localize an application."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:698
|
||
msgid ""
|
||
"Thanks to the following people who have noted errors or offered suggestions "
|
||
"on this article: Nicholas Bastin, Marius Gedminas, Kent Johnson, Ken "
|
||
"Krugler, Marc-André Lemburg, Martin von Löwis, Chad Whitacre."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:702
|
||
msgid "Version 1.0: posted August 5 2005."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:704
|
||
msgid ""
|
||
"Version 1.01: posted August 7 2005. Corrects factual and markup errors; "
|
||
"adds several links."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:707
|
||
msgid "Version 1.02: posted August 16 2005. Corrects factual errors."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/unicode.rst:709
|
||
msgid ""
|
||
"Version 1.03: posted June 20 2010. Notes that Python 3.x is not covered, "
|
||
"and that the HOWTO only covers 2.x."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:3
|
||
msgid "HOWTO Fetch Internet Resources Using urllib2"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:5
|
||
msgid "`Michael Foord <http://www.voidspace.org.uk/python/index.shtml>`_"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:9
|
||
msgid ""
|
||
"There is an 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:20
|
||
msgid ""
|
||
"You may also find useful the following article on fetching web resources "
|
||
"with Python:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:23
|
||
msgid ""
|
||
"`Basic Authentication <http://www.voidspace.org.uk/python/articles/"
|
||
"authentication.shtml>`_"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:25
|
||
msgid "A tutorial on *Basic Authentication*, with examples in Python."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:27
|
||
msgid ""
|
||
"**urllib2** 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:34
|
||
msgid ""
|
||
"urllib2 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:39
|
||
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 *urllib2*, with enough detail about HTTP to help you "
|
||
"through. It is not intended to replace the :mod:`urllib2` docs, but is "
|
||
"supplementary to them."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:49
|
||
msgid "Fetching URLs"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:51
|
||
msgid "The simplest way to use urllib2 is as follows::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:57
|
||
msgid ""
|
||
"Many uses of urllib2 will be that simple (note that instead of an 'http:' "
|
||
"URL we could have used an 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:62
|
||
msgid ""
|
||
"HTTP is based on requests and responses - the client makes requests and "
|
||
"servers send responses. urllib2 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:76
|
||
msgid ""
|
||
"Note that urllib2 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:81
|
||
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:88
|
||
msgid "Data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:90
|
||
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 ``urllib`` library *not* from ``urllib2``. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:113
|
||
msgid ""
|
||
"Note that other encodings are sometimes required (e.g. for file upload from "
|
||
"HTML forms - see `HTML Specification, Form Submission <http://www.w3.org/TR/"
|
||
"REC-html40/interact/forms.html#h-17.13>`_ for more details)."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:118
|
||
msgid ""
|
||
"If you do not pass the ``data`` argument, urllib2 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:128
|
||
msgid "This is done as follows::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:143
|
||
msgid ""
|
||
"Notice that the full URL is created by adding a ``?`` to the URL, followed "
|
||
"by the encoded values."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:147
|
||
msgid "Headers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:149
|
||
msgid ""
|
||
"We'll discuss here one particular HTTP header, to illustrate how to add "
|
||
"headers to your HTTP request."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:152
|
||
msgid ""
|
||
"Some websites [#]_ dislike being browsed by programs, or send different "
|
||
"versions to different browsers [#]_. By default urllib2 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:178
|
||
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:183
|
||
msgid "Handling Exceptions"
|
||
msgstr "Gestion des exceptions"
|
||
|
||
#: ../Doc/howto/urllib2.rst:185
|
||
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:189
|
||
msgid ""
|
||
":exc:`HTTPError` is the subclass of :exc:`URLError` raised in the specific "
|
||
"case of HTTP URLs."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:193
|
||
msgid "URLError"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:195
|
||
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:200 ../Doc/howto/urllib2.rst:445
|
||
msgid "e.g. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:211
|
||
msgid "HTTPError"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:213
|
||
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, urllib2 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:221
|
||
msgid "See section 10 of RFC 2616 for a reference on all the HTTP error codes."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:223
|
||
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:227
|
||
msgid "Error Codes"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:229
|
||
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:233
|
||
msgid ""
|
||
"``BaseHTTPServer.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:305
|
||
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. ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:326
|
||
msgid "Wrapping it Up"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:328
|
||
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:332
|
||
msgid "Number 1"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:353
|
||
msgid ""
|
||
"The ``except HTTPError`` *must* come first, otherwise ``except URLError`` "
|
||
"will *also* catch an :exc:`HTTPError`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:357
|
||
msgid "Number 2"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:377
|
||
msgid "info and geturl"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:379
|
||
msgid ""
|
||
"The response returned by urlopen (or the :exc:`HTTPError` instance) has two "
|
||
"useful methods :meth:`info` and :meth:`geturl`."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:382
|
||
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:386
|
||
msgid ""
|
||
"**info** - this returns a dictionary-like object that describes the page "
|
||
"fetched, particularly the headers sent by the server. It is currently an "
|
||
"``httplib.HTTPMessage`` instance."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:390
|
||
msgid ""
|
||
"Typical headers include 'Content-length', 'Content-type', and so on. See the "
|
||
"`Quick Reference to HTTP Headers <http://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:397
|
||
msgid "Openers and Handlers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:399
|
||
msgid ""
|
||
"When you fetch a URL you use an opener (an instance of the perhaps "
|
||
"confusingly-named :class:`urllib2.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:407
|
||
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:411
|
||
msgid ""
|
||
"To create an opener, instantiate an ``OpenerDirector``, and then call ``."
|
||
"add_handler(some_handler_instance)`` repeatedly."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:414
|
||
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:419
|
||
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:422
|
||
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:426
|
||
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:432
|
||
msgid "Basic Authentication"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:434
|
||
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:440
|
||
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:450
|
||
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:455
|
||
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:465
|
||
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:490
|
||
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``, ``HTTPErrorProcessor``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:497
|
||
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:507
|
||
msgid "Proxies"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:509
|
||
msgid ""
|
||
"**urllib2** 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:522
|
||
msgid ""
|
||
"Currently ``urllib2`` *does not* support fetching of ``https`` locations "
|
||
"through a proxy. However, this can be enabled by extending urllib2 as shown "
|
||
"in the recipe [#]_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:528
|
||
msgid "Sockets and Layers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:530
|
||
msgid ""
|
||
"The Python support for fetching resources from the web is layered. urllib2 "
|
||
"uses the httplib library, which in turn uses the socket library."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:533
|
||
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 httplib or urllib2 "
|
||
"levels. However, you can set the default timeout globally for all sockets "
|
||
"using ::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:558
|
||
msgid "This document was reviewed and revised by John Lee."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:560
|
||
msgid ""
|
||
"For an introduction to the CGI protocol see `Writing Web Applications in "
|
||
"Python <http://www.pyzine.com/Issue008/Section_Articles/article_CGIOne."
|
||
"html>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:562
|
||
msgid "Google for example."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:563
|
||
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:566
|
||
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:568
|
||
msgid ""
|
||
"For details of more HTTP request headers, see `Quick Reference to HTTP "
|
||
"Headers`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:570
|
||
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 urllib2 picks up on. In order to test scripts "
|
||
"with a localhost server, I have to prevent urllib2 from using the proxy."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/urllib2.rst:575
|
||
msgid ""
|
||
"urllib2 opener for SSL proxy (CONNECT method): `ASPN Cookbook Recipe <http://"
|
||
"code.activestate.com/recipes/456195/>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:3
|
||
msgid "HOWTO Use Python in the web"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:5
|
||
msgid "Marek Kubica"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:9
|
||
msgid ""
|
||
"This document shows how Python fits into the web. It presents some ways to "
|
||
"integrate Python with a web server, and general practices useful for "
|
||
"developing web sites."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:14
|
||
msgid ""
|
||
"Programming for the Web has become a hot topic since the rise of \"Web "
|
||
"2.0\", which focuses on user-generated content on web sites. It has always "
|
||
"been possible to use Python for creating web sites, but it was a rather "
|
||
"tedious task. Therefore, many frameworks and helper tools have been created "
|
||
"to assist developers in creating faster and more robust sites. This HOWTO "
|
||
"describes some of the methods used to combine Python with a web server to "
|
||
"create dynamic content. It is not meant as a complete introduction, as this "
|
||
"topic is far too broad to be covered in one single document. However, a "
|
||
"short overview of the most popular libraries is provided."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:26
|
||
msgid ""
|
||
"While this HOWTO tries to give an overview of Python in the web, it cannot "
|
||
"always be as up to date as desired. Web development in Python is rapidly "
|
||
"moving forward, so the wiki page on `Web Programming <https://wiki.python."
|
||
"org/moin/WebProgramming>`_ may be more in sync with recent development."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:34
|
||
msgid "The Low-Level View"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:36
|
||
msgid ""
|
||
"When a user enters a web site, their browser makes a connection to the "
|
||
"site's web server (this is called the *request*). The server looks up the "
|
||
"file in the file system and sends it back to the user's browser, which "
|
||
"displays it (this is the *response*). This is roughly how the underlying "
|
||
"protocol, HTTP, works."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:41
|
||
msgid ""
|
||
"Dynamic web sites are not based on files in the file system, but rather on "
|
||
"programs which are run by the web server when a request comes in, and which "
|
||
"*generate* the content that is returned to the user. They can do all sorts "
|
||
"of useful things, like display the postings of a bulletin board, show your "
|
||
"email, configure software, or just display the current time. These programs "
|
||
"can be written in any programming language the server supports. Since most "
|
||
"servers support Python, it is easy to use Python to create dynamic web sites."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:49
|
||
msgid ""
|
||
"Most HTTP servers are written in C or C++, so they cannot execute Python "
|
||
"code directly -- a bridge is needed between the server and the program. "
|
||
"These bridges, or rather interfaces, define how programs interact with the "
|
||
"server. There have been numerous attempts to create the best possible "
|
||
"interface, but there are only a few worth mentioning."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:55
|
||
msgid ""
|
||
"Not every web server supports every interface. Many web servers only "
|
||
"support old, now-obsolete interfaces; however, they can often be extended "
|
||
"using third-party modules to support newer ones."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:61
|
||
msgid "Common Gateway Interface"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:63
|
||
msgid ""
|
||
"This interface, most commonly referred to as \"CGI\", is the oldest, and is "
|
||
"supported by nearly every web server out of the box. Programs using CGI to "
|
||
"communicate with their web server need to be started by the server for every "
|
||
"request. So, every request starts a new Python interpreter -- which takes "
|
||
"some time to start up -- thus making the whole interface only usable for low "
|
||
"load situations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:70
|
||
msgid ""
|
||
"The upside of CGI is that it is simple -- writing a Python program which "
|
||
"uses CGI is a matter of about three lines of code. This simplicity comes at "
|
||
"a price: it does very few things to help the developer."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:74
|
||
msgid ""
|
||
"Writing CGI programs, while still possible, is no longer recommended. With :"
|
||
"ref:`WSGI <WSGI>`, a topic covered later in this document, it is possible to "
|
||
"write programs that emulate CGI, so they can be run as CGI if no better "
|
||
"option is available."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:81
|
||
msgid ""
|
||
"The Python standard library includes some modules that are helpful for "
|
||
"creating plain CGI programs:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:84
|
||
msgid ":mod:`cgi` -- Handling of user input in CGI scripts"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:85
|
||
msgid ""
|
||
":mod:`cgitb` -- Displays nice tracebacks when errors happen in CGI "
|
||
"applications, instead of presenting a \"500 Internal Server Error\" message"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:88
|
||
msgid ""
|
||
"The Python wiki features a page on `CGI scripts <https://wiki.python.org/"
|
||
"moin/CgiScripts>`_ with some additional information about CGI in Python."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:94
|
||
msgid "Simple script for testing CGI"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:96
|
||
msgid ""
|
||
"To test whether your web server works with CGI, you can use this short and "
|
||
"simple CGI program::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:111
|
||
msgid ""
|
||
"Depending on your web server configuration, you may need to save this code "
|
||
"with a ``.py`` or ``.cgi`` extension. Additionally, this file may also need "
|
||
"to be in a ``cgi-bin`` folder, for security reasons."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:115
|
||
msgid ""
|
||
"You might wonder what the ``cgitb`` line is about. This line makes it "
|
||
"possible to display a nice traceback instead of just crashing and displaying "
|
||
"an \"Internal Server Error\" in the user's browser. This is useful for "
|
||
"debugging, but it might risk exposing some confidential data to the user. "
|
||
"You should not use ``cgitb`` in production code for this reason. You should "
|
||
"*always* catch exceptions, and display proper error pages -- end-users don't "
|
||
"like to see nondescript \"Internal Server Errors\" in their browsers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:125
|
||
msgid "Setting up CGI on your own server"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:127
|
||
msgid ""
|
||
"If you don't have your own web server, this does not apply to you. You can "
|
||
"check whether it works as-is, and if not you will need to talk to the "
|
||
"administrator of your web server. If it is a big host, you can try filing a "
|
||
"ticket asking for Python support."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:132
|
||
msgid ""
|
||
"If you are your own administrator or want to set up CGI for testing purposes "
|
||
"on your own computers, you have to configure it by yourself. There is no "
|
||
"single way to configure CGI, as there are many web servers with different "
|
||
"configuration options. Currently the most widely used free web server is "
|
||
"`Apache HTTPd <http://httpd.apache.org/>`_, or Apache for short. Apache can "
|
||
"be easily installed on nearly every system using the system's package "
|
||
"management tool. `lighttpd <http://www.lighttpd.net>`_ is another "
|
||
"alternative and is said to have better performance. On many systems this "
|
||
"server can also be installed using the package management tool, so manually "
|
||
"compiling the web server may not be needed."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:143
|
||
msgid ""
|
||
"On Apache you can take a look at the `Dynamic Content with CGI <http://httpd."
|
||
"apache.org/docs/2.2/howto/cgi.html>`_ tutorial, where everything is "
|
||
"described. Most of the time it is enough just to set ``+ExecCGI``. The "
|
||
"tutorial also describes the most common gotchas that might arise."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:148
|
||
msgid ""
|
||
"On lighttpd you need to use the `CGI module <http://redmine.lighttpd.net/"
|
||
"projects/lighttpd/wiki/Docs_ModCGI>`_\\ , which can be configured in a "
|
||
"straightforward way. It boils down to setting ``cgi.assign`` properly."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:154
|
||
msgid "Common problems with CGI scripts"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:156
|
||
msgid ""
|
||
"Using CGI sometimes leads to small annoyances while trying to get these "
|
||
"scripts to run. Sometimes a seemingly correct script does not work as "
|
||
"expected, the cause being some small hidden problem that's difficult to spot."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:160
|
||
msgid "Some of these potential problems are:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:162
|
||
msgid ""
|
||
"The Python script is not marked as executable. When CGI scripts are not "
|
||
"executable most web servers will let the user download it, instead of "
|
||
"running it and sending the output to the user. For CGI scripts to run "
|
||
"properly on Unix-like operating systems, the ``+x`` bit needs to be set. "
|
||
"Using ``chmod a+x your_script.py`` may solve this problem."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:168
|
||
msgid ""
|
||
"On a Unix-like system, The line endings in the program file must be Unix "
|
||
"style line endings. This is important because the web server checks the "
|
||
"first line of the script (called shebang) and tries to run the program "
|
||
"specified there. It gets easily confused by Windows line endings (Carriage "
|
||
"Return & Line Feed, also called CRLF), so you have to convert the file to "
|
||
"Unix line endings (only Line Feed, LF). This can be done automatically by "
|
||
"uploading the file via FTP in text mode instead of binary mode, but the "
|
||
"preferred way is just telling your editor to save the files with Unix line "
|
||
"endings. Most editors support this."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:178
|
||
msgid ""
|
||
"Your web server must be able to read the file, and you need to make sure the "
|
||
"permissions are correct. On unix-like systems, the server often runs as "
|
||
"user and group ``www-data``, so it might be worth a try to change the file "
|
||
"ownership, or making the file world readable by using ``chmod a+r "
|
||
"your_script.py``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:184
|
||
msgid ""
|
||
"The web server must know that the file you're trying to access is a CGI "
|
||
"script. Check the configuration of your web server, as it may be configured "
|
||
"to expect a specific file extension for CGI scripts."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:188
|
||
msgid ""
|
||
"On Unix-like systems, the path to the interpreter in the shebang (``#!/usr/"
|
||
"bin/env python``) must be correct. This line calls ``/usr/bin/env`` to find "
|
||
"Python, but it will fail if there is no ``/usr/bin/env``, or if Python is "
|
||
"not in the web server's path. If you know where your Python is installed, "
|
||
"you can also use that full path. The commands ``whereis python`` and ``type "
|
||
"-p python`` could help you find where it is installed. Once you know the "
|
||
"path, you can change the shebang accordingly: ``#!/usr/bin/python``."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:197
|
||
msgid ""
|
||
"The file must not contain a BOM (Byte Order Mark). The BOM is meant for "
|
||
"determining the byte order of UTF-16 and UTF-32 encodings, but some editors "
|
||
"write this also into UTF-8 files. The BOM interferes with the shebang line, "
|
||
"so be sure to tell your editor not to write the BOM."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:202
|
||
msgid ""
|
||
"If the web server is using :ref:`mod-python`, ``mod_python`` may be having "
|
||
"problems. ``mod_python`` is able to handle CGI scripts by itself, but it "
|
||
"can also be a source of issues."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:210
|
||
msgid "mod_python"
|
||
msgstr "mod_python"
|
||
|
||
#: ../Doc/howto/webservers.rst:212
|
||
msgid ""
|
||
"People coming from PHP often find it hard to grasp how to use Python in the "
|
||
"web. Their first thought is mostly `mod_python <http://modpython.org/>`_\\ , "
|
||
"because they think that this is the equivalent to ``mod_php``. Actually, "
|
||
"there are many differences. What ``mod_python`` does is embed the "
|
||
"interpreter into the Apache process, thus speeding up requests by not having "
|
||
"to start a Python interpreter for each request. On the other hand, it is "
|
||
"not \"Python intermixed with HTML\" in the way that PHP is often intermixed "
|
||
"with HTML. The Python equivalent of that is a template engine. "
|
||
"``mod_python`` itself is much more powerful and provides more access to "
|
||
"Apache internals. It can emulate CGI, work in a \"Python Server Pages\" "
|
||
"mode (similar to JSP) which is \"HTML intermingled with Python\", and it has "
|
||
"a \"Publisher\" which designates one file to accept all requests and decide "
|
||
"what to do with them."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:225
|
||
msgid ""
|
||
"``mod_python`` does have some problems. Unlike the PHP interpreter, the "
|
||
"Python interpreter uses caching when executing files, so changes to a file "
|
||
"will require the web server to be restarted. Another problem is the basic "
|
||
"concept -- Apache starts child processes to handle the requests, and "
|
||
"unfortunately every child process needs to load the whole Python interpreter "
|
||
"even if it does not use it. This makes the whole web server slower. "
|
||
"Another problem is that, because ``mod_python`` is linked against a specific "
|
||
"version of ``libpython``, it is not possible to switch from an older version "
|
||
"to a newer (e.g. 2.4 to 2.5) without recompiling ``mod_python``. "
|
||
"``mod_python`` is also bound to the Apache web server, so programs written "
|
||
"for ``mod_python`` cannot easily run on other web servers."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:237
|
||
msgid ""
|
||
"These are the reasons why ``mod_python`` should be avoided when writing new "
|
||
"programs. In some circumstances it still might be a good idea to use "
|
||
"``mod_python`` for deployment, but WSGI makes it possible to run WSGI "
|
||
"programs under ``mod_python`` as well."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:244
|
||
msgid "FastCGI and SCGI"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:246
|
||
msgid ""
|
||
"FastCGI and SCGI try to solve the performance problem of CGI in another way. "
|
||
"Instead of embedding the interpreter into the web server, they create long-"
|
||
"running background processes. There is still a module in the web server "
|
||
"which makes it possible for the web server to \"speak\" with the background "
|
||
"process. As the background process is independent of the server, it can be "
|
||
"written in any language, including Python. The language just needs to have "
|
||
"a library which handles the communication with the webserver."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:254
|
||
msgid ""
|
||
"The difference between FastCGI and SCGI is very small, as SCGI is "
|
||
"essentially just a \"simpler FastCGI\". As the web server support for SCGI "
|
||
"is limited, most people use FastCGI instead, which works the same way. "
|
||
"Almost everything that applies to SCGI also applies to FastCGI as well, so "
|
||
"we'll only cover the latter."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:260
|
||
msgid ""
|
||
"These days, FastCGI is never used directly. Just like ``mod_python``, it is "
|
||
"only used for the deployment of WSGI applications."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:265
|
||
msgid "Setting up FastCGI"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:267
|
||
msgid "Each web server requires a specific module."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:269
|
||
msgid ""
|
||
"Apache has both `mod_fastcgi <http://www.fastcgi.com/drupal/>`_ and "
|
||
"`mod_fcgid <http://httpd.apache.org/mod_fcgid/>`_. ``mod_fastcgi`` is the "
|
||
"original one, but it has some licensing issues, which is why it is sometimes "
|
||
"considered non-free. ``mod_fcgid`` is a smaller, compatible alternative. "
|
||
"One of these modules needs to be loaded by Apache."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:275
|
||
msgid ""
|
||
"lighttpd ships its own `FastCGI module <http://redmine.lighttpd.net/projects/"
|
||
"lighttpd/wiki/Docs_ModFastCGI>`_ as well as an `SCGI module <http://redmine."
|
||
"lighttpd.net/projects/lighttpd/wiki/Docs_ModSCGI>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:279
|
||
msgid ""
|
||
"`nginx <http://nginx.org/>`_ also supports `FastCGI <http://wiki.nginx.org/"
|
||
"NginxSimplePythonFCGI>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:282
|
||
msgid ""
|
||
"Once you have installed and configured the module, you can test it with the "
|
||
"following WSGI-application::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:303
|
||
msgid ""
|
||
"This is a simple WSGI application, but you need to install `flup <https://"
|
||
"pypi.python.org/pypi/flup/1.0>`_ first, as flup handles the low level "
|
||
"FastCGI access."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:309
|
||
msgid ""
|
||
"There is some documentation on `setting up Django with FastCGI <https://docs."
|
||
"djangoproject.com/en/dev/howto/deployment/fastcgi/>`_, most of which can be "
|
||
"reused for other WSGI-compliant frameworks and libraries. Only the ``manage."
|
||
"py`` part has to be changed, the example used here can be used instead. "
|
||
"Django does more or less the exact same thing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:317
|
||
msgid "mod_wsgi"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:319
|
||
msgid ""
|
||
"`mod_wsgi <http://code.google.com/p/modwsgi/>`_ is an attempt to get rid of "
|
||
"the low level gateways. Given that FastCGI, SCGI, and mod_python are mostly "
|
||
"used to deploy WSGI applications, mod_wsgi was started to directly embed "
|
||
"WSGI applications into the Apache web server. mod_wsgi is specifically "
|
||
"designed to host WSGI applications. It makes the deployment of WSGI "
|
||
"applications much easier than deployment using other low level methods, "
|
||
"which need glue code. The downside is that mod_wsgi is limited to the "
|
||
"Apache web server; other servers would need their own implementations of "
|
||
"mod_wsgi."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:328
|
||
msgid ""
|
||
"mod_wsgi supports two modes: embedded mode, in which it integrates with the "
|
||
"Apache process, and daemon mode, which is more FastCGI-like. Unlike "
|
||
"FastCGI, mod_wsgi handles the worker-processes by itself, which makes "
|
||
"administration easier."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:337
|
||
msgid "Step back: WSGI"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:339
|
||
msgid ""
|
||
"WSGI has already been mentioned several times, so it has to be something "
|
||
"important. In fact it really is, and now it is time to explain it."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:342
|
||
msgid ""
|
||
"The *Web Server Gateway Interface*, or WSGI for short, is defined in :pep:"
|
||
"`333` and is currently the best way to do Python web programming. While it "
|
||
"is great for programmers writing frameworks, a normal web developer does not "
|
||
"need to get in direct contact with it. When choosing a framework for web "
|
||
"development it is a good idea to choose one which supports WSGI."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:348
|
||
msgid ""
|
||
"The big benefit of WSGI is the unification of the application programming "
|
||
"interface. When your program is compatible with WSGI -- which at the outer "
|
||
"level means that the framework you are using has support for WSGI -- your "
|
||
"program can be deployed via any web server interface for which there are "
|
||
"WSGI wrappers. You do not need to care about whether the application user "
|
||
"uses mod_python or FastCGI or mod_wsgi -- with WSGI your application will "
|
||
"work on any gateway interface. The Python standard library contains its own "
|
||
"WSGI server, :mod:`wsgiref`, which is a small web server that can be used "
|
||
"for testing."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:358
|
||
msgid ""
|
||
"A really great WSGI feature is middleware. Middleware is a layer around "
|
||
"your program which can add various functionality to it. There is quite a "
|
||
"bit of `middleware <http://www.wsgi.org/en/latest/libraries.html>`_ already "
|
||
"available. For example, instead of writing your own session management "
|
||
"(HTTP is a stateless protocol, so to associate multiple HTTP requests with a "
|
||
"single user your application must create and manage such state via a "
|
||
"session), you can just download middleware which does that, plug it in, and "
|
||
"get on with coding the unique parts of your application. The same thing "
|
||
"with compression -- there is existing middleware which handles compressing "
|
||
"your HTML using gzip to save on your server's bandwidth. Authentication is "
|
||
"another a problem easily solved using existing middleware."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:370
|
||
msgid ""
|
||
"Although WSGI may seem complex, the initial phase of learning can be very "
|
||
"rewarding because WSGI and the associated middleware already have solutions "
|
||
"to many problems that might arise while developing web sites."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:376
|
||
msgid "WSGI Servers"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:378
|
||
msgid ""
|
||
"The code that is used to connect to various low level gateways like CGI or "
|
||
"mod_python is called a *WSGI server*. One of these servers is ``flup``, "
|
||
"which supports FastCGI and SCGI, as well as `AJP <http://en.wikipedia.org/"
|
||
"wiki/Apache_JServ_Protocol>`_. Some of these servers are written in Python, "
|
||
"as ``flup`` is, but there also exist others which are written in C and can "
|
||
"be used as drop-in replacements."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:385
|
||
msgid ""
|
||
"There are many servers already available, so a Python web application can be "
|
||
"deployed nearly anywhere. This is one big advantage that Python has "
|
||
"compared with other web technologies."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:391
|
||
msgid ""
|
||
"A good overview of WSGI-related code can be found in the `WSGI homepage "
|
||
"<http://www.wsgi.org/en/latest/index.html>`_, which contains an extensive "
|
||
"list of `WSGI servers <http://www.wsgi.org/en/latest/servers.html>`_ which "
|
||
"can be used by *any* application supporting WSGI."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:396
|
||
msgid ""
|
||
"You might be interested in some WSGI-supporting modules already contained in "
|
||
"the standard library, namely:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:399
|
||
msgid ":mod:`wsgiref` -- some tiny utilities and servers for WSGI"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:403
|
||
msgid "Case study: MoinMoin"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:405
|
||
msgid ""
|
||
"What does WSGI give the web application developer? Let's take a look at an "
|
||
"application that's been around for a while, which was written in Python "
|
||
"without using WSGI."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:409
|
||
msgid ""
|
||
"One of the most widely used wiki software packages is `MoinMoin <http://"
|
||
"moinmo.in/>`_. It was created in 2000, so it predates WSGI by about three "
|
||
"years. Older versions needed separate code to run on CGI, mod_python, "
|
||
"FastCGI and standalone."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:414
|
||
msgid ""
|
||
"It now includes support for WSGI. Using WSGI, it is possible to deploy "
|
||
"MoinMoin on any WSGI compliant server, with no additional glue code. Unlike "
|
||
"the pre-WSGI versions, this could include WSGI servers that the authors of "
|
||
"MoinMoin know nothing about."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:421
|
||
msgid "Model-View-Controller"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:423
|
||
msgid ""
|
||
"The term *MVC* is often encountered in statements such as \"framework *foo* "
|
||
"supports MVC\". MVC is more about the overall organization of code, rather "
|
||
"than any particular API. Many web frameworks use this model to help the "
|
||
"developer bring structure to their program. Bigger web applications can "
|
||
"have lots of code, so it is a good idea to have an effective structure right "
|
||
"from the beginning. That way, even users of other frameworks (or even other "
|
||
"languages, since MVC is not Python-specific) can easily understand the code, "
|
||
"given that they are already familiar with the MVC structure."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:432
|
||
msgid "MVC stands for three components:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:434
|
||
msgid ""
|
||
"The *model*. This is the data that will be displayed and modified. In "
|
||
"Python frameworks, this component is often represented by the classes used "
|
||
"by an object-relational mapper."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:438
|
||
msgid ""
|
||
"The *view*. This component's job is to display the data of the model to the "
|
||
"user. Typically this component is implemented via templates."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:441
|
||
msgid ""
|
||
"The *controller*. This is the layer between the user and the model. The "
|
||
"controller reacts to user actions (like opening some specific URL), tells "
|
||
"the model to modify the data if necessary, and tells the view code what to "
|
||
"display,"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:446
|
||
msgid ""
|
||
"While one might think that MVC is a complex design pattern, in fact it is "
|
||
"not. It is used in Python because it has turned out to be useful for "
|
||
"creating clean, maintainable web sites."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:452
|
||
msgid ""
|
||
"While not all Python frameworks explicitly support MVC, it is often trivial "
|
||
"to create a web site which uses the MVC pattern by separating the data logic "
|
||
"(the model) from the user interaction logic (the controller) and the "
|
||
"templates (the view). That's why it is important not to write unnecessary "
|
||
"Python code in the templates -- it works against the MVC model and creates "
|
||
"chaos in the code base, making it harder to understand and modify."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:461
|
||
msgid ""
|
||
"The English Wikipedia has an article about the `Model-View-Controller "
|
||
"pattern <http://en.wikipedia.org/wiki/Model-view-controller>`_. It includes "
|
||
"a long list of web frameworks for various programming languages."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:467
|
||
msgid "Ingredients for Websites"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:469
|
||
msgid ""
|
||
"Websites are complex constructs, so tools have been created to help web "
|
||
"developers make their code easier to write and more maintainable. Tools "
|
||
"like these exist for all web frameworks in all languages. Developers are "
|
||
"not forced to use these tools, and often there is no \"best\" tool. It is "
|
||
"worth learning about the available tools because they can greatly simplify "
|
||
"the process of developing a web site."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:479
|
||
msgid ""
|
||
"There are far more components than can be presented here. The Python wiki "
|
||
"has a page about these components, called `Web Components <https://wiki."
|
||
"python.org/moin/WebComponents>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:485
|
||
msgid "Templates"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:487
|
||
msgid ""
|
||
"Mixing of HTML and Python code is made possible by a few libraries. While "
|
||
"convenient at first, it leads to horribly unmaintainable code. That's why "
|
||
"templates exist. Templates are, in the simplest case, just HTML files with "
|
||
"placeholders. The HTML is sent to the user's browser after filling in the "
|
||
"placeholders."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:493
|
||
msgid "Python already includes two ways to build simple templates::"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:504
|
||
msgid ""
|
||
"To generate complex HTML based on non-trivial model data, conditional and "
|
||
"looping constructs like Python's *for* and *if* are generally needed. "
|
||
"*Template engines* support templates of this complexity."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:508
|
||
msgid ""
|
||
"There are a lot of template engines available for Python which can be used "
|
||
"with or without a `framework`_. Some of these define a plain-text "
|
||
"programming language which is easy to learn, partly because it is limited in "
|
||
"scope. Others use XML, and the template output is guaranteed to be always be "
|
||
"valid XML. There are many other variations."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:514
|
||
msgid ""
|
||
"Some `frameworks`_ ship their own template engine or recommend one in "
|
||
"particular. In the absence of a reason to use a different template engine, "
|
||
"using the one provided by or recommended by the framework is a good idea."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:518
|
||
msgid "Popular template engines include:"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:520
|
||
msgid "`Mako <http://www.makotemplates.org/>`_"
|
||
msgstr "`Mako <http://www.makotemplates.org/>`_"
|
||
|
||
#: ../Doc/howto/webservers.rst:521
|
||
msgid "`Genshi <http://genshi.edgewall.org/>`_"
|
||
msgstr "`Genshi <http://genshi.edgewall.org/>`_"
|
||
|
||
#: ../Doc/howto/webservers.rst:522
|
||
msgid "`Jinja <http://jinja.pocoo.org/>`_"
|
||
msgstr "`Jinja <http://jinja.pocoo.org/2/>`_"
|
||
|
||
#: ../Doc/howto/webservers.rst:526
|
||
msgid ""
|
||
"There are many template engines competing for attention, because it is "
|
||
"pretty easy to create them in Python. The page `Templating <https://wiki."
|
||
"python.org/moin/Templating>`_ in the wiki lists a big, ever-growing number "
|
||
"of these. The three listed above are considered \"second generation\" "
|
||
"template engines and are a good place to start."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:534
|
||
msgid "Data persistence"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:536
|
||
msgid ""
|
||
"*Data persistence*, while sounding very complicated, is just about storing "
|
||
"data. This data might be the text of blog entries, the postings on a "
|
||
"bulletin board or the text of a wiki page. There are, of course, a number "
|
||
"of different ways to store information on a web server."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:541
|
||
msgid ""
|
||
"Often, relational database engines like `MySQL <http://www.mysql.com/>`_ or "
|
||
"`PostgreSQL <http://www.postgresql.org/>`_ are used because of their good "
|
||
"performance when handling very large databases consisting of millions of "
|
||
"entries. There is also a small database engine called `SQLite <http://www."
|
||
"sqlite.org/>`_, which is bundled with Python in the :mod:`sqlite3` module, "
|
||
"and which uses only one file. It has no other dependencies. For smaller "
|
||
"sites SQLite is just enough."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:549
|
||
msgid ""
|
||
"Relational databases are *queried* using a language called `SQL <http://en."
|
||
"wikipedia.org/wiki/SQL>`_. Python programmers in general do not like SQL "
|
||
"too much, as they prefer to work with objects. It is possible to save "
|
||
"Python objects into a database using a technology called `ORM <http://en."
|
||
"wikipedia.org/wiki/Object-relational_mapping>`_ (Object Relational "
|
||
"Mapping). ORM translates all object-oriented access into SQL code under the "
|
||
"hood, so the developer does not need to think about it. Most `frameworks`_ "
|
||
"use ORMs, and it works quite well."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:558
|
||
msgid ""
|
||
"A second possibility is storing data in normal, plain text files (some times "
|
||
"called \"flat files\"). This is very easy for simple sites, but can be "
|
||
"difficult to get right if the web site is performing many updates to the "
|
||
"stored data."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:563
|
||
msgid ""
|
||
"A third possibility are object oriented databases (also called \"object "
|
||
"databases\"). These databases store the object data in a form that closely "
|
||
"parallels the way the objects are structured in memory during program "
|
||
"execution. (By contrast, ORMs store the object data as rows of data in "
|
||
"tables and relations between those rows.) Storing the objects directly has "
|
||
"the advantage that nearly all objects can be saved in a straightforward way, "
|
||
"unlike in relational databases where some objects are very hard to represent."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:571
|
||
msgid ""
|
||
"`Frameworks`_ often give hints on which data storage method to choose. It "
|
||
"is usually a good idea to stick to the data store recommended by the "
|
||
"framework unless the application has special requirements better satisfied "
|
||
"by an alternate storage mechanism."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:578
|
||
msgid ""
|
||
"`Persistence Tools <https://wiki.python.org/moin/PersistenceTools>`_ lists "
|
||
"possibilities on how to save data in the file system. Some of these modules "
|
||
"are part of the standard library"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:582
|
||
msgid ""
|
||
"`Database Programming <https://wiki.python.org/moin/DatabaseProgramming>`_ "
|
||
"helps with choosing a method for saving data"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:585
|
||
msgid ""
|
||
"`SQLAlchemy <http://www.sqlalchemy.org/>`_, the most powerful OR-Mapper for "
|
||
"Python, and `Elixir <http://elixir.ematia.de/>`_, which makes SQLAlchemy "
|
||
"easier to use"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:589
|
||
msgid "`SQLObject <http://www.sqlobject.org/>`_, another popular OR-Mapper"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:591
|
||
msgid ""
|
||
"`ZODB <https://launchpad.net/zodb>`_ and `Durus <http://www.mems-exchange."
|
||
"org/software/durus/>`_, two object oriented databases"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:599
|
||
msgid "Frameworks"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:601
|
||
msgid ""
|
||
"The process of creating code to run web sites involves writing code to "
|
||
"provide various services. The code to provide a particular service often "
|
||
"works the same way regardless of the complexity or purpose of the web site "
|
||
"in question. Abstracting these common solutions into reusable code produces "
|
||
"what are called \"frameworks\" for web development. Perhaps the most well-"
|
||
"known framework for web development is Ruby on Rails, but Python has its own "
|
||
"frameworks. Some of these were partly inspired by Rails, or borrowed ideas "
|
||
"from Rails, but many existed a long time before Rails."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:610
|
||
msgid ""
|
||
"Originally Python web frameworks tended to incorporate all of the services "
|
||
"needed to develop web sites as a giant, integrated set of tools. No two web "
|
||
"frameworks were interoperable: a program developed for one could not be "
|
||
"deployed on a different one without considerable re-engineering work. This "
|
||
"led to the development of \"minimalist\" web frameworks that provided just "
|
||
"the tools to communicate between the Python code and the http protocol, with "
|
||
"all other services to be added on top via separate components. Some ad hoc "
|
||
"standards were developed that allowed for limited interoperability between "
|
||
"frameworks, such as a standard that allowed different template engines to be "
|
||
"used interchangeably."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:621
|
||
msgid ""
|
||
"Since the advent of WSGI, the Python web framework world has been evolving "
|
||
"toward interoperability based on the WSGI standard. Now many web "
|
||
"frameworks, whether \"full stack\" (providing all the tools one needs to "
|
||
"deploy the most complex web sites) or minimalist, or anything in between, "
|
||
"are built from collections of reusable components that can be used with more "
|
||
"than one framework."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:628
|
||
msgid ""
|
||
"The majority of users will probably want to select a \"full stack\" "
|
||
"framework that has an active community. These frameworks tend to be well "
|
||
"documented, and provide the easiest path to producing a fully functional web "
|
||
"site in minimal time."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:635
|
||
msgid "Some notable frameworks"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:637
|
||
msgid ""
|
||
"There are an incredible number of frameworks, so they cannot all be covered "
|
||
"here. Instead we will briefly touch on some of the most popular."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:642
|
||
msgid "Django"
|
||
msgstr "Django"
|
||
|
||
#: ../Doc/howto/webservers.rst:644
|
||
msgid ""
|
||
"`Django <https://www.djangoproject.com/>`_ is a framework consisting of "
|
||
"several tightly coupled elements which were written from scratch and work "
|
||
"together very well. It includes an ORM which is quite powerful while being "
|
||
"simple to use, and has a great online administration interface which makes "
|
||
"it possible to edit the data in the database with a browser. The template "
|
||
"engine is text-based and is designed to be usable for page designers who "
|
||
"cannot write Python. It supports template inheritance and filters (which "
|
||
"work like Unix pipes). Django has many handy features bundled, such as "
|
||
"creation of RSS feeds or generic views, which make it possible to create web "
|
||
"sites almost without writing any Python code."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:654
|
||
msgid ""
|
||
"It has a big, international community, the members of which have created "
|
||
"many web sites. There are also a lot of add-on projects which extend "
|
||
"Django's normal functionality. This is partly due to Django's well written "
|
||
"`online documentation <https://docs.djangoproject.com/>`_ and the `Django "
|
||
"book <http://www.djangobook.com/>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:663
|
||
msgid ""
|
||
"Although Django is an MVC-style framework, it names the elements "
|
||
"differently, which is described in the `Django FAQ <https://docs."
|
||
"djangoproject.com/en/dev/faq/general/#django-appears-to-be-a-mvc-framework-"
|
||
"but-you-call-the-controller-the-view-and-the-view-the-template-how-come-you-"
|
||
"don-t-use-the-standard-names>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:669
|
||
msgid "TurboGears"
|
||
msgstr "TurboGears"
|
||
|
||
#: ../Doc/howto/webservers.rst:671
|
||
msgid ""
|
||
"Another popular web framework for Python is `TurboGears <http://www."
|
||
"turbogears.org/>`_. TurboGears takes the approach of using already existing "
|
||
"components and combining them with glue code to create a seamless "
|
||
"experience. TurboGears gives the user flexibility in choosing components. "
|
||
"For example the ORM and template engine can be changed to use packages "
|
||
"different from those used by default."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:678
|
||
msgid ""
|
||
"The documentation can be found in the `TurboGears wiki <http://docs."
|
||
"turbogears.org/>`_, where links to screencasts can be found. TurboGears has "
|
||
"also an active user community which can respond to most related questions. "
|
||
"There is also a `TurboGears book <http://turbogearsbook.com/>`_ published, "
|
||
"which is a good starting point."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:684
|
||
msgid ""
|
||
"The newest version of TurboGears, version 2.0, moves even further in "
|
||
"direction of WSGI support and a component-based architecture. TurboGears 2 "
|
||
"is based on the WSGI stack of another popular component-based web framework, "
|
||
"`Pylons <http://www.pylonsproject.org/>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:691
|
||
msgid "Zope"
|
||
msgstr "Zope"
|
||
|
||
#: ../Doc/howto/webservers.rst:693
|
||
msgid ""
|
||
"The Zope framework is one of the \"old original\" frameworks. Its current "
|
||
"incarnation in Zope2 is a tightly integrated full-stack framework. One of "
|
||
"its most interesting feature is its tight integration with a powerful object "
|
||
"database called the `ZODB <https://launchpad.net/zodb>`_ (Zope Object "
|
||
"Database). Because of its highly integrated nature, Zope wound up in a "
|
||
"somewhat isolated ecosystem: code written for Zope wasn't very usable "
|
||
"outside of Zope, and vice-versa. To solve this problem the Zope 3 effort "
|
||
"was started. Zope 3 re-engineers Zope as a set of more cleanly isolated "
|
||
"components. This effort was started before the advent of the WSGI standard, "
|
||
"but there is WSGI support for Zope 3 from the `Repoze <http://repoze.org/>`_ "
|
||
"project. Zope components have many years of production use behind them, and "
|
||
"the Zope 3 project gives access to these components to the wider Python "
|
||
"community. There is even a separate framework based on the Zope components: "
|
||
"`Grok <http://grok.zope.org/>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:708
|
||
msgid ""
|
||
"Zope is also the infrastructure used by the `Plone <https://plone.org/>`_ "
|
||
"content management system, one of the most powerful and popular content "
|
||
"management systems available."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:714
|
||
msgid "Other notable frameworks"
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:716
|
||
msgid ""
|
||
"Of course these are not the only frameworks that are available. There are "
|
||
"many other frameworks worth mentioning."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:719
|
||
msgid ""
|
||
"Another framework that's already been mentioned is `Pylons`_. Pylons is "
|
||
"much like TurboGears, but with an even stronger emphasis on flexibility, "
|
||
"which comes at the cost of being more difficult to use. Nearly every "
|
||
"component can be exchanged, which makes it necessary to use the "
|
||
"documentation of every single component, of which there are many. Pylons "
|
||
"builds upon `Paste <http://pythonpaste.org/>`_, an extensive set of tools "
|
||
"which are handy for WSGI."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:726
|
||
msgid ""
|
||
"And that's still not everything. The most up-to-date information can always "
|
||
"be found in the Python wiki."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:731
|
||
msgid ""
|
||
"The Python wiki contains an extensive list of `web frameworks <https://wiki."
|
||
"python.org/moin/WebFrameworks>`_."
|
||
msgstr ""
|
||
|
||
#: ../Doc/howto/webservers.rst:734
|
||
msgid ""
|
||
"Most frameworks also have their own mailing lists and IRC channels, look out "
|
||
"for these on the projects' web sites."
|
||
msgstr ""
|
||
|
||
#~ msgid "^"
|
||
#~ msgstr "^"
|
||
|
||
#~ msgid "Other Resources"
|
||
#~ msgstr "Autres Ressources"
|
||
|
||
#~ msgid "A.M. Kuchling"
|
||
#~ msgstr "A.M. Kuchling"
|
||
|
||
#~ msgid "0.03"
|
||
#~ msgstr "0.03"
|
||
|
||
#~ msgid ""
|
||
#~ "It's usually difficult to get your management to accept open source "
|
||
#~ "software, and Python is no exception to this rule. This document "
|
||
#~ "discusses reasons to use Python, strategies for winning acceptance, facts "
|
||
#~ "and arguments you can use, and cases where you *shouldn't* try to use "
|
||
#~ "Python."
|
||
#~ msgstr ""
|
||
#~ "Il est souvent difficile de faire accepter les logiciels open source par "
|
||
#~ "votre encadrement, et Python n'est pas une exception à cette règle. Ce "
|
||
#~ "document traite des raisons d'utiliser Python, des stratégies pour le "
|
||
#~ "faire accepter, des faits et arguments que vous pouvez exploiter, et des "
|
||
#~ "cas où vous *ne devriez pas* essayer d'utiliser python."
|
||
|
||
#~ msgid "Reasons to Use Python"
|
||
#~ msgstr "Les raisons de choisir Python"
|
||
|
||
#~ msgid ""
|
||
#~ "There are several reasons to incorporate a scripting language into your "
|
||
#~ "development process, and this section will discuss them, and why Python "
|
||
#~ "has some properties that make it a particularly good choice."
|
||
#~ msgstr ""
|
||
#~ "Ce chapitre traite des différentes raisons d'introduire un langage de "
|
||
#~ "script dans vos processus de développements, et pourquoi Python est un "
|
||
#~ "choix particulièrement judicieux."
|
||
|
||
#~ msgid ""
|
||
#~ "Programs are often organized in a modular fashion. Lower-level "
|
||
#~ "operations are grouped together, and called by higher-level functions, "
|
||
#~ "which may in turn be used as basic operations by still further upper "
|
||
#~ "levels."
|
||
#~ msgstr ""
|
||
#~ "Les programmes sont en général organisés de manière modulaire. Les "
|
||
#~ "opérations de bas niveau sont regroupées, et appelées par des fonctions "
|
||
#~ "de niveau supérieur, qui peuvent être à leur tour être utilisées comme "
|
||
#~ "des opérations unitaires par du code de niveau encore supérieur."
|
||
|
||
#~ msgid ""
|
||
#~ "Often, the lowest levels do very simple things; they implement a data "
|
||
#~ "structure such as a binary tree or hash table, or they perform some "
|
||
#~ "simple computation, such as converting a date string to a number. The "
|
||
#~ "higher levels then contain logic connecting these primitive operations. "
|
||
#~ "Using the approach, the primitives can be seen as basic building blocks "
|
||
#~ "which are then glued together to produce the complete product."
|
||
#~ msgstr ""
|
||
#~ "En général, les niveaux inférieurs réalisent des opérations très "
|
||
#~ "simples ; ils implémentent une structure de données comme un arbre "
|
||
#~ "binaire ou une table de hachage, ou ils exécutent des opérations simples, "
|
||
#~ "comme la conversion d'une date en chaîne de caractères par exemple. Les "
|
||
#~ "niveaux supérieurs fournissent la logique pour associer ces opérations "
|
||
#~ "primitives. Avec cette approche, les primitives peuvent être considérées "
|
||
#~ "comme des simples briques qui sont assemblées afin de construire le "
|
||
#~ "produit complet."
|
||
|
||
#~ msgid "Prototyping"
|
||
#~ msgstr "Prototypage"
|
||
|
||
#~ msgid "Author"
|
||
#~ msgstr "Auteur"
|
||
|
||
#~ msgid "Release"
|
||
#~ msgstr "Version"
|
||
|
||
#~ msgid "See also"
|
||
#~ msgstr "Voir aussi"
|