python-docs-fr/howto.po

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