# SOME DESCRIPTIVE TITLE. # Copyright (C) 1990-2010, Python Software Foundation # This file is distributed under the same license as the Python package. # FIRST AUTHOR , YEAR. #, fuzzy msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2014-11-03 09:23\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \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" # ed2c1e75cda74c6bacd8233a92e11e2b #: ../src/Doc/howto/argparse.rst:3 msgid "Argparse Tutorial" msgstr "" # 200f6fc6f7394271a6276fcfe3273a09 #: ../src/Doc/howto/argparse.rst:5 msgid "Tshepang Lekhonkhobe" msgstr "" # ba2cf8e6c4b74afb8275761f1289aadd #: ../src/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 "" # f2d820d7fe834fab909de32872122abb #: ../src/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 "" # cdd8e2525f924b3c83d4fc2d745f8899 #: ../src/Doc/howto/argparse.rst:24 msgid "Concepts" msgstr "" # cc9e2f360c8340a886f8cd1db172ee5f #: ../src/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 "" # eb49ba3d308a43faaa0347a709943ba2 #: ../src/Doc/howto/argparse.rst:48 msgid "A few concepts we can learn from the four commands:" msgstr "" # 6b94ff97d73d4563ac5123ad6c91023c #: ../src/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 "" # 1f144116a2784cf28d243ca6b6b14428 #: ../src/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 "" # 36848d976f3d4b99a3abb07b95fbbe1c #: ../src/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 "" # abd627ea53d84e85b84e52561db2def4 #: ../src/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 "" # 901705678aaf47479af169a18c5488fb #: ../src/Doc/howto/argparse.rst:72 msgid "The basics" msgstr "" # 3acacfd395f949fba581ad8df478272d #: ../src/Doc/howto/argparse.rst:74 msgid "Let us start with a very simple example which does (almost) nothing::" msgstr "" # 19ce897f3a4a40e98a8ec81d8261611d # cd314c6b22c5443082c3216a5acde0d7 # 20795628a4c2456aaf50b95a8155628f #: ../src/Doc/howto/argparse.rst:80 ../src/Doc/howto/argparse.rst:188 #: ../src/Doc/howto/argparse.rst:209 msgid "Following is a result of running the code:" msgstr "" # a69cbfdeb027402b8dae8442c9e32543 # d080102a0371487b8e7a9df31cb291e2 # d8adb9677e8c4bcaabb70a21f6706841 #: ../src/Doc/howto/argparse.rst:97 ../src/Doc/howto/argparse.rst:254 #: ../src/Doc/howto/argparse.rst:298 msgid "Here is what is happening:" msgstr "" # 809de0b225f34682b32b0924855549f4 #: ../src/Doc/howto/argparse.rst:99 msgid "" "Running the script without any options results in nothing displayed to " "stdout. Not so useful." msgstr "" # 88a835298220492886c8c6b03ba14291 #: ../src/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 "" # a83aa58673aa4ffd844d4f8710e0f5b8 #: ../src/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 "" # 36c8a64da160473f83961e770fd19e86 #: ../src/Doc/howto/argparse.rst:112 msgid "Introducing Positional arguments" msgstr "" # 89702f55bf604b84ba7bf50eaa18381c #: ../src/Doc/howto/argparse.rst:114 msgid "An example::" msgstr "" # 2152c6282c354a45ae084c6484959db0 #: ../src/Doc/howto/argparse.rst:122 msgid "And running the code:" msgstr "" # 8ac679fe46d74f6686f40d8b373e62cd #: ../src/Doc/howto/argparse.rst:140 msgid "Here is what's happening:" msgstr "" # e90c4bc43e8d4916928a09c382e57b8f #: ../src/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 "" # 20f8cd7161e04fbf8a3ef30fa9a0fd43 #: ../src/Doc/howto/argparse.rst:146 msgid "Calling our program now requires us to specify an option." msgstr "" # b31954419bb2477ba18be150cc9a904b #: ../src/Doc/howto/argparse.rst:148 msgid "" "The :meth:`parse_args` method actually returns some data from the options " "specified, in this case, ``echo``." msgstr "" # 94be1fc6c9a64555bf332d4b5273a8c8 #: ../src/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 "" # e737368bf84b4f14a1078f6b4d0834ce #: ../src/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 "" # 5ca6e3a3b28541a49f5313e2ca7540f3 #: ../src/Doc/howto/argparse.rst:167 msgid "And we get:" msgstr "" # b4d1a84b95ec4463bf094ab4f5dc7e3e #: ../src/Doc/howto/argparse.rst:180 msgid "Now, how about doing something even more useful::" msgstr "" # eb4a5fbc93d74af6b741ea5ba889eac1 #: ../src/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 "" # 5fa0dae59b9441928901fc1d2309d5f3 #: ../src/Doc/howto/argparse.rst:219 msgid "" "That went well. The program now even helpfully quits on bad illegal input " "before proceeding." msgstr "" # 9fe6344ec9a64053b877930edda99baa #: ../src/Doc/howto/argparse.rst:224 msgid "Introducing Optional arguments" msgstr "" # cf9e5e7cce1a427e9bada5bf3316df89 #: ../src/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 "" # d40a9fbb59694ced86f039fc958e3ca5 # 4d444bec24e448f7bd620043cb4b2a02 # 0465703176a9478ea74459722925cd49 # 0d4b42c07c1441edbf6eb1aa357bfb97 #: ../src/Doc/howto/argparse.rst:236 ../src/Doc/howto/argparse.rst:282 #: ../src/Doc/howto/argparse.rst:398 ../src/Doc/howto/argparse.rst:432 msgid "And the output:" msgstr "" # a2d6900fd2ef4799a4956eaf46ad548f #: ../src/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 "" # 48bf3a47c73d4df685831895d45cd3bc #: ../src/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 "" # ea474839c84441e5b4fed6a6985d0fc0 #: ../src/Doc/howto/argparse.rst:265 msgid "The help message is a bit different." msgstr "" # 3f1265e224bb4577a68debe9c23c6c06 #: ../src/Doc/howto/argparse.rst:267 msgid "" "When using the ``--verbosity`` option, one must also specify some value, any " "value." msgstr "" # 88ce273a61e742b8b58e5c944a371e5d #: ../src/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 "" # c452465e05644cab83d1960866f0b729 #: ../src/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 "" # bc5a61890db841fc9e59a1330a9ea38c #: ../src/Doc/howto/argparse.rst:307 msgid "" "It complains when you specify a value, in true spirit of what flags actually " "are." msgstr "" # d17e2b1f198348c0b15f28b624143b03 #: ../src/Doc/howto/argparse.rst:310 msgid "Notice the different help text." msgstr "" # 749d899bef604512a359ff88a7e64be6 #: ../src/Doc/howto/argparse.rst:314 msgid "Short options" msgstr "" # bdaf1ceb126644a09bb3ead44969c30e #: ../src/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 "" # 0e5ba7c902f843a0a7a204d3a67fdf6d #: ../src/Doc/howto/argparse.rst:328 msgid "And here goes:" msgstr "" # 6ab46d6fde2c417b8fd1b41c4588634d #: ../src/Doc/howto/argparse.rst:341 msgid "Note that the new ability is also reflected in the help text." msgstr "" # 9cd03436de014d769ef7c75a564576d6 #: ../src/Doc/howto/argparse.rst:345 msgid "Combining Positional and Optional arguments" msgstr "" # af0aa9f8016a49e0a56448f2368714d8 #: ../src/Doc/howto/argparse.rst:347 msgid "Our program keeps growing in complexity::" msgstr "" # 7a2171285e0d4947af63b2e13836bf88 #: ../src/Doc/howto/argparse.rst:362 msgid "And now the output:" msgstr "" # 95f3c6e1f6ff407295cd42881bc8b685 #: ../src/Doc/howto/argparse.rst:376 msgid "We've brought back a positional argument, hence the complaint." msgstr "" # 14c74304cae3408bbee542d20599aa77 #: ../src/Doc/howto/argparse.rst:378 msgid "Note that the order does not matter." msgstr "" # b1997585bd4e4bdfa81eb2674454962e #: ../src/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 "" # a3e67eade5ea48aa971ac7fdbfadba1d #: ../src/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 "" # ff50803d09054f7fb826f0207b9870b0 #: ../src/Doc/howto/argparse.rst:450 msgid "" "Note that the change also reflects both in the error message as well as the " "help string." msgstr "" # 36dc67e241e1421c81469dd3c1215ebd #: ../src/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 "" # 8546c388b9ba46e4a33e106bf56b4c46 #: ../src/Doc/howto/argparse.rst:472 msgid "" "We have introduced another action, \"count\", to count the number of " "occurrences of a specific optional arguments:" msgstr "" # da62432192934a6cbd3ce0fdc3fd852c #: ../src/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 "" # 238e2227b86048c78eebfa3a92615746 #: ../src/Doc/howto/argparse.rst:503 msgid "It also behaves similar to \"store_true\" action." msgstr "" # 96349d6535594b17a600ad840e547332 #: ../src/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 "" # 3df4bafd899e4101baa9cf065eb8d1cb #: ../src/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 "" # a15ad8b69c5c4d0f8ade8df1655f564c #: ../src/Doc/howto/argparse.rst:511 msgid "" "As should be expected, specifying the long form of the flag, we should get " "the same output." msgstr "" # bba2cb9134de4a1ba8266001ce32e227 #: ../src/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 out script (e.g. via the ``help`` keyword argument)." msgstr "" # 7c3baa4d38a04921bbb34db75f40191f #: ../src/Doc/howto/argparse.rst:518 msgid "That last output exposes a bug in our program." msgstr "" # ede443f12b194bf08b8af2cc84de72c7 #: ../src/Doc/howto/argparse.rst:521 msgid "Let's fix::" msgstr "" # 42d9f54500cb4fe7a3f7f04764af02a7 #: ../src/Doc/howto/argparse.rst:540 msgid "And this is what it gives:" msgstr "" # e06d6df0f277456c898c83b64e6e07fd #: ../src/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 "" # a83746c6d4f84a3ab4f17a816ad8d27e #: ../src/Doc/howto/argparse.rst:557 msgid "Third output not so good." msgstr "" # fc17fe3866c44c2c865e2ade4f0cf235 #: ../src/Doc/howto/argparse.rst:559 msgid "Let's fix that bug::" msgstr "" # fc49dd9b000d4a2e9bd86f5c87ae7611 #: ../src/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 "" # f7b5161d927440aa913b318a3cb63e3a #: ../src/Doc/howto/argparse.rst:583 msgid "And:" msgstr "" # 48d847a95afe4972a90685bb5dfa27e7 #: ../src/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 "" # 9ef1eb9b41ba423a92ddd13d4b708fce #: ../src/Doc/howto/argparse.rst:597 msgid "Getting a little more advanced" msgstr "" # 2dadf9c3eab740f4b7570152a47b84c9 #: ../src/Doc/howto/argparse.rst:599 msgid "" "What if we wanted to expand our tiny program to perform other powers, not " "just squares::" msgstr "" # f3bf44877bc64c0aa86abae6e2f0acc6 # e4e884a3fc7347999e313d0b14998905 #: ../src/Doc/howto/argparse.rst:616 ../src/Doc/howto/argparse.rst:654 msgid "Output:" msgstr "" # ec32d3f0faf6456687bc1073526ec4bb #: ../src/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 "" # f8ffc56259fe4a6ca816aaae8589db93 #: ../src/Doc/howto/argparse.rst:668 msgid "Conflicting options" msgstr "" # 676c05799d414eddb22479972d2b480e #: ../src/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 "" # 713077aa2c824297950aa968d2444dcd #: ../src/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 "" # 45d600c444b441928858bfedbb823c46 #: ../src/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 "" # 73f555c6fd084854a2d62f34e6ef4553 #: ../src/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 "" # 927f5f87a382492ab7a3926dda0d4bbc #: ../src/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 "" # 1b05b0b91b544885bf48160c113f9998 #: ../src/Doc/howto/argparse.rst:761 msgid "Conclusion" msgstr "" # f791bef919cf4cf5bdeaa83a63b11948 #: ../src/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 "" # 1fa71cf6d04f43c2b12e7c684dc07815 #: ../src/Doc/howto/cporting.rst:7 msgid "Porting Extension Modules to Python 3" msgstr "" #: ../src/Doc/howto/cporting.rst:9 msgid "Benjamin Peterson" msgstr "Benjamin Peterson" # 61237b37ee8a439ebd64184b40f78ea1 #: ../src/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 "" #: ../src/Doc/howto/cporting.rst:23 msgid "Conditional compilation" msgstr "" # 6c17774a852c4a8ebff5ef99673811e3 #: ../src/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 "" #: ../src/Doc/howto/cporting.rst:32 msgid "" "API functions that are not present can be aliased to their equivalents " "within conditional blocks." msgstr "" #: ../src/Doc/howto/cporting.rst:37 msgid "Changes to Object APIs" msgstr "" # 8f247eff42394718972ca8f2f161e758 #: ../src/Doc/howto/cporting.rst:39 msgid "" "Python 3 merged together some types with similar functions while cleanly " "separating others." msgstr "" #: ../src/Doc/howto/cporting.rst:44 msgid "str/unicode Unification" msgstr "" # a9f354480a3642a9a9e475e80b310aee #: ../src/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 "" #: ../src/Doc/howto/cporting.rst:95 msgid "long/int Unification" msgstr "" # 3767f985b0b640ab86b6e4fcac418764 #: ../src/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 "" #: ../src/Doc/howto/cporting.rst:104 msgid "Module initialization and state" msgstr "" # 0926a05def714bc6be7470c21a597de2 #: ../src/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 "" # 2b2b820305204eb98416dbc169903c6a #: ../src/Doc/howto/cporting.rst:197 msgid "CObject replaced with Capsule" msgstr "" # e40a24473fd74f3183273bf061bd0ae1 #: ../src/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 "" # 74ae9cf398894df4b60b8564bb3748df #: ../src/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 "" # 2b7e3a305e1f464991a47c4c4d58c9e0 #: ../src/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 "" # 8b1240e394814c219739b84896bc630a #: ../src/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 "" # 691c2900ef5e425cbe070f2624ae02a5 #: ../src/Doc/howto/cporting.rst:228 msgid "The name parameter passed in to :c:func:`PyCapsule_New` is ignored." msgstr "" # a6ed5310b58f4270b84746b90266e4c5 #: ../src/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 "" # 223109969e9a4a6c943bd1f206d9ff8c #: ../src/Doc/howto/cporting.rst:234 msgid ":c:func:`PyCapsule_GetName` always returns NULL." msgstr "" # 94468e8bbf364d05820aeca035f9f767 #: ../src/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 "" # 7d9b3aa9994a47948fb61ddc42eaa6be #: ../src/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 "" #: ../src/Doc/howto/cporting.rst:252 msgid "Other options" msgstr "" # efe92c9f2c7f4d2ba14c533d6d0d159d #: ../src/Doc/howto/cporting.rst:254 msgid "" "If you are writing a new extension module, you might consider `Cython " "`_. It translates a Python-like language to C. The " "extension modules it creates are compatible with Python 3 and Python 2." msgstr "" #: ../src/Doc/howto/curses.rst:5 msgid "Curses Programming with Python" msgstr "" #: ../src/Doc/howto/curses.rst:7 msgid "A.M. Kuchling, Eric S. Raymond" msgstr "" #: ../src/Doc/howto/curses.rst:8 msgid "2.03" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/curses.rst:18 msgid "What is curses?" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/curses.rst:59 msgid "The Python curses module" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/curses.rst:75 msgid "Starting and ending a curses application" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/curses.rst:108 msgid "" "Terminating a curses application is much easier than starting one. You'll " "need to call ::" msgstr "" #: ../src/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 "" # 58b48c143b1144d09096bcf48a52b5ea #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/curses.rst:135 msgid "Windows and Pads" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/curses.rst:210 msgid "Displaying Text" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/curses.rst:225 msgid "Form" msgstr "" #: ../src/Doc/howto/curses.rst:225 ../src/Doc/howto/curses.rst:283 msgid "Description" msgstr "" #: ../src/Doc/howto/curses.rst:227 msgid "*str* or *ch*" msgstr "" #: ../src/Doc/howto/curses.rst:227 msgid "Display the string *str* or character *ch* at the current position" msgstr "" #: ../src/Doc/howto/curses.rst:230 msgid "*str* or *ch*, *attr*" msgstr "" #: ../src/Doc/howto/curses.rst:230 msgid "" "Display the string *str* or character *ch*, using attribute *attr* at the " "current position" msgstr "" #: ../src/Doc/howto/curses.rst:234 msgid "*y*, *x*, *str* or *ch*" msgstr "" #: ../src/Doc/howto/curses.rst:234 msgid "Move to position *y,x* within the window, and display *str* or *ch*" msgstr "" #: ../src/Doc/howto/curses.rst:237 msgid "*y*, *x*, *str* or *ch*, *attr*" msgstr "" #: ../src/Doc/howto/curses.rst:237 msgid "" "Move to position *y,x* within the window, and display *str* or *ch*, using " "attribute *attr*" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/curses.rst:269 msgid "Attributes and Color" msgstr "" #: ../src/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 "" # d4ee7abe0a9845bab9d70653090828fa #: ../src/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 "" #: ../src/Doc/howto/curses.rst:283 msgid "Attribute" msgstr "" #: ../src/Doc/howto/curses.rst:285 msgid ":const:`A_BLINK`" msgstr "" #: ../src/Doc/howto/curses.rst:285 msgid "Blinking text" msgstr "" #: ../src/Doc/howto/curses.rst:287 msgid ":const:`A_BOLD`" msgstr "" #: ../src/Doc/howto/curses.rst:287 msgid "Extra bright or bold text" msgstr "" #: ../src/Doc/howto/curses.rst:289 msgid ":const:`A_DIM`" msgstr "" #: ../src/Doc/howto/curses.rst:289 msgid "Half bright text" msgstr "" #: ../src/Doc/howto/curses.rst:291 msgid ":const:`A_REVERSE`" msgstr "" #: ../src/Doc/howto/curses.rst:291 msgid "Reverse-video text" msgstr "" #: ../src/Doc/howto/curses.rst:293 msgid ":const:`A_STANDOUT`" msgstr "" #: ../src/Doc/howto/curses.rst:293 msgid "The best highlighting mode available" msgstr "" #: ../src/Doc/howto/curses.rst:295 msgid ":const:`A_UNDERLINE`" msgstr "" #: ../src/Doc/howto/curses.rst:295 msgid "Underlined text" msgstr "" #: ../src/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 "" # 410250bff4f14d3188d601724053c1f6 #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/curses.rst:324 msgid "An example, which displays a line of text using color pair 1::" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/curses.rst:360 msgid "User Input" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/curses.rst:419 msgid "For More Information" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/curses.rst:440 msgid "The ncurses FAQ: http://invisible-island.net/ncurses/ncurses.faq.html" msgstr "" #: ../src/Doc/howto/descriptor.rst:3 msgid "Descriptor HowTo Guide" msgstr "" #: ../src/Doc/howto/descriptor.rst:5 msgid "Raymond Hettinger" msgstr "" #: ../src/Doc/howto/descriptor.rst:6 msgid "" msgstr "" #: ../src/Doc/howto/descriptor.rst:11 msgid "Abstract" msgstr "Résumé" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:24 msgid "Definition and Introduction" msgstr "" #: ../src/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 "" #: ../src/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 "" # 94ad4b1b102944dcba5a7169e0d492b4 #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:51 msgid "Descriptor Protocol" msgstr "" #: ../src/Doc/howto/descriptor.rst:53 msgid "``descr.__get__(self, obj, type=None) --> value``" msgstr "" #: ../src/Doc/howto/descriptor.rst:55 msgid "``descr.__set__(self, obj, value) --> None``" msgstr "" #: ../src/Doc/howto/descriptor.rst:57 msgid "``descr.__delete__(self, obj) --> None``" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:81 msgid "Invoking Descriptors" msgstr "" #: ../src/Doc/howto/descriptor.rst:83 msgid "" "A descriptor can be called directly by its method name. For example, ``d." "__get__(obj)``." msgstr "" #: ../src/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 "" #: ../src/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 "" # 32c6b54eec0943caa7922e7e27e65fa3 #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:114 msgid "The important points to remember are:" msgstr "" #: ../src/Doc/howto/descriptor.rst:116 msgid "descriptors are invoked by the :meth:`__getattribute__` method" msgstr "" #: ../src/Doc/howto/descriptor.rst:117 msgid "overriding :meth:`__getattribute__` prevents automatic descriptor calls" msgstr "" #: ../src/Doc/howto/descriptor.rst:118 msgid "" ":meth:`__getattribute__` is only available with new style classes and objects" msgstr "" #: ../src/Doc/howto/descriptor.rst:119 msgid "" ":meth:`object.__getattribute__` and :meth:`type.__getattribute__` make " "different calls to :meth:`__get__`." msgstr "" #: ../src/Doc/howto/descriptor.rst:121 msgid "data descriptors always override instance dictionaries." msgstr "" #: ../src/Doc/howto/descriptor.rst:122 msgid "non-data descriptors may be overridden by instance dictionaries." msgstr "" # 3175df0c7cc241b69f0ac69f941f4bbc #: ../src/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 "" # 08d87a377d0443f78b2dcfc064c9595a #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:147 msgid "Descriptor Example" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:194 msgid "Properties" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:201 msgid "" "The documentation shows a typical use to define a managed attribute ``x``::" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:269 msgid "Functions and Methods" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:293 msgid "" "Running the interpreter shows how the function descriptor works in practice::" msgstr "" # e4e859d3b5db442a8691474caa6bfcd8 #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:322 msgid "Static Methods and Class Methods" msgstr "" #: ../src/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 "" #: ../src/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 a ``obj.f(*args)`` call into ``f(obj, *args)``. Calling ``klass." "f(*args)`` becomes ``f(*args)``." msgstr "" #: ../src/Doc/howto/descriptor.rst:332 msgid "This chart summarizes the binding and its two most useful variants:" msgstr "" #: ../src/Doc/howto/descriptor.rst:335 msgid "Transformation" msgstr "" #: ../src/Doc/howto/descriptor.rst:335 msgid "Called from an Object" msgstr "" #: ../src/Doc/howto/descriptor.rst:335 msgid "Called from a Class" msgstr "" #: ../src/Doc/howto/descriptor.rst:338 msgid "function" msgstr "" #: ../src/Doc/howto/descriptor.rst:338 msgid "f(obj, \\*args)" msgstr "" #: ../src/Doc/howto/descriptor.rst:338 ../src/Doc/howto/descriptor.rst:340 msgid "f(\\*args)" msgstr "" #: ../src/Doc/howto/descriptor.rst:340 msgid "staticmethod" msgstr "" #: ../src/Doc/howto/descriptor.rst:342 msgid "classmethod" msgstr "" #: ../src/Doc/howto/descriptor.rst:342 msgid "f(type(obj), \\*args)" msgstr "" #: ../src/Doc/howto/descriptor.rst:342 msgid "f(klass, \\*args)" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:351 msgid "" "Good candidates for static methods are methods that do not reference the " "``self`` variable." msgstr "" #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:363 msgid "" "Since staticmethods return the underlying function with no changes, the " "example calls are unexciting::" msgstr "" #: ../src/Doc/howto/descriptor.rst:376 msgid "" "Using the non-data descriptor protocol, a pure Python version of :func:" "`staticmethod` would look like this::" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/descriptor.rst:419 msgid "Now a new dictionary of unique keys can be constructed like this::" msgstr "" #: ../src/Doc/howto/descriptor.rst:424 msgid "" "Using the non-data descriptor protocol, a pure Python version of :func:" "`classmethod` would look like this::" msgstr "" #: ../src/Doc/howto/doanddont.rst:3 msgid "Idioms and Anti-Idioms in Python" msgstr "" #: ../src/Doc/howto/doanddont.rst:5 msgid "Moshe Zadka" msgstr "Moshe Zadka" #: ../src/Doc/howto/doanddont.rst:7 msgid "This document is placed in the public domain." msgstr "" #: ../src/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 "" #: ../src/Doc/howto/doanddont.rst:17 msgid "Language Constructs You Should Not Use" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/doanddont.rst:25 msgid "from module import \\*" msgstr "" #: ../src/Doc/howto/doanddont.rst:29 msgid "Inside Function Definitions" msgstr "" # 3b070374ab9c46db86141abca1cf9676 #: ../src/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 "" #: ../src/Doc/howto/doanddont.rst:41 msgid "At Module Level" msgstr "" #: ../src/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 "" # 8fcf2c18c08643d3ac37592887d0af07 #: ../src/Doc/howto/doanddont.rst:49 msgid "" "One of the most awful questions asked on the newsgroup is why this code::" msgstr "" #: ../src/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 "" # 0b24b7ab69d8496a94dbfaf694f4c904 #: ../src/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 "" #: ../src/Doc/howto/doanddont.rst:66 msgid "When It Is Just Fine" msgstr "" #: ../src/Doc/howto/doanddont.rst:68 msgid "There are situations in which ``from module import *`` is just fine:" msgstr "" #: ../src/Doc/howto/doanddont.rst:70 msgid "" "The interactive prompt. For example, ``from math import *`` makes Python an " "amazing scientific calculator." msgstr "" #: ../src/Doc/howto/doanddont.rst:73 msgid "When extending a module in C with a module in Python." msgstr "" #: ../src/Doc/howto/doanddont.rst:75 msgid "When the module advertises itself as ``from import *`` safe." msgstr "" # a8963819590c4e009a8034925e487be7 #: ../src/Doc/howto/doanddont.rst:79 msgid "Unadorned :keyword:`exec`, :func:`execfile` and friends" msgstr "" # 6a2d4f68a14e4ad094bb2a91644ccc2f #: ../src/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 "" # 0c70c8e0c8ff4ffc94c2b6e1c9a61a99 #: ../src/Doc/howto/doanddont.rst:87 msgid "Bad examples::" msgstr "" # d9f2b77e03bb473db871b2e8d4a745e7 #: ../src/Doc/howto/doanddont.rst:97 msgid "Good examples::" msgstr "" #: ../src/Doc/howto/doanddont.rst:112 msgid "from module import name1, name2" msgstr "" # deaddf57af464bbdb55a96b83622f6a0 #: ../src/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 "" #: ../src/Doc/howto/doanddont.rst:122 msgid "Bad example::" msgstr "" #: ../src/Doc/howto/doanddont.rst:132 msgid "Good example::" msgstr "" #: ../src/Doc/howto/doanddont.rst:144 msgid "except:" msgstr "" # db17e9662afe43ae89e4b42c1a0fb9aa #: ../src/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 "" # 1cbe89098ac342f09741e7e90261bc33 #: ../src/Doc/howto/doanddont.rst:151 msgid "The following code shows a great example of why this is bad::" msgstr "" # 94ddb2c34dea40a981d88196a9b00864 #: ../src/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 "" # 7ecf196aef1145f8a507557e4e7016b2 #: ../src/Doc/howto/doanddont.rst:163 msgid "A better way to write the above is ::" msgstr "" # 797e00c6b49246bf8979c7cca3623937 #: ../src/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 "" # fc0f356ef48c4fa4b2dbbe3609a9e957 #: ../src/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 "" #: ../src/Doc/howto/doanddont.rst:188 msgid "Exceptions" msgstr "Exceptions" #: ../src/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 "" #: ../src/Doc/howto/doanddont.rst:194 msgid "The following is a very popular anti-idiom ::" msgstr "" # 0ad6de21dc6643bd850c8f0c58c01ebc #: ../src/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 "" # c8eab7af0acd48008890c503f21d2ccd #: ../src/Doc/howto/doanddont.rst:211 msgid "Here is a somewhat better way to do it. ::" msgstr "" # 2ba23783cc7d48319a3bc36b8df9951d #: ../src/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 "" # af3b6105fb7e4b31a835dc790835749f #: ../src/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 "" # 9e71123b51df43f7ad1e8b1eff75a716 #: ../src/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 "" # 6f65e970712d46fab77f1f3081ef512a #: ../src/Doc/howto/doanddont.rst:238 msgid "So, an even better version of :func:`get_status()` is probably ::" msgstr "" # 0b812ac3a9744e2fab79e636f82a76e6 #: ../src/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 "" # 7a82e50381a347cda1f1463bb8728797 #: ../src/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 "" # 68f0bff64070451587bc0b260a486cf5 #: ../src/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 "" #: ../src/Doc/howto/doanddont.rst:263 msgid "Using the Batteries" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/doanddont.rst:274 msgid "Compare::" msgstr "" #: ../src/Doc/howto/doanddont.rst:281 msgid "" "More useful functions in :mod:`os.path`: :func:`basename`, :func:`dirname` " "and :func:`splitext`." msgstr "" # bd47e3bd1e094e6796b843e2c662d783 #: ../src/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 "" # 59605a0b22674180978040f9513b9392 #: ../src/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 "" #: ../src/Doc/howto/doanddont.rst:303 msgid "Using Backslash to Continue Statements" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/doanddont.rst:319 msgid "then it would just be subtly wrong." msgstr "" #: ../src/Doc/howto/doanddont.rst:321 msgid "" "It is usually much better to use the implicit continuation inside " "parenthesis:" msgstr "" #: ../src/Doc/howto/doanddont.rst:323 msgid "This version is bulletproof::" msgstr "" #: ../src/Doc/howto/functional.rst:3 msgid "Functional Programming HOWTO" msgstr "" #: ../src/Doc/howto/functional.rst:5 msgid "A. M. Kuchling" msgstr "" #: ../src/Doc/howto/functional.rst:6 msgid "0.31" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:16 ../src/Doc/howto/regex.rst:24 #: ../src/Doc/howto/urllib2.rst:16 msgid "Introduction" msgstr "Introduction" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:22 msgid "" "Programming languages support decomposing problems in several different ways:" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # f43392e813194be1b5b91376136aa56f #: ../src/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 "" #: ../src/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 "" # 5d8fb7519dda449396718895458147a8 #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:92 msgid "Formal provability." msgstr "" #: ../src/Doc/howto/functional.rst:93 msgid "Modularity." msgstr "" #: ../src/Doc/howto/functional.rst:94 msgid "Composability." msgstr "" #: ../src/Doc/howto/functional.rst:95 msgid "Ease of debugging and testing." msgstr "" #: ../src/Doc/howto/functional.rst:99 msgid "Formal provability" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:135 msgid "Modularity" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:145 msgid "Ease of debugging and testing" msgstr "" #: ../src/Doc/howto/functional.rst:147 msgid "Testing and debugging a functional-style program is easier." msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:161 msgid "Composability" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:176 msgid "Iterators" msgstr "Itérateurs" #: ../src/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 "" # 8965b08b62e44a9c9a04dc6bdb9fd4fb #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:196 msgid "You can experiment with the iteration interface manually:" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # 022f038034b94aa8878123cce12a6832 #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:261 msgid "Data Types That Support Iterators" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:267 msgid "" "Calling :func:`iter` on a dictionary returns an iterator that will loop over " "the dictionary's keys:" msgstr "" #: ../src/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 "" # 4ef7e00921324cf49d2f2566fd8aae12 #: ../src/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 "" #: ../src/Doc/howto/functional.rst:299 msgid "" "The :func:`dict` constructor can accept an iterator that returns a finite " "stream of ``(key, value)`` tuples:" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:314 msgid "" "Sets can take their contents from an iterable and let you iterate over the " "set's elements::" msgstr "" #: ../src/Doc/howto/functional.rst:324 msgid "Generator expressions and list comprehensions" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:345 msgid "" "You can select only certain elements by adding an ``\"if\"`` condition::" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:370 msgid "" "Again, for a list comprehension only the outside brackets are different " "(square brackets instead of parentheses)." msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:432 msgid "Generators" msgstr "Générateurs" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:447 msgid "Here's the simplest example of a generator function:" msgstr "" #: ../src/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 "" # 2a76967001804636ad2fcfa6bbed0045 #: ../src/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 "" #: ../src/Doc/howto/functional.rst:467 msgid "Here's a sample usage of the ``generate_ints()`` generator:" msgstr "" #: ../src/Doc/howto/functional.rst:484 msgid "" "You could equally write ``for i in generate_ints(5)``, or ``a,b,c = " "generate_ints(3)``." msgstr "" #: ../src/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 "" # d2309684b2ca48d492c27e55375610b2 #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:525 msgid "Passing values into a generator" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # 1f679b3767324cfead3c677ba8360bd6 #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:571 msgid "And here's an example of changing the counter:" msgstr "" # 0f566a83104f47b5b21fe1564a340bcc #: ../src/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 "" #: ../src/Doc/howto/functional.rst:593 msgid "" "In addition to ``send()``, there are two other new methods on generators:" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:619 msgid "Built-in functions" msgstr "" #: ../src/Doc/howto/functional.rst:621 msgid "" "Let's look in more detail at built-in functions often used with iterators." msgstr "" # db9c4b853dca458791d1b8dc23b975f7 #: ../src/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 "" # ccd98d828be7454b9d7c8680999c584e #: ../src/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 "" # a50c24b2bf454f8fb65d97ad4832ad0c #: ../src/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 "" # c95bd811a5f94c6ebf1518eea49e0e03 #: ../src/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 "" #: ../src/Doc/howto/functional.rst:655 msgid "This can also be written as a list comprehension:" msgstr "" # 58422958eb7d4136824dd1d1a38d4079 #: ../src/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 "" # d764b6408cf9446ab21bd2e0490a23ff #: ../src/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 "" # bb2dcf92629848a9a8a82414382b3c0c #: ../src/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 "" # 443c8c29d8c742339a48bdd4f27f655d #: ../src/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 "" # 1a6b37109b904b81a1359d6563ec8572 #: ../src/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 "" #: ../src/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 "" # 4a860e3a6a1447838f78526da75dea72 #: ../src/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 "" # 40b61bab800c418d9af70280f48db5e5 #: ../src/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 "" # c4d9ef84666c4a6a89abb857a22d2658 #: ../src/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 "" #: ../src/Doc/howto/functional.rst:766 msgid "Small functions and the lambda expression" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:788 msgid "" "An alternative is to just use the ``def`` statement and define a function in " "the usual way::" msgstr "" #: ../src/Doc/howto/functional.rst:800 msgid "" "Which alternative is preferable? That's a style question; my usual course " "is to avoid using ``lambda``." msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:823 msgid "But it would be best of all if I had simply used a ``for`` loop::" msgstr "" #: ../src/Doc/howto/functional.rst:829 msgid "Or the :func:`sum` built-in and a generator expression::" msgstr "" # b24d1d1e5f5d472e89a5dbe9e6a31b54 #: ../src/Doc/howto/functional.rst:833 msgid "Many uses of :func:`reduce` are clearer when written as ``for`` loops." msgstr "" #: ../src/Doc/howto/functional.rst:835 msgid "" "Fredrik Lundh once suggested the following set of rules for refactoring uses " "of ``lambda``:" msgstr "" #: ../src/Doc/howto/functional.rst:838 msgid "Write a lambda function." msgstr "" #: ../src/Doc/howto/functional.rst:839 msgid "Write a comment explaining what the heck that lambda does." msgstr "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:842 msgid "Convert the lambda to a def statement, using that name." msgstr "" #: ../src/Doc/howto/functional.rst:843 msgid "Remove the comment." msgstr "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:850 msgid "The itertools module" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:856 msgid "The module's functions fall into a few broad classes:" msgstr "" #: ../src/Doc/howto/functional.rst:858 msgid "Functions that create a new iterator based on an existing iterator." msgstr "" #: ../src/Doc/howto/functional.rst:859 msgid "Functions for treating an iterator's elements as function arguments." msgstr "" #: ../src/Doc/howto/functional.rst:860 msgid "Functions for selecting portions of an iterator's output." msgstr "" #: ../src/Doc/howto/functional.rst:861 msgid "A function for grouping an iterator's output." msgstr "" #: ../src/Doc/howto/functional.rst:864 msgid "Creating new iterators" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # 775bb2fb158242ec8e0c8c8a6114b633 #: ../src/Doc/howto/functional.rst:896 msgid "" "``itertools.izip(iterA, iterB, ...)`` takes one element from each iterable " "and returns them in a tuple::" msgstr "" # 4dfde9f89b0d4743a23d94b6633a1f72 #: ../src/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 `__.)" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:951 msgid "Calling functions on elements" msgstr "" # 9c19f240e894413c879f743d48a97030 #: ../src/Doc/howto/functional.rst:953 msgid "" "Two functions are used for calling other functions on the contents of an " "iterable." msgstr "" # 0759bbd996f7403fb911682ff3ec88bb #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:978 msgid "Selecting elements" msgstr "" #: ../src/Doc/howto/functional.rst:980 msgid "" "Another group of functions chooses a subset of an iterator's elements based " "on a predicate." msgstr "" # eb4b0d8c72964a87ba6c0b8652d5ae90 #: ../src/Doc/howto/functional.rst:983 msgid "" "``itertools.ifilter(predicate, iter)`` returns all the elements for which " "the predicate returns true::" msgstr "" # 7955827bd4b14ebc85b8a282478d275d #: ../src/Doc/howto/functional.rst:992 msgid "" "``itertools.ifilterfalse(predicate, iter)`` is the opposite, returning all " "elements for which the predicate returns false::" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:1026 msgid "Grouping elements" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:1068 msgid "The functools module" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:1085 msgid "Here's a small but realistic example::" msgstr "" #: ../src/Doc/howto/functional.rst:1099 msgid "The operator module" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:1106 msgid "Some of the functions in this module are:" msgstr "" # e45e8f8244a247e2ac07d059683e532e #: ../src/Doc/howto/functional.rst:1108 msgid "" "Math operations: ``add()``, ``sub()``, ``mul()``, ``div()``, ``floordiv()``, " "``abs()``, ..." msgstr "" #: ../src/Doc/howto/functional.rst:1110 msgid "Logical operations: ``not_()``, ``truth()``." msgstr "" #: ../src/Doc/howto/functional.rst:1111 msgid "Bitwise operations: ``and_()``, ``or_()``, ``invert()``." msgstr "" #: ../src/Doc/howto/functional.rst:1112 msgid "" "Comparisons: ``eq()``, ``ne()``, ``lt()``, ``le()``, ``gt()``, and ``ge()``." msgstr "" #: ../src/Doc/howto/functional.rst:1113 msgid "Object identity: ``is_()``, ``is_not()``." msgstr "" #: ../src/Doc/howto/functional.rst:1115 msgid "Consult the operator module's documentation for a complete list." msgstr "" #: ../src/Doc/howto/functional.rst:1119 ../src/Doc/howto/unicode.rst:696 msgid "Revision History and Acknowledgements" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:1126 msgid "Version 0.1: posted June 30 2006." msgstr "" #: ../src/Doc/howto/functional.rst:1128 msgid "Version 0.11: posted July 1 2006. Typo fixes." msgstr "" #: ../src/Doc/howto/functional.rst:1130 msgid "" "Version 0.2: posted July 10 2006. Merged genexp and listcomp sections into " "one. Typo fixes." msgstr "" #: ../src/Doc/howto/functional.rst:1133 msgid "" "Version 0.21: Added more references suggested on the tutor mailing list." msgstr "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:1140 ../src/Doc/howto/unicode.rst:205 #: ../src/Doc/howto/unicode.rst:492 ../src/Doc/howto/unicode.rst:686 msgid "References" msgstr "" #: ../src/Doc/howto/functional.rst:1143 msgid "General" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/functional.rst:1156 msgid "" "http://en.wikipedia.org/wiki/Functional_programming: General Wikipedia entry " "describing functional programming." msgstr "" #: ../src/Doc/howto/functional.rst:1159 msgid "http://en.wikipedia.org/wiki/Coroutine: Entry for coroutines." msgstr "" #: ../src/Doc/howto/functional.rst:1161 msgid "" "http://en.wikipedia.org/wiki/Currying: Entry for the concept of currying." msgstr "" #: ../src/Doc/howto/functional.rst:1164 msgid "Python-specific" msgstr "" #: ../src/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 "" # 0433fa1150da4ff7b3cd48a20c08fbf0 #: ../src/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 "" # 79a43c0711b445a5a544cba9fb2691ca #: ../src/Doc/howto/functional.rst:1174 msgid "" "`part 1 `__, `part 2 `__, and `part 3 `__," msgstr "" #: ../src/Doc/howto/functional.rst:1180 msgid "Python documentation" msgstr "" #: ../src/Doc/howto/functional.rst:1182 msgid "Documentation for the :mod:`itertools` module." msgstr "" #: ../src/Doc/howto/functional.rst:1184 msgid "Documentation for the :mod:`operator` module." msgstr "" #: ../src/Doc/howto/functional.rst:1186 msgid ":pep:`289`: \"Generator Expressions\"" msgstr "" #: ../src/Doc/howto/functional.rst:1188 msgid "" ":pep:`342`: \"Coroutines via Enhanced Generators\" describes the new " "generator features in Python 2.5." msgstr "" #: ../src/Doc/howto/index.rst:3 msgid "Python HOWTOs" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/index.rst:11 msgid "Currently, the HOWTOs are:" msgstr "" # 4f1f57103f294dc395ce3431cc9330b7 #: ../src/Doc/howto/logging.rst:3 msgid "Logging HOWTO" msgstr "" # 65b3c45dd137494ca1e0b60718d3c9ce # d0a2d0e9480d4a35aff3eb44698fe1e0 #: ../src/Doc/howto/logging.rst:5 ../src/Doc/howto/logging-cookbook.rst:7 msgid "Vinay Sajip " msgstr "" # 0b7f9af1ca8843e9b75234d3b30aa959 #: ../src/Doc/howto/logging.rst:12 msgid "Basic Logging Tutorial" msgstr "" # d90d7449c5184f929731f84f6de11a8c #: ../src/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 "" # ec25d27883004e0ab8f4f702de97a67d #: ../src/Doc/howto/logging.rst:23 msgid "When to use logging" msgstr "" # 7295593185584a3e94b198069fe3c0ad #: ../src/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 "" # 329f086d2fbf4654b1804b138c1b7795 #: ../src/Doc/howto/logging.rst:31 msgid "Task you want to perform" msgstr "" # 828741848e7346ba8a9b21c8a4594c0c #: ../src/Doc/howto/logging.rst:31 msgid "The best tool for the task" msgstr "" # 681079f4c80147ffa674884ffd16ea9e #: ../src/Doc/howto/logging.rst:33 msgid "" "Display console output for ordinary usage of a command line script or program" msgstr "" # c51e568135e54cbe84ba9f6fe6420db0 #: ../src/Doc/howto/logging.rst:33 msgid ":func:`print`" msgstr "" # 2111f1f3ccfd4fd18bae421d9f9aab67 #: ../src/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 "" # 753d3b3814c645bd8379ebd08deaa87d #: ../src/Doc/howto/logging.rst:37 msgid "" ":func:`logging.info` (or :func:`logging.debug` for very detailed output for " "diagnostic purposes)" msgstr "" # 2b06f4b58a8e455d94cdfdb4cc92be5c #: ../src/Doc/howto/logging.rst:42 msgid "Issue a warning regarding a particular runtime event" msgstr "" # 70df136b6bf747e893d85821ebbddfb6 #: ../src/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 "" # 5446c4f930804bb8a4c2b602c43eb120 #: ../src/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 "" # 1f67c85b2bb74bf7ab47f0a5e8569b8e #: ../src/Doc/howto/logging.rst:52 msgid "Report an error regarding a particular runtime event" msgstr "" # cb0b1bb84fe94f84ac6bdff939d322e4 #: ../src/Doc/howto/logging.rst:52 msgid "Raise an exception" msgstr "" # 6960b3b4cd75488c99924ccb262ae6f9 #: ../src/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 "" # 36b8d971916a4de08e2f5cff7e88cf2d #: ../src/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 "" # 15133143a6cb48f4af0c7ab49b88ddfb #: ../src/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 "" # f3c8e2c9cdee4d1bb3f0b16138b5a226 # dd3d23b35360438b92570155d5210b61 #: ../src/Doc/howto/logging.rst:69 ../src/Doc/howto/logging.rst:794 msgid "Level" msgstr "" # a6bbc26de8da43c5826878e44528294f #: ../src/Doc/howto/logging.rst:69 msgid "When it's used" msgstr "" # 8ae4dcb4fe2b43708fad71d7bca1343a # 6268a642e9b241f988db1fb0ff24ed97 #: ../src/Doc/howto/logging.rst:71 ../src/Doc/howto/logging.rst:804 msgid "``DEBUG``" msgstr "" # 846a7464bd4942a7b48bb9de8a2f3ff6 #: ../src/Doc/howto/logging.rst:71 msgid "" "Detailed information, typically of interest only when diagnosing problems." msgstr "" # a665da04a6854416b5d2767cb2eb0468 # 9beadc188b264b65b9bc85843f5e8770 #: ../src/Doc/howto/logging.rst:74 ../src/Doc/howto/logging.rst:802 msgid "``INFO``" msgstr "" # e738e61ffa4246478690d124c09a7eeb #: ../src/Doc/howto/logging.rst:74 msgid "Confirmation that things are working as expected." msgstr "" # c9d7d51ce00d4705964bac5f01e3ca25 # 63a390ce620d4a40a04707824b431428 #: ../src/Doc/howto/logging.rst:77 ../src/Doc/howto/logging.rst:800 msgid "``WARNING``" msgstr "" # bb34bcc063cd4c63ab07f916fdedb702 #: ../src/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 "" # 8d4ef2d1497d4eb5a5781ea52bfa897a # 825ee3b82e454c7584172f05f3e01f04 #: ../src/Doc/howto/logging.rst:82 ../src/Doc/howto/logging.rst:798 msgid "``ERROR``" msgstr "" # fb15fb76bd4d4d8e8a531cc754dbb4a5 #: ../src/Doc/howto/logging.rst:82 msgid "" "Due to a more serious problem, the software has not been able to perform " "some function." msgstr "" # 930288483e494a9f9fc69c30e8842795 # 489e9c9dc08b4f37bbde0ad825687f8c #: ../src/Doc/howto/logging.rst:85 ../src/Doc/howto/logging.rst:796 msgid "``CRITICAL``" msgstr "" # 4ea27f275fbc4613b0cbc54d3c02373e #: ../src/Doc/howto/logging.rst:85 msgid "" "A serious error, indicating that the program itself may be unable to " "continue running." msgstr "" # 3536e0219683480fa795ac4d51852804 #: ../src/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 "" # 75dfca248365401b8da1163d115fc97b #: ../src/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 "" # 1b09a37cec504c9e8af14f6c27046fd4 #: ../src/Doc/howto/logging.rst:101 msgid "A simple example" msgstr "" # d907bcdc8f5140ecb674785e71d5d613 #: ../src/Doc/howto/logging.rst:103 msgid "A very simple example is::" msgstr "" # 8974cebbb9ef41618a43fbff4673264c #: ../src/Doc/howto/logging.rst:109 msgid "If you type these lines into a script and run it, you'll see::" msgstr "" # 2b9ce51dc05e4a23a08e77ec74c416cc #: ../src/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 "" # 5c606f6ff5a24156b06d302b318c71d8 #: ../src/Doc/howto/logging.rst:122 msgid "Logging to a file" msgstr "" # 1b73497e0f5b4302bf169656e99821eb #: ../src/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 "" # 9e30a537bcc8491e91083272e5016c07 #: ../src/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 "" # bc10937a53cb4d06915d192c7cc1ac20 #: ../src/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 "" # 03972b897f20416e8af61cab8e1b945c #: ../src/Doc/howto/logging.rst:145 msgid "" "If you want to set the logging level from a command-line option such as::" msgstr "" # 7e0a734744f44166a0bc99eb5de37cf3 #: ../src/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 "" # f21f97965a3046178fb1a2d35ad1d51e #: ../src/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 "" # da33353ac2a14d2eb53023ba3bdad78e #: ../src/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 "" # 25238040105c44e7a58558b863736a9c #: ../src/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 "" # 236a87897bc4409f966d9fe8569692e1 #: ../src/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 "" # 8f030ab2906c4cd98d23fff0bd997c32 #: ../src/Doc/howto/logging.rst:183 msgid "Logging from multiple modules" msgstr "" # 656e4a7d8dcd47a6a450d926084528e1 #: ../src/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 "" # 00cbfee41d64491ba4163525e01c4088 #: ../src/Doc/howto/logging.rst:209 msgid "If you run *myapp.py*, you should see this in *myapp.log*::" msgstr "" # 288706eb43124e1da5328e8271fad100 #: ../src/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 "" # 2aaf29e0126640099f1f0cc3025bf5b5 #: ../src/Doc/howto/logging.rst:225 msgid "Logging variable data" msgstr "" # 96aca89d50d048dbb10751d74763ab3c #: ../src/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 "" # 4707deac65324e7290606ffc63f0f03c #: ../src/Doc/howto/logging.rst:233 msgid "will display::" msgstr "" # 4bd36860470e4c649b6565a8fb7015f8 #: ../src/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 "" # 19d878f01793404788e41d271463f9d6 #: ../src/Doc/howto/logging.rst:246 msgid "Changing the format of displayed messages" msgstr "" # 64d09c4ca1e146629016fe66cf7c84b8 #: ../src/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 "" # 19722281939544b1bb3f399a1767f58a #: ../src/Doc/howto/logging.rst:257 msgid "which would print::" msgstr "" # a910e22d2f5c4500b87f62643359b222 #: ../src/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 "" # 92ae82b02a9f4b09b9ca1a842efd6e59 #: ../src/Doc/howto/logging.rst:272 msgid "Displaying the date/time in messages" msgstr "" # 47aedfa597a7434d98cafeef08cc7a59 #: ../src/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 "" # b1785110acd04394aaab3a9d3958f2ae #: ../src/Doc/howto/logging.rst:281 msgid "which should print something like this::" msgstr "" # 203d1c0dd3b54db8b32a7cf07bb68411 #: ../src/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 "" # c057f2e907a640b0b2e68d9737ac1351 #: ../src/Doc/howto/logging.rst:293 msgid "which would display something like this::" msgstr "" # bd1e3da11d684da6a74add8d295545ec #: ../src/Doc/howto/logging.rst:297 msgid "" "The format of the *datefmt* argument is the same as supported by :func:`time." "strftime`." msgstr "" # 7d33d1c0f6eb4d9588d21c03b8792ec6 #: ../src/Doc/howto/logging.rst:302 msgid "Next Steps" msgstr "" # f2a0ba57517e4648a1b06c1f281af298 #: ../src/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 "" # b24fa96d7f364877bdc04650b55ba2b3 #: ../src/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 "" # fc47ef89d4fb415aa6d898db658b282f #: ../src/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 "" # e2a5881504de4c2b83a9a08843ae993c #: ../src/Doc/howto/logging.rst:324 msgid "Advanced Logging Tutorial" msgstr "" # 2b0fceccdc6b4cc6bb8bbf047c017eca #: ../src/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 "" # dd2717f66d2247fabd7d3303a522da40 #: ../src/Doc/howto/logging.rst:329 msgid "Loggers expose the interface that application code directly uses." msgstr "" # 5e50eb77d0d54c38a57cc30f9df00069 #: ../src/Doc/howto/logging.rst:330 msgid "" "Handlers send the log records (created by loggers) to the appropriate " "destination." msgstr "" # 95436fe2027345d7be08b4595424332b #: ../src/Doc/howto/logging.rst:332 msgid "" "Filters provide a finer grained facility for determining which log records " "to output." msgstr "" # 8e34945dc8284df5939af78a70d528af #: ../src/Doc/howto/logging.rst:334 msgid "Formatters specify the layout of log records in the final output." msgstr "" # cb7b9eadf4ab4a6187eb8b210ea79d23 #: ../src/Doc/howto/logging.rst:336 msgid "" "Log event information is passed between loggers, handlers, filters and " "formatters in a :class:`LogRecord` instance." msgstr "" # 23fbe588545248dd990be5a45d3af9bf #: ../src/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 "" # 7c87284caf9a432eb73d93f79afbc2fe #: ../src/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 "" # 72ae200ea40d4cc4b06b1afa4c40792b #: ../src/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 "" # a8f867cfdf00463892a9aba951039162 #: ../src/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 "" # a3746460e5a24eaab8c6c9e8bd50f2fb #: ../src/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 "" # 54a9491bcc94436c8c06baf8fe4ba935 #: ../src/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 "" # 2008620fdbac44f993c22668c28c545c #: ../src/Doc/howto/logging.rst:375 msgid "The default format set by :func:`basicConfig` for messages is::" msgstr "" # 47b9dd70ec994284ba0c868e0b2ef7aa #: ../src/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 "" # b8adf0835beb484aba0b9c2da2a82f2e #: ../src/Doc/howto/logging.rst:384 msgid "Logging Flow" msgstr "" # 14b2ed380bd24a2d8f2dd53a48686618 #: ../src/Doc/howto/logging.rst:386 msgid "" "The flow of log event information in loggers and handlers is illustrated in " "the following diagram." msgstr "" # b353f5a682a24c9292719fe3eabb0c31 #: ../src/Doc/howto/logging.rst:392 msgid "Loggers" msgstr "" # 6339e3b5d4c847c3b837df492421c640 #: ../src/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 "" # 7c6d8e2a5a224de0a86da47dab617825 #: ../src/Doc/howto/logging.rst:400 msgid "" "The most widely used methods on logger objects fall into two categories: " "configuration and message sending." msgstr "" # 4984d6d837a64642a1a6c8074e7b3038 #: ../src/Doc/howto/logging.rst:403 msgid "These are the most common configuration methods:" msgstr "" # b97521a6662f462db0ad913ed4f297db #: ../src/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 "" # 9442f93a860f4d428999121a34d0be17 #: ../src/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 "" # bda414615c4d40c28d89e720e95b0b1a #: ../src/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 "" # 9a32209a8c4941f6a955de2f83ef4012 #: ../src/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 "" # 138f5e30b0bb4506aa2e5cc5316be2cd #: ../src/Doc/howto/logging.rst:422 msgid "" "With the logger object configured, the following methods create log messages:" msgstr "" # a0e77824a45e45a5be737a71ae52d4dc #: ../src/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 "" # bed88bfc13d9481bb98f3b4d5be605c0 #: ../src/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 "" # 632d699272834fe6a73732ecf128761e #: ../src/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 "" # 7c1227c2d53a4fe6997cc6e9ddb3a47a #: ../src/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 "" # 96215912457545fd9c35320f4417cc26 #: ../src/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 "" # 71f38ce9036d4a4e9da7c8fb61e90d35 #: ../src/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 "" # 04d1211bca61498c897f614f63f53735 #: ../src/Doc/howto/logging.rst:469 msgid "Handlers" msgstr "" # 6f681a4e98654c32a888ad51258e64d0 #: ../src/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 "" # beadeeb8c003417bbd66fa66c7d7cf47 #: ../src/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 "" # 417032447e714133ab5d15bd8bc01139 #: ../src/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 "" # a4cc7add80f747cbb0b328faeb6a2faa #: ../src/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 "" # f1a5188ca6b0405ba011f57b33e0da3b #: ../src/Doc/howto/logging.rst:496 msgid "" ":meth:`~Handler.setFormatter` selects a Formatter object for this handler to " "use." msgstr "" # f5812dbd070540fb82efcbaf7c988ccd #: ../src/Doc/howto/logging.rst:499 msgid "" ":meth:`~Handler.addFilter` and :meth:`~Handler.removeFilter` respectively " "configure and deconfigure filter objects on handlers." msgstr "" # d7ebe8f4cc534e77878aaa467a54c0f7 #: ../src/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 "" # 68e5e8f13d2546a6839d11180a915044 #: ../src/Doc/howto/logging.rst:509 msgid "Formatters" msgstr "" # ca68e914ef9a4e8e9af968d993e6f8ea #: ../src/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 "" # e22b9dbedd574d4d9fc2d18591b5b1d2 #: ../src/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 "" # 05ba9e4f4d684ac6a432500b44a42a2a #: ../src/Doc/howto/logging.rst:524 msgid "with the milliseconds tacked on at the end." msgstr "" # 595451cc7a32465b8036658f16569914 #: ../src/Doc/howto/logging.rst:526 msgid "" "The message format string uses ``%()s`` styled string " "substitution; the possible keys are documented in :ref:`logrecord-" "attributes`." msgstr "" # fcfa086632304d85b9fda552b79e19c9 #: ../src/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 "" # f801d948dc5f4239855788479d748a5d #: ../src/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 "" # 01bb0a8c8d274e569ece1f7110ccd1dc #: ../src/Doc/howto/logging.rst:545 msgid "Configuring Logging" msgstr "" # d17331fddb69471b9ed96e15ee5e9a32 #: ../src/Doc/howto/logging.rst:549 msgid "Programmers can configure logging in three ways:" msgstr "" # 65a9a34640ee4290a9ba79d48d8d4481 #: ../src/Doc/howto/logging.rst:551 msgid "" "Creating loggers, handlers, and formatters explicitly using Python code that " "calls the configuration methods listed above." msgstr "" # d4d780f19ea14d1b9a34a2cb071163be #: ../src/Doc/howto/logging.rst:553 msgid "" "Creating a logging config file and reading it using the :func:`fileConfig` " "function." msgstr "" # ebcd354b464d40d784cbcdadef28df6c #: ../src/Doc/howto/logging.rst:555 msgid "" "Creating a dictionary of configuration information and passing it to the :" "func:`dictConfig` function." msgstr "" # 3d203274869b4bfb868209681006940f #: ../src/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 "" # aa7aa865612d4d99bd3e53629c42b300 #: ../src/Doc/howto/logging.rst:588 msgid "" "Running this module from the command line produces the following output::" msgstr "" # 1ad0db31d640485a9eb16f5a4c66926b #: ../src/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 "" # 5a25cd5854a64a7d94f8fe1f2b29a936 #: ../src/Doc/howto/logging.rst:616 msgid "Here is the logging.conf file::" msgstr "" # 8c60a062160d45109bfef70ffeb7ef87 #: ../src/Doc/howto/logging.rst:647 msgid "" "The output is nearly identical to that of the non-config-file-based example::" msgstr "" # da2ed4ced3784612a7715d90da7f69c6 #: ../src/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 "" # 2a5947a51ff5489ab33a5f5d4ab85e55 #: ../src/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 "" # 632f34cf6eb64963bc5193711482c45a #: ../src/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 "" # d231c449986242808916b5b0bfc2706e #: ../src/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 "" # 0de18de43e6c4292a5e0e75971f202cc #: ../src/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 "" # 611a1fc047d84d41a9eba48f0692337b #: ../src/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 "" # f80e52a5059f4c1cb300cc0455ce3a8d #: ../src/Doc/howto/logging.rst:719 msgid "" "For more information about logging using a dictionary, see :ref:`logging-" "config-api`." msgstr "" # 0b65c9e4dd744699968a09936f52dd8f #: ../src/Doc/howto/logging.rst:723 msgid "What happens if no configuration is provided" msgstr "" # ef691d17244549bbb7faa4e116bb044a #: ../src/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 "" # 90643e9147bd40749feae5415b38691b #: ../src/Doc/howto/logging.rst:730 msgid "For Python 2.x, the behaviour is as follows:" msgstr "" # d478b740cadd45e98bea736455936be1 #: ../src/Doc/howto/logging.rst:732 msgid "" "If *logging.raiseExceptions* is *False* (production mode), the event is " "silently dropped." msgstr "" # 6447007e63ee4bff9b70357ce2092fa9 #: ../src/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 "" # 276825f5926a40e2959cb6eabaf974cd #: ../src/Doc/howto/logging.rst:741 msgid "Configuring Logging for a Library" msgstr "" # d9986a2b242b491ba1827a8858da67b6 #: ../src/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 "" # e476d82bbafe488a9ebbd197f95cdb5f #: ../src/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 "" # c0ab6555c911477798674b1c6f6155f4 #: ../src/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 "" # b61833135b6b45548f10d8d75ea61796 #: ../src/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 "" # b529d53e602645c48908513a4f81acbe #: ../src/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 "" # b8adf0835beb484aba0b9c2da2a82f2e #: ../src/Doc/howto/logging.rst:785 msgid "Logging Levels" msgstr "" # 5eb39eb60e0243469f227c6ec95f87f7 #: ../src/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 "" # 834fbc8785c5464c838fd17ed4d0b81a #: ../src/Doc/howto/logging.rst:794 msgid "Numeric value" msgstr "" # dcb6b28fe8d94c1dab83c0edbd5499be #: ../src/Doc/howto/logging.rst:796 msgid "50" msgstr "" # 0f41caccf66145658c1de947166b75fc #: ../src/Doc/howto/logging.rst:798 msgid "40" msgstr "" # c6cd1e2b60ff454b99bef1482ce9e795 #: ../src/Doc/howto/logging.rst:800 msgid "30" msgstr "" # 9917c837650f4f4e916edf762c564cfd #: ../src/Doc/howto/logging.rst:802 msgid "20" msgstr "" # c84fff79e6d04a518bc33786fefec845 #: ../src/Doc/howto/logging.rst:804 msgid "10" msgstr "" # 0b2fa9c4feb74c92a2deee5583527d15 #: ../src/Doc/howto/logging.rst:806 msgid "``NOTSET``" msgstr "" # eeb56da8d74c422582ee50f90cb9d538 #: ../src/Doc/howto/logging.rst:806 msgid "0" msgstr "" # 964423eac13943698a2bf905d02fe654 #: ../src/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 "" # 0cbc321734bb43808c50e72407bfb0ea #: ../src/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 "" # 2d2e60bc2e07463cb2cb3e89f4ac106b #: ../src/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 "" # af9b56f127a14d5492a0fdb672725c60 #: ../src/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 "" # f723492ad04941f2a6f069afd02c32ca #: ../src/Doc/howto/logging.rst:843 msgid "Custom Levels" msgstr "" # b7cd42e472df4fb892fedfa9a2a83ae5 #: ../src/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 "" # 69d69c10ec4e445baf2aea6bc503fc7e #: ../src/Doc/howto/logging.rst:858 msgid "Useful Handlers" msgstr "" # 2fd00f12710b466e81af49cbc9c4515d #: ../src/Doc/howto/logging.rst:860 msgid "" "In addition to the base :class:`Handler` class, many useful subclasses are " "provided:" msgstr "" # a228b422f5154a1499398d1896f80198 #: ../src/Doc/howto/logging.rst:863 msgid "" ":class:`StreamHandler` instances send messages to streams (file-like " "objects)." msgstr "" # 532f9dd537654e2f9c4f657a71953787 #: ../src/Doc/howto/logging.rst:866 msgid ":class:`FileHandler` instances send messages to disk files." msgstr "" # 8d728fda551849c3b406669e42f3b9af #: ../src/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 "" # 938eeba90f504caba5d5cfeb23069370 #: ../src/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 "" # 94d03d7628d3450f965bd18b20bee489 #: ../src/Doc/howto/logging.rst:876 msgid "" ":class:`~handlers.TimedRotatingFileHandler` instances send messages to disk " "files, rotating the log file at certain timed intervals." msgstr "" # 06aff85bf6b446d78fcfff67d28ab84b #: ../src/Doc/howto/logging.rst:879 msgid "" ":class:`~handlers.SocketHandler` instances send messages to TCP/IP sockets." msgstr "" # b9c789d471764eee9c9d388a188d1795 #: ../src/Doc/howto/logging.rst:882 msgid "" ":class:`~handlers.DatagramHandler` instances send messages to UDP sockets." msgstr "" # 1d02f34b43ff43eeaea86bf5eff2456b #: ../src/Doc/howto/logging.rst:885 msgid "" ":class:`~handlers.SMTPHandler` instances send messages to a designated email " "address." msgstr "" # 19b0df4142434452819618b44832cf47 #: ../src/Doc/howto/logging.rst:888 msgid "" ":class:`~handlers.SysLogHandler` instances send messages to a Unix syslog " "daemon, possibly on a remote machine." msgstr "" # f6b69717f7d14ebc815bcb96def03cf6 #: ../src/Doc/howto/logging.rst:891 msgid "" ":class:`~handlers.NTEventLogHandler` instances send messages to a Windows " "NT/2000/XP event log." msgstr "" # 7b86de6284574674b0d14bb239988582 #: ../src/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 "" # 404e0b6b8c95495d8909f2eecfc13f84 #: ../src/Doc/howto/logging.rst:897 msgid "" ":class:`~handlers.HTTPHandler` instances send messages to an HTTP server " "using either ``GET`` or ``POST`` semantics." msgstr "" # 488be080510b4761a23e0460199a794a #: ../src/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 "" # 698dbe7569db49dab44898fd3c0a001c #: ../src/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 "" # 31223c19657c48c6aa032b232e0e4e12 #: ../src/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 "" # 0dc46f8f9e8341de8dd0718d1c86c6a2 #: ../src/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 "" # bfa11ebc83904d19ac649f128391f80a #: ../src/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 "" # 1bdebeebd5384715847dcc87e40b06b3 #: ../src/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 "" # b0ec99179aad43e79f5aa34fa7a978d3 #: ../src/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 "" # 2a2d09c53a134db8af4f6d72ee8d28b7 #: ../src/Doc/howto/logging.rst:943 msgid "Exceptions raised during logging" msgstr "" # a35b95c61d7143b6bdbd578259deb261 #: ../src/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 "" # 0ca364320d534ad88313b9c198ce71b0 #: ../src/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 "" # b680fbe9a6b54b2e88886debc97638af #: ../src/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 "" # 82fb811028564341ac673e0ee9cbb55c #: ../src/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 "" # 6224921983d34cf6b85470aa38d9e650 #: ../src/Doc/howto/logging.rst:969 msgid "Using arbitrary objects as messages" msgstr "" # 0b6faff4c6524c19a9b2684e088d8396 #: ../src/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 "" # d0a7780ff5e449d5a2800545b0f26245 #: ../src/Doc/howto/logging.rst:982 msgid "Optimization" msgstr "" # de53b3d3c3944ed0b75fda9a512ae253 #: ../src/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 "" # a1b9f95340994142b159d89a7cab4161 #: ../src/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 "" # a2728227de8e47dfa96337245382d9cc #: ../src/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 "" # 3257dacf4c96460da8c0925e42a393fa #: ../src/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 "" # 6927c1ffb0bd42a9af7069601d10d897 #: ../src/Doc/howto/logging.rst:1014 msgid "What you don't want to collect" msgstr "" # feb4503a01104538b685a43d6af1549c #: ../src/Doc/howto/logging.rst:1014 msgid "How to avoid collecting it" msgstr "" # 212afa8e03c14f918f496827a5b7fa41 #: ../src/Doc/howto/logging.rst:1016 msgid "Information about where calls were made from." msgstr "" # 11539a1b2315485da96c7f77ce7708bf #: ../src/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 "" # 2bf0b3f20078478484040c88fb5e0c9f #: ../src/Doc/howto/logging.rst:1023 msgid "Threading information." msgstr "" # 38df13e6f6904874b224a52c41106e44 #: ../src/Doc/howto/logging.rst:1023 msgid "Set ``logging.logThreads`` to ``0``." msgstr "" # 15383c565c3f4acf82a5bfcf68f6f05d #: ../src/Doc/howto/logging.rst:1025 msgid "Process information." msgstr "" # d35805b7261b4ca0a6b55f46f6786b9a #: ../src/Doc/howto/logging.rst:1025 msgid "Set ``logging.logProcesses`` to ``0``." msgstr "" # 9ade541d83cc4d3d9a90b84faefe671c #: ../src/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 "" # 8628ef1542db410698329976abb52ef5 #: ../src/Doc/howto/logging.rst:1034 msgid "Module :mod:`logging`" msgstr "" # 4d9db3afbb294a39a785a00688797682 #: ../src/Doc/howto/logging.rst:1035 msgid "API reference for the logging module." msgstr "" # fd51fd03eddd44749cf3bc8d5f114a72 #: ../src/Doc/howto/logging.rst:1037 msgid "Module :mod:`logging.config`" msgstr "" # 306c129ce0424b7b971f4a2100cb3501 #: ../src/Doc/howto/logging.rst:1038 msgid "Configuration API for the logging module." msgstr "" # f3590e6a19494f6d96ab1a5c60cebab7 #: ../src/Doc/howto/logging.rst:1040 msgid "Module :mod:`logging.handlers`" msgstr "" # 5553cb8d8a3e4597ad14c7fcbb14c6e4 #: ../src/Doc/howto/logging.rst:1041 msgid "Useful handlers included with the logging module." msgstr "" # b89c4135f79c4a45b7542b2c6387c19c #: ../src/Doc/howto/logging.rst:1043 msgid ":ref:`A logging cookbook `" msgstr "" # 4ab08e9dadb84d4abf609ac44e482eff #: ../src/Doc/howto/logging-cookbook.rst:5 msgid "Logging Cookbook" msgstr "" # c0ce754d04814546b28147373668a703 #: ../src/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 "" # 715f427313b042e0973bfe1214fbcf86 #: ../src/Doc/howto/logging-cookbook.rst:15 msgid "Using logging in multiple modules" msgstr "" # 07be080861aa4966910120070a2bcae7 #: ../src/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 "" # ac89a0b43f9942ac8ffa73767a870b97 #: ../src/Doc/howto/logging-cookbook.rst:55 msgid "Here is the auxiliary module::" msgstr "" # 202c88ccc813452493d51d18228f4b94 #: ../src/Doc/howto/logging-cookbook.rst:74 msgid "The output looks like this::" msgstr "" # c5b3c475ae3a4e4ebfd5ccfb13dc6394 #: ../src/Doc/howto/logging-cookbook.rst:98 msgid "Multiple handlers and formatters" msgstr "" # 8e98f60b1c3c4a9f9f76545901e21e67 #: ../src/Doc/howto/logging-cookbook.rst:100 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 "" # fea5f8250df845329bae0f1b1cc578dc #: ../src/Doc/howto/logging-cookbook.rst:133 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 "" # cca0deb0ae6a4aa0b72abbdfbb0006eb #: ../src/Doc/howto/logging-cookbook.rst:136 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 "" # a5419a5385a049a48bab2d3934872bc5 #: ../src/Doc/howto/logging-cookbook.rst:147 msgid "Logging to multiple destinations" msgstr "" # 8df1e3cf14d241e5aeaaac3c052524a1 #: ../src/Doc/howto/logging-cookbook.rst:149 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 "" # 50f17ab298464b739ee8d1d4b80434de #: ../src/Doc/howto/logging-cookbook.rst:187 msgid "When you run this, on the console you will see ::" msgstr "" # 945781983dbb4309af5541d89d519d76 #: ../src/Doc/howto/logging-cookbook.rst:194 msgid "and in the file you will see something like ::" msgstr "" # c32d8934c8ec4284abb86048ee635f7c #: ../src/Doc/howto/logging-cookbook.rst:202 msgid "" "As you can see, the DEBUG message only shows up in the file. The other " "messages are sent to both destinations." msgstr "" # d13005faab0941dda60b029db228910f #: ../src/Doc/howto/logging-cookbook.rst:205 msgid "" "This example uses console and file handlers, but you can use any number and " "combination of handlers you choose." msgstr "" # 7796e09f6c204c78bc9a013ffc8401ce #: ../src/Doc/howto/logging-cookbook.rst:210 msgid "Configuration server example" msgstr "" # e845858550f041539106e414eb74d011 #: ../src/Doc/howto/logging-cookbook.rst:212 msgid "Here is an example of a module using the logging configuration server::" msgstr "" # 35eed5830c2743fcbf044db01c467208 #: ../src/Doc/howto/logging-cookbook.rst:243 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 "" # 681f1859e45c4bcc9affa678497dbaf6 #: ../src/Doc/howto/logging-cookbook.rst:268 msgid "Sending and receiving logging events across a network" msgstr "" # d83d778603ab4800a9d3e60ac154a2f6 #: ../src/Doc/howto/logging-cookbook.rst:270 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 "" # 5ef48760ffa94efe92ac5de482694d4f #: ../src/Doc/howto/logging-cookbook.rst:298 msgid "" "At the receiving end, you can set up a receiver using the :mod:" "`SocketServer` module. Here is a basic working example::" msgstr "" # 9208c8835d4445df8a4e87cd92dcaed1 #: ../src/Doc/howto/logging-cookbook.rst:386 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 "" # e0cf06bdde8c4e5b8d4b85195b1f9145 #: ../src/Doc/howto/logging-cookbook.rst:396 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 "" # 0689a8aeb6c6492388316da1cf903b3c #: ../src/Doc/howto/logging-cookbook.rst:406 msgid "Adding contextual information to your logging output" msgstr "" # c64019d055454a31a89a2b0614d09f71 #: ../src/Doc/howto/logging-cookbook.rst:410 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 "" # d0c48a121ad7479eb9f0cb55e0bf66e4 #: ../src/Doc/howto/logging-cookbook.rst:425 msgid "Using LoggerAdapters to impart contextual information" msgstr "" # 113373d919594bd09aac8b4ec00abe8d #: ../src/Doc/howto/logging-cookbook.rst:427 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 "" # e2bedc4b1f784a439d61fcff704a768b #: ../src/Doc/howto/logging-cookbook.rst:435 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 "" # 89ba6e4de18a48cd904d42f92b745531 #: ../src/Doc/howto/logging-cookbook.rst:451 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 "" # 5a612b2bcaf6472890b84ebaef1bc93a #: ../src/Doc/howto/logging-cookbook.rst:460 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 "" # 9316b95afbff4553bb1455ac8a2b4c01 #: ../src/Doc/howto/logging-cookbook.rst:476 msgid "which you can use like this::" msgstr "" # 23bc71e9663347a6988ee8708f96350d #: ../src/Doc/howto/logging-cookbook.rst:481 msgid "" "Then any events that you log to the adapter will have the value of " "``some_conn_id`` prepended to the log messages." msgstr "" # b7ab13928f994f7fb1e00f2e1ac655b6 #: ../src/Doc/howto/logging-cookbook.rst:485 msgid "Using objects other than dicts to pass contextual information" msgstr "" # e81d1bef160145c2a5a1af939bc62037 #: ../src/Doc/howto/logging-cookbook.rst:487 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 "" # b7ab13928f994f7fb1e00f2e1ac655b6 #: ../src/Doc/howto/logging-cookbook.rst:496 msgid "Using Filters to impart contextual information" msgstr "" # d2afe8ebb2704ca39c5993e9b9aa8ce8 #: ../src/Doc/howto/logging-cookbook.rst:498 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 "" # a5967f54c5a6401e8a0a73f3da93d47e #: ../src/Doc/howto/logging-cookbook.rst:503 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 "" # 9316b95afbff4553bb1455ac8a2b4c01 #: ../src/Doc/howto/logging-cookbook.rst:549 msgid "which, when run, produces something like::" msgstr "" # 4dba03e90f9e4ef1835d31b361d4947a #: ../src/Doc/howto/logging-cookbook.rst:568 msgid "Logging to a single file from multiple processes" msgstr "" # 37465a7d39014454b6a67ffb1ddf9d93 #: ../src/Doc/howto/logging-cookbook.rst:570 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 ` 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 "" # 6c93640a937f4825b71d902736677003 #: ../src/Doc/howto/logging-cookbook.rst:583 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 "" # 148f7bd8dfc74335a2ba74848ddbf233 #: ../src/Doc/howto/logging-cookbook.rst:594 msgid "Using file rotation" msgstr "" # 735c7d997b6441e189640ed352f6e9c7 #: ../src/Doc/howto/logging-cookbook.rst:599 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 "" # 3f25aaca339c4b03b5e93093dfd51cd7 #: ../src/Doc/howto/logging-cookbook.rst:631 msgid "" "The result should be 6 separate files, each with part of the log history for " "the application::" msgstr "" # dcde1ba2e5a84247819f964678e9948c #: ../src/Doc/howto/logging-cookbook.rst:641 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 "" # 7233ec1669a44294a05ce2061985a22a #: ../src/Doc/howto/logging-cookbook.rst:646 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 "" # 0a6c71c9fbdc42c6b076ace75960a935 #: ../src/Doc/howto/logging-cookbook.rst:650 msgid "An example dictionary-based configuration" msgstr "" # 98716e710eee4013b7f910bdcc805a2f #: ../src/Doc/howto/logging-cookbook.rst:652 msgid "" "Below is an example of a logging configuration dictionary - it's taken from " "the `documentation on the Django project `_. This dictionary is passed to :" "func:`~config.dictConfig` to put the configuration into effect::" msgstr "" # d6557a9605484f1db1163ee13b579a07 #: ../src/Doc/howto/logging-cookbook.rst:708 msgid "" "For more information about this configuration, you can see the `relevant " "section `_ of the Django documentation." msgstr "" # 8e06eb031f914417b9cc192f019908b0 #: ../src/Doc/howto/logging-cookbook.rst:713 msgid "Inserting a BOM into messages sent to a SysLogHandler" msgstr "" # 9005d64c4e514f45907665af78dd4e3c #: ../src/Doc/howto/logging-cookbook.rst:715 msgid "" "`RFC 5424 `_ 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 `_.)" msgstr "" # bc7217561a084ee2be1f776e926b809b #: ../src/Doc/howto/logging-cookbook.rst:721 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 "" # 45afc2aaa85d4baaab52e127881f5de2 #: ../src/Doc/howto/logging-cookbook.rst:727 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 "" # 01bc166a6b9e4f9dafd3630988f930f4 #: ../src/Doc/howto/logging-cookbook.rst:733 msgid "" "Attach a :class:`~logging.Formatter` instance to your :class:`~logging." "handlers.SysLogHandler` instance, with a format string such as::" msgstr "" # 0b13247194d7497096e313fa273bb8f9 #: ../src/Doc/howto/logging-cookbook.rst:739 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 "" # 1baa721b6f894e18924bb49539aece78 #: ../src/Doc/howto/logging-cookbook.rst:742 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 "" # 39da5b688cb34daa8d2724e58a163924 #: ../src/Doc/howto/logging-cookbook.rst:746 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 "" # 563aa68eaa3844419e017beec419601c #: ../src/Doc/howto/logging-cookbook.rst:750 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 "" # 0d8560d1498f4c6ca61453cad525e91b #: ../src/Doc/howto/logging-cookbook.rst:758 msgid "Implementing structured logging" msgstr "" # 62bce27fb80a44d484ad24911feda140 #: ../src/Doc/howto/logging-cookbook.rst:760 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 "" # d8e16a2c93764297b5221734eb03d6ea #: ../src/Doc/howto/logging-cookbook.rst:784 msgid "If the above script is run, it prints::" msgstr "" # f20b3a7bba7c4657972e45a86bbc4b45 # 9e6574c13a474001a7b68b02043c52d5 #: ../src/Doc/howto/logging-cookbook.rst:788 #: ../src/Doc/howto/logging-cookbook.rst:835 msgid "" "Note that the order of items might be different according to the version of " "Python used." msgstr "" # 4dff3c2a5e2044c6ac210738690ac934 #: ../src/Doc/howto/logging-cookbook.rst:791 msgid "" "If you need more specialised processing, you can use a custom JSON encoder, " "as in the following complete example::" msgstr "" # 1a7bdf84caba47cebdbefa1ffa3c403f #: ../src/Doc/howto/logging-cookbook.rst:831 msgid "When the above script is run, it prints::" msgstr "" # 6e3fdd33d9a34c10940b48131ca922f1 #: ../src/Doc/howto/logging-cookbook.rst:844 msgid "Customizing handlers with :func:`dictConfig`" msgstr "" # 609142a705684ef887b9188935200181 #: ../src/Doc/howto/logging-cookbook.rst:846 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 "" # 4d47d67f619645d1950fc10b4f1dc91f #: ../src/Doc/howto/logging-cookbook.rst:865 msgid "" "You can then specify, in a logging configuration passed to :func:" "`dictConfig`, that a logging handler be created by calling this function::" msgstr "" # 8c06e5cb9a48412fb00d1f1317f0077d #: ../src/Doc/howto/logging-cookbook.rst:898 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 "" # 8e3572b8a76c4f63891e3c656ade99f9 #: ../src/Doc/howto/logging-cookbook.rst:945 msgid "To run this, you will probably need to run as ``root``::" msgstr "" # 2ba20e9beb6d43e0a98da6e04a5fe42b #: ../src/Doc/howto/logging-cookbook.rst:953 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 "" # 873509a8c6204c27a0af43b25beecfe2 #: ../src/Doc/howto/logging-cookbook.rst:959 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 "" # 4e48ec9d6a6840c697af9e9831a64aa0 #: ../src/Doc/howto/logging-cookbook.rst:964 msgid "you could use e.g.::" msgstr "" # 3a82194747ae4b23b1ad1aa66af528a0 #: ../src/Doc/howto/logging-cookbook.rst:968 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 "" # 4b2d94be597545978078af2b12d62c14 #: ../src/Doc/howto/logging-cookbook.rst:973 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 "" # 08e469fef83a4330926f828d88e9ebe6 #: ../src/Doc/howto/logging-cookbook.rst:977 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 "" # 02c540aa3e87419d8a2437011c57f47b #: ../src/Doc/howto/logging-cookbook.rst:985 msgid "Configuring filters with :func:`dictConfig`" msgstr "" # a83e5f5b18094a7d9ce8f4cf4254b949 #: ../src/Doc/howto/logging-cookbook.rst:987 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 "" # 5d668e33f96f4efb95e8de2334a7e93d #: ../src/Doc/howto/logging-cookbook.rst:1040 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 "" # fbcf9986f4da445ab27f946a5bf59dcf #: ../src/Doc/howto/logging-cookbook.rst:1046 msgid "which shows that the filter is working as configured." msgstr "" # ca7822bd3451451eb53c76bb8ef104cd #: ../src/Doc/howto/logging-cookbook.rst:1048 msgid "A couple of extra points to note:" msgstr "" # 16fa4de733634057985a4b3495555a47 #: ../src/Doc/howto/logging-cookbook.rst:1050 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 "" # 9438e5f8a9ea4fa199092485ad386ee4 #: ../src/Doc/howto/logging-cookbook.rst:1057 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 "" # e836dbe15866465da83f3801b4809e39 #: ../src/Doc/howto/pyporting.rst:5 msgid "Porting Python 2 Code to Python 3" msgstr "" # fc7eaf7cb2144f37af8eeeaaecccbec0 #: ../src/Doc/howto/pyporting.rst:7 msgid "Brett Cannon" msgstr "" # 514eabc408a54e8196ff75ca1ef5faf1 #: ../src/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 "" # ae071a7dbe9c4bd2a9276020dffb59e5 #: ../src/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 "" # 73cb2b9e2b534b9ea89579783b6a07a7 #: ../src/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 "" # d2e8d2742a014dda97511dde79ee49d9 #: ../src/Doc/howto/pyporting.rst:22 msgid "" "If you prefer to read a (free) book on porting a project to Python 3, " "consider reading `Porting to Python 3`_ by Lennart Regebro which should " "cover much of what is discussed in this HOWTO." msgstr "" # 5f37e14e84c14dbbafd338935c691f7a #: ../src/Doc/howto/pyporting.rst:26 msgid "" "For help with porting, you can email the python-porting_ mailing list with " "questions." msgstr "" # 9a20b89edd7943e1a8602563008f8378 #: ../src/Doc/howto/pyporting.rst:30 msgid "The Short Version" msgstr "" # 285da7ae4c3b48148cddf61741ea59c4 #: ../src/Doc/howto/pyporting.rst:32 msgid "" "Decide what's the oldest version of Python 2 you want to support (if at all)" msgstr "" # b4846c5532134f50815fa7f947894f5d #: ../src/Doc/howto/pyporting.rst:33 msgid "" "Make sure you have a thorough test suite and use continuous integration " "testing to make sure you stay compatible with the versions of Python you " "care about" msgstr "" # e4fe3362859047d0895051e3e52a22a2 #: ../src/Doc/howto/pyporting.rst:36 msgid "" "If you have dependencies, check their Python 3 status using caniusepython3 " "(`command-line tool `__, `web " "app `__)" msgstr "" # 5407e7f6dd0e42978c07989ca030075b #: ../src/Doc/howto/pyporting.rst:40 msgid "With that done, your options are:" msgstr "" # 51f5e59aa2194c7597a6e3da783612e4 #: ../src/Doc/howto/pyporting.rst:42 msgid "" "If you are dropping Python 2 support, use :ref:`2to3 <2to3-reference>` to " "port to Python 3" msgstr "" # b9d3e51f64894b4db110d5d5f378b11c #: ../src/Doc/howto/pyporting.rst:45 msgid "" "If you are keeping Python 2 support, then start writing Python 2/3-" "compatible code starting **TODAY**" msgstr "" # 319d8d9a69a646abbde7e125f6f32d70 #: ../src/Doc/howto/pyporting.rst:48 msgid "" "If you have dependencies that have not been ported, reach out to them to " "port their project while working to make your code compatible with Python 3 " "so you're ready when your dependencies are all ported" msgstr "" # 6b6330340c974bab9420bc7286499a0b #: ../src/Doc/howto/pyporting.rst:51 msgid "" "If all your dependencies have been ported (or you have none), go ahead and " "port to Python 3" msgstr "" # 59e8f9f7a3934f71a6a6e38aa7e0818d #: ../src/Doc/howto/pyporting.rst:54 msgid "" "If you are creating a new project that wants to have 2/3 compatibility, code " "in Python 3 and then backport to Python 2" msgstr "" # cf359e67f99f47c98ffd55f73df3b547 #: ../src/Doc/howto/pyporting.rst:59 msgid "Before You Begin" msgstr "" # b585dc57f9ad48cca1da8d40562eab72 #: ../src/Doc/howto/pyporting.rst:61 msgid "" "If your project is on the Cheeseshop_/PyPI_, make sure it has the proper " "`trove classifiers`_ to signify what versions of Python it **currently** " "supports. At minimum you should specify the major version(s), e.g. " "``Programming Language :: Python :: 2`` if your project currently only " "supports Python 2. It is preferrable that you be as specific as possible by " "listing every major/minor version of Python that you support, e.g. if your " "project supports Python 2.6 and 2.7, then you want the classifiers of::" msgstr "" # 38f0ff77e0174dfbb1a443e115ebd7d0 #: ../src/Doc/howto/pyporting.rst:73 msgid "" "Once your project supports Python 3 you will want to go back and add the " "appropriate classifiers for Python 3 as well. This is important as setting " "the ``Programming Language :: Python :: 3`` classifier will lead to your " "project being listed under the `Python 3 Packages`_ section of PyPI." msgstr "" # affaf1a2cc0f471abc51dbe3030b80a3 #: ../src/Doc/howto/pyporting.rst:78 msgid "" "Make sure you have a robust test suite. You need to make sure everything " "continues to work, just like when you support a new minor/feature release of " "Python. This means making sure your test suite is thorough and is ported " "properly between Python 2 & 3 (consider using coverage_ to measure that you " "have effective test coverage). You will also most likely want to use " "something like tox_ to automate testing between all of your supported " "versions of Python. You will also want to **port your tests first** so that " "you can make sure that you detect breakage during the transition. Tests also " "tend to be simpler than the code they are testing so it gives you an idea of " "how easy it can be to port code." msgstr "" # 5effd53c2aef4e0aab8b9d929505073f #: ../src/Doc/howto/pyporting.rst:89 msgid "" "Drop support for older Python versions if possible. Python 2.5 introduced a " "lot of useful syntax and libraries which have become idiomatic in Python 3. " "Python 2.6 introduced future statements which makes compatibility much " "easier if you are going from Python 2 to 3. Python 2.7 continues the trend " "in the stdlib. Choose the newest version of Python which you believe can be " "your minimum support version and work from there." msgstr "" # 0a81a69232c744c8bddfdb39e9dee724 #: ../src/Doc/howto/pyporting.rst:97 msgid "" "Target the newest version of Python 3 that you can. Beyond just the usual " "bugfixes, compatibility has continued to improve between Python 2 and 3 as " "time has passed. E.g. Python 3.3 added back the ``u`` prefix for strings, " "making source-compatible Python code easier to write." msgstr "" # 5df91ba38d274da78f22e256b624e640 #: ../src/Doc/howto/pyporting.rst:104 msgid "Writing Source-Compatible Python 2/3 Code" msgstr "" # b384fa25c3e345f8b0ca45ee37745924 #: ../src/Doc/howto/pyporting.rst:106 msgid "" "Over the years the Python community has discovered that the easiest way to " "support both Python 2 and 3 in parallel is to write Python code that works " "in either version. While this might sound counter-intuitive at first, it " "actually is not difficult and typically only requires following some select " "(non-idiomatic) practices and using some key projects to help make bridging " "between Python 2 and 3 easier." msgstr "" # e37ea88df3114b16bbbd343df032925a #: ../src/Doc/howto/pyporting.rst:114 msgid "Projects to Consider" msgstr "" # d786edc5e71649b4a381fc625b01e595 #: ../src/Doc/howto/pyporting.rst:116 msgid "" "The lowest level library for supporting Python 2 & 3 simultaneously is six_. " "Reading through its documentation will give you an idea of where exactly the " "Python language changed between versions 2 & 3 and thus what you will want " "the library to help you continue to support." msgstr "" # 0cb34f83b81346bd8e2945291e23f36d #: ../src/Doc/howto/pyporting.rst:121 msgid "" "To help automate porting your code over to using six, you can use " "modernize_. This project will attempt to rewrite your code to be as modern " "as possible while using six to smooth out any differences between Python 2 & " "3." msgstr "" # d77300995d5546c891a7d7b9f0dfd4fe #: ../src/Doc/howto/pyporting.rst:125 msgid "" "If you want to write your compatible code to feel more like Python 3 there " "is the future_ project. It tries to provide backports of objects from Python " "3 so that you can use them from Python 2-compatible code, e.g. replacing the " "``bytes`` type from Python 2 with the one from Python 3. It also provides a " "translation script like modernize (its translation code is actually " "partially based on it) to help start working with a pre-existing code base. " "It is also unique in that its translation script will also port Python 3 " "code backwards as well as Python 2 code forwards." msgstr "" # 7978c3bcde614790b21ec2f6b3d1a13f #: ../src/Doc/howto/pyporting.rst:136 msgid "Tips & Tricks" msgstr "" # f36bf80c4a9c4e3c806fbc8f4fc8f1a9 #: ../src/Doc/howto/pyporting.rst:138 msgid "" "To help with writing source-compatible code using one of the projects " "mentioned in `Projects to Consider`_, consider following the below " "suggestions. Some of them are handled by the suggested projects, so if you " "do use one of them then read their documentation first to see which " "suggestions below will taken care of for you." msgstr "" # 0052bcd6b2e2478c814287f60a3ae01a #: ../src/Doc/howto/pyporting.rst:145 msgid "Support Python 2.7" msgstr "" # 985a47117ed94be5bb5fa2a533228a63 #: ../src/Doc/howto/pyporting.rst:147 msgid "" "As a first step, make sure that your project is compatible with Python 2.7. " "This is just good to do as Python 2.7 is the last release of Python 2 and " "thus will be used for a rather long time. It also allows for use of the " "``-3`` flag to Python to help discover places in your code where " "compatibility might be an issue (the ``-3`` flag is in Python 2.6 but Python " "2.7 adds more warnings)." msgstr "" # c325727b35694b8abd54f7a8e47a57d5 #: ../src/Doc/howto/pyporting.rst:154 msgid "Try to Support Python 2.6 and Newer Only" msgstr "" # b74674991a424c7c8bf5da770d9ff79c #: ../src/Doc/howto/pyporting.rst:156 msgid "" "While not possible for all projects, if you can support Python 2.6 and newer " "**only**, your life will be much easier. Various future statements, stdlib " "additions, etc. exist only in Python 2.6 and later which greatly assist in " "supporting Python 3. But if you project must keep support for Python 2.5 " "then it is still possible to simultaneously support Python 3." msgstr "" # 612c0ab302284a8f816f83128df1c249 #: ../src/Doc/howto/pyporting.rst:162 msgid "" "Below are the benefits you gain if you only have to support Python 2.6 and " "newer. Some of these options are personal choice while others are " "**strongly** recommended (the ones that are more for personal choice are " "labeled as such). If you continue to support older versions of Python then " "you at least need to watch out for situations that these solutions fix and " "handle them appropriately (which is where library help from e.g. six_ comes " "in handy)." msgstr "" # 9c73d37a434e4173a419bcc1c03ff471 #: ../src/Doc/howto/pyporting.rst:171 msgid "``from __future__ import print_function``" msgstr "" # 1b9862a9864c42d497839c3ae6365fe2 #: ../src/Doc/howto/pyporting.rst:173 msgid "" "It will not only get you used to typing ``print()`` as a function instead of " "a statement, but it will also give you the various benefits the function has " "over the Python 2 statement (six_ provides a function if you support Python " "2.5 or older)." msgstr "" # 655bfeeac62a4176bc66faf79a729b4c #: ../src/Doc/howto/pyporting.rst:180 msgid "``from __future__ import unicode_literals``" msgstr "" # e75ceeece51240beb2111386c53d52a0 #: ../src/Doc/howto/pyporting.rst:182 msgid "" "If you choose to use this future statement then all string literals in " "Python 2 will be assumed to be Unicode (as is already the case in Python 3). " "If you choose not to use this future statement then you should mark all of " "your text strings with a ``u`` prefix and only support Python 3.3 or newer. " "But you are **strongly** advised to do one or the other (six_ provides a " "function in case you don't want to use the future statement **and** you want " "to support Python 3.2 or older)." msgstr "" # 74a892ff88f3483bbcf3f580e9038c29 #: ../src/Doc/howto/pyporting.rst:192 msgid "Bytes/string literals" msgstr "" # c58a4daad8c4424f942f4131e351c034 #: ../src/Doc/howto/pyporting.rst:194 msgid "" "This is a **very** important one. Prefix Python 2 strings that are meant to " "contain bytes with a ``b`` prefix to very clearly delineate what is and is " "not a Python 3 text string (six_ provides a function to use for Python 2.5 " "compatibility)." msgstr "" # f5b8ec2c0c11493ea67b1ccc2991d340 #: ../src/Doc/howto/pyporting.rst:199 msgid "" "This point cannot be stressed enough: make sure you know what all of your " "string literals in Python 2 are meant to be in Python 3. Any string literal " "that should be treated as bytes should have the ``b`` prefix. Any string " "literal that should be Unicode/text in Python 2 should either have the ``u`` " "literal (supported, but ignored, in Python 3.3 and later) or you should have " "``from __future__ import unicode_literals`` at the top of the file. But the " "key point is you should know how Python 3 will treat every one one of your " "string literals and you should mark them as appropriate." msgstr "" # 94bbf631e2e7423bbad1b31e7b45b1d9 #: ../src/Doc/howto/pyporting.rst:208 msgid "" "There are some differences between byte literals in Python 2 and those in " "Python 3 thanks to the bytes type just being an alias to ``str`` in Python " "2. See the `Handle Common \"Gotchas\"`_ section for what to watch out for." msgstr "" # 0ced37ed743b44f5817b10e2f7d93168 #: ../src/Doc/howto/pyporting.rst:213 ../src/Doc/howto/pyporting.rst:226 msgid "``from __future__ import absolute_import``" msgstr "" # d796146776074d7e98730beb73fd4ba0 #: ../src/Doc/howto/pyporting.rst:214 msgid "" "Discussed in more detail below, but you should use this future statement to " "prevent yourself from accidentally using implicit relative imports." msgstr "" # 79593443c762481eb192d92e23f3fdfd #: ../src/Doc/howto/pyporting.rst:219 msgid "Supporting Python 2.5 and Newer Only" msgstr "" # 51f5e59aa2194c7597a6e3da783612e4 #: ../src/Doc/howto/pyporting.rst:221 msgid "" "If you are supporting Python 2.5 and newer there are still some features of " "Python that you can utilize." msgstr "" # 0dc36d774cc5479490e53c76800eb360 #: ../src/Doc/howto/pyporting.rst:228 msgid "" "Implicit relative imports (e.g., importing ``spam.bacon`` from within ``spam." "eggs`` with the statement ``import bacon``) do not work in Python 3. This " "future statement moves away from that and allows the use of explicit " "relative imports (e.g., ``from . import bacon``)." msgstr "" # b3304c22b27b4d119b67447aedc3f60c #: ../src/Doc/howto/pyporting.rst:233 msgid "" "In Python 2.5 you must use the __future__ statement to get to use explicit " "relative imports and prevent implicit ones. In Python 2.6 explicit relative " "imports are available without the statement, but you still want the " "__future__ statement to prevent implicit relative imports. In Python 2.7 the " "__future__ statement is not needed. In other words, unless you are only " "supporting Python 2.7 or a version earlier than Python 2.5, use this " "__future__ statement." msgstr "" # 8974b6ce3fad41d2ab1b6b57db2feb86 #: ../src/Doc/howto/pyporting.rst:243 msgid "Mark all Unicode strings with a ``u`` prefix" msgstr "" # 05431ce1a29d4c67b174c103cecca755 #: ../src/Doc/howto/pyporting.rst:245 msgid "" "While Python 2.6 has a ``__future__`` statement to automatically cause " "Python 2 to treat all string literals as Unicode, Python 2.5 does not have " "that shortcut. This means you should go through and mark all string literals " "with a ``u`` prefix to turn them explicitly into text strings where " "appropriate and only support Python 3.3 or newer. Otherwise use a project " "like six_ which provides a function to pass all text string literals through." msgstr "" # 32a99b7cbf164be4ad3367e48a71cd4b #: ../src/Doc/howto/pyporting.rst:254 msgid "Capturing the Currently Raised Exception" msgstr "" # 6ffae18c38384a09ab36f80f1be22f37 #: ../src/Doc/howto/pyporting.rst:256 msgid "" "In Python 2.5 and earlier the syntax to access the current exception is::" msgstr "" # 4ea5928ecf4b48fd9a76a7518a445cb3 #: ../src/Doc/howto/pyporting.rst:264 msgid "" "This syntax changed in Python 3 (and backported to Python 2.6 and later) to::" msgstr "" # 6ffae18c38384a09ab36f80f1be22f37 #: ../src/Doc/howto/pyporting.rst:274 msgid "" "Because of this syntax change you must change how you capture the current " "exception in Python 2.5 and earlier to::" msgstr "" # 9135a918d99846b6b2f07acb4481dfe2 #: ../src/Doc/howto/pyporting.rst:285 msgid "" "You can get more information about the raised exception from :func:`sys." "exc_info` than simply the current exception instance, but you most likely " "don't need it." msgstr "" # 8808a5e91dc24b4e941fb94ce386d32a #: ../src/Doc/howto/pyporting.rst:290 msgid "" "In Python 3, the traceback is attached to the exception instance through the " "``__traceback__`` attribute. If the instance is saved in a local variable " "that persists outside of the ``except`` block, the traceback will create a " "reference cycle with the current frame and its dictionary of local " "variables. This will delay reclaiming dead resources until the next cyclic :" "term:`garbage collection` pass." msgstr "" # d4505a6c83924f2989209021f7aaa4fe #: ../src/Doc/howto/pyporting.rst:297 msgid "" "In Python 2, this problem only occurs if you save the traceback itself (e.g. " "the third element of the tuple returned by :func:`sys.exc_info`) in a " "variable." msgstr "" # 4cd3379c765e492f8d8250e3e9f903a3 #: ../src/Doc/howto/pyporting.rst:303 msgid "Handle Common \"Gotchas\"" msgstr "" # f53c6990a50b4eebb1d40264e83fe9c7 #: ../src/Doc/howto/pyporting.rst:305 msgid "" "These are things to watch out for no matter what version of Python 2 you are " "supporting which are not syntactic considerations." msgstr "" # ab3034ec5e5e4661aa6de68ce95d5078 #: ../src/Doc/howto/pyporting.rst:310 msgid "``from __future__ import division``" msgstr "" # df60a68b4f7f40b6b7f104d17e5580c7 #: ../src/Doc/howto/pyporting.rst:312 msgid "" "While the exact same outcome can be had by using the ``-Qnew`` argument to " "Python, using this future statement lifts the requirement that your users " "use the flag to get the expected behavior of division in Python 3 (e.g., " "``1/2 == 0.5; 1//2 == 0``)." msgstr "" # e46aa5d4215a4df48231102107237eca #: ../src/Doc/howto/pyporting.rst:320 msgid "Specify when opening a file as binary" msgstr "" # 4f4aa2633f3f4b6aad2be8d04871966e #: ../src/Doc/howto/pyporting.rst:322 msgid "" "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 to read and/or write bytes data) or text " "access (allowing to read and/or write unicode data)." msgstr "" # b9a34cc2e1e046f6b406152ab3d19b72 #: ../src/Doc/howto/pyporting.rst:331 msgid "Text files" msgstr "" # e6361ba1d9af424e8db34faac2b9d9c9 #: ../src/Doc/howto/pyporting.rst:333 msgid "" "Text files created using ``open()`` under Python 2 return byte strings, " "while under Python 3 they return unicode strings. Depending on your porting " "strategy, this can be an issue." msgstr "" # b34c508e7d0442749c5e4a8b88d1fb75 #: ../src/Doc/howto/pyporting.rst:337 msgid "" "If you want text files to return unicode strings in Python 2, you have two " "possibilities:" msgstr "" # fcf0d560b43f481daa22ceda2edd9d35 #: ../src/Doc/howto/pyporting.rst:340 msgid "" "Under Python 2.6 and higher, use :func:`io.open`. Since :func:`io.open` is " "essentially the same function in both Python 2 and Python 3, it will help " "iron out any issues that might arise." msgstr "" # 97c9151f55c44cc581dec6e8f5f66307 #: ../src/Doc/howto/pyporting.rst:344 msgid "" "If pre-2.6 compatibility is needed, then you should use :func:`codecs.open` " "instead. This will make sure that you get back unicode strings in Python 2." msgstr "" # 67ef437384224cfd950b9e37f12550f9 #: ../src/Doc/howto/pyporting.rst:348 msgid "Subclass ``object``" msgstr "" # fb4d1cff09334961b99df7bfb1560b12 #: ../src/Doc/howto/pyporting.rst:350 msgid "" "New-style classes have been around since Python 2.2. You need to make sure " "you are subclassing from ``object`` to avoid odd edge cases involving method " "resolution order, etc. This continues to be totally valid in Python 3 " "(although unneeded as all classes implicitly inherit from ``object``)." msgstr "" # 13de8b799eb24005bd09daddfa10bbc9 #: ../src/Doc/howto/pyporting.rst:357 msgid "Deal With the Bytes/String Dichotomy" msgstr "" # 191015c1e13e4492b79d44cfb05f2ea9 #: ../src/Doc/howto/pyporting.rst:359 msgid "" "One of the biggest issues people have when porting code to Python 3 is " "handling the bytes/string dichotomy. Because Python 2 allowed the ``str`` " "type to hold textual data, people have over the years been rather loose in " "their delineation of what ``str`` instances held text compared to bytes. In " "Python 3 you cannot be so care-free anymore and need to properly handle the " "difference. The key to handling this issue is to make sure that **every** " "string literal in your Python 2 code is either syntactically or functionally " "marked as either bytes or text data. After this is done you then need to " "make sure your APIs are designed to either handle a specific type or made to " "be properly polymorphic." msgstr "" # 33a55a2846b649d0a5d4ba31885156c1 #: ../src/Doc/howto/pyporting.rst:371 msgid "Mark Up Python 2 String Literals" msgstr "" # 99d1b07e9b704affb160beb8889d7536 #: ../src/Doc/howto/pyporting.rst:373 msgid "" "First thing you must do is designate every single string literal in Python 2 " "as either textual or bytes data. If you are only supporting Python 2.6 or " "newer, this can be accomplished by marking bytes literals with a ``b`` " "prefix and then designating textual data with a ``u`` prefix or using the " "``unicode_literals`` future statement." msgstr "" # 942e68067a7248a197ebb9316b94751c #: ../src/Doc/howto/pyporting.rst:379 msgid "" "If your project supports versions of Python predating 2.6, then you should " "use the six_ project and its ``b()`` function to denote bytes literals. For " "text literals you can either use six's ``u()`` function or use a ``u`` " "prefix." msgstr "" # 210012be5cb54681b011ae64027b2287 #: ../src/Doc/howto/pyporting.rst:385 msgid "Decide what APIs Will Accept" msgstr "" # 994241dfdfcf40848a5e9da2800ca105 #: ../src/Doc/howto/pyporting.rst:387 msgid "" "In Python 2 it was very easy to accidentally create an API that accepted " "both bytes and textual data. But in Python 3, thanks to the more strict " "handling of disparate types, this loose usage of bytes and text together " "tends to fail." msgstr "" # 7f4384ba7a6d4c618c062ec6194867fd #: ../src/Doc/howto/pyporting.rst:391 msgid "" "Take the dict ``{b'a': 'bytes', u'a': 'text'}`` in Python 2.6. It creates " "the dict ``{u'a': 'text'}`` since ``b'a' == u'a'``. But in Python 3 the " "equivalent dict creates ``{b'a': 'bytes', 'a': 'text'}``, i.e., no lost " "data. Similar issues can crop up when transitioning Python 2 code to Python " "3." msgstr "" # af331f899ccf451db1b01b2a83b5b6f1 #: ../src/Doc/howto/pyporting.rst:396 msgid "" "This means you need to choose what an API is going to accept and create and " "consistently stick to that API in both Python 2 and 3." msgstr "" # 0d339def3215422fa9f8c0ff8e20da62 #: ../src/Doc/howto/pyporting.rst:401 msgid "Bytes / Unicode Comparison" msgstr "" # af8b53a10767414ea892732f5d7e394f #: ../src/Doc/howto/pyporting.rst:403 msgid "" "In Python 3, mixing bytes and unicode is forbidden in most situations; it " "will raise a :class:`TypeError` where Python 2 would have attempted an " "implicit coercion between types. However, there is one case where it " "doesn't and it can be very misleading::" msgstr "" # f4117ff439c74fd4805675c5f516e1ae #: ../src/Doc/howto/pyporting.rst:411 msgid "" "This is because an equality comparison is required by the language to always " "succeed (and return ``False`` for incompatible types). However, this also " "means that code incorrectly ported to Python 3 can display buggy behaviour " "if such comparisons are silently executed. To detect such situations, " "Python 3 has a ``-b`` flag that will display a warning::" msgstr "" # 7dd10ede04f64754ac4bc90ca6e1e864 #: ../src/Doc/howto/pyporting.rst:422 msgid "To turn the warning into an exception, use the ``-bb`` flag instead::" msgstr "" # cbfbb174ee164217935dc50ca49a64d5 #: ../src/Doc/howto/pyporting.rst:432 msgid "Indexing bytes objects" msgstr "" # 073990d932f441d4ad77df12577cff82 #: ../src/Doc/howto/pyporting.rst:434 msgid "" "Another potentially surprising change is the indexing behaviour of bytes " "objects in Python 3::" msgstr "" # ab390883aefd413e87f5a68abfbbbe38 #: ../src/Doc/howto/pyporting.rst:440 msgid "" "Indeed, Python 3 bytes objects (as well as :class:`bytearray` objects) are " "sequences of integers. But code converted from Python 2 will often assume " "that indexing a bytestring produces another bytestring, not an integer. To " "reconcile both behaviours, use slicing::" msgstr "" # 44b2eb374c5a4a82a8ba4bbf3cbe4d9a #: ../src/Doc/howto/pyporting.rst:451 msgid "" "The only remaining gotcha is that an out-of-bounds slice returns an empty " "bytes object instead of raising ``IndexError``:" msgstr "" # aaa226ca491249469d358a77d231d0ae #: ../src/Doc/howto/pyporting.rst:463 msgid "``__str__()``/``__unicode__()``" msgstr "" # c9111443666d4689975684fdc8cdd9e4 #: ../src/Doc/howto/pyporting.rst:465 msgid "" "In Python 2, objects can specify both a string and unicode representation of " "themselves. In Python 3, though, there is only a string representation. This " "becomes an issue as people can inadvertently do things in their " "``__str__()`` methods which have unpredictable results (e.g., infinite " "recursion if you happen to use the ``unicode(self).encode('utf8')`` idiom as " "the body of your ``__str__()`` method)." msgstr "" # d16d61b49c8841f4934c8ece3fc7b2c6 #: ../src/Doc/howto/pyporting.rst:472 msgid "" "You can use a mixin class to work around this. This allows you to only " "define a ``__unicode__()`` method for your class and let the mixin derive " "``__str__()`` for you (code from http://lucumr.pocoo.org/2011/1/22/forwards-" "compatible-python/)::" msgstr "" # c3ac65b738b748fe8c0e5213bda611e8 #: ../src/Doc/howto/pyporting.rst:499 msgid "Don't Index on Exceptions" msgstr "" # 2c607128d18c42958bf810f4e4a5c972 #: ../src/Doc/howto/pyporting.rst:501 msgid "In Python 2, the following worked::" msgstr "" # faa974825eb34be3bb9b4ed2d0bd2bef #: ../src/Doc/howto/pyporting.rst:509 msgid "" "But in Python 3, indexing directly on an exception is an error. You need to " "make sure to only index on the :attr:`BaseException.args` attribute which is " "a sequence containing all arguments passed to the :meth:`__init__` method." msgstr "" # 9adee86971bc42bbb34c2f8e72ed6648 #: ../src/Doc/howto/pyporting.rst:513 msgid "Even better is to use the documented attributes the exception provides." msgstr "" # 5702d4995aa743f2a385918b5e8e4272 #: ../src/Doc/howto/pyporting.rst:517 msgid "Don't use ``__getslice__`` & Friends" msgstr "" # 627edb2d8eea4c0bac4d069d06a4e91b #: ../src/Doc/howto/pyporting.rst:519 msgid "" "Been deprecated for a while, but Python 3 finally drops support for " "``__getslice__()``, etc. Move completely over to :meth:`__getitem__` and " "friends." msgstr "" # 450a06164a3444c9bf70aabcbd3e858b #: ../src/Doc/howto/pyporting.rst:525 msgid "Updating doctests" msgstr "" # 615328515a964a6cb279596b93b8f86d #: ../src/Doc/howto/pyporting.rst:527 msgid "" "Don't forget to make them Python 2/3 compatible as well. If you wrote a " "monolithic set of doctests (e.g., a single docstring containing all of your " "doctests), you should at least consider breaking the doctests up into " "smaller pieces to make it more manageable to fix. Otherwise it might very " "well be worth your time and effort to port your tests to :mod:`unittest`." msgstr "" # 9499659a065a4586a941a8e82d2bd6e6 #: ../src/Doc/howto/pyporting.rst:535 msgid "Update ``map`` for imbalanced input sequences" msgstr "" # 3bd8bf9c76a04ac9a52a38e3d4ccf522 #: ../src/Doc/howto/pyporting.rst:537 msgid "" "With Python 2, when ``map`` was given more than one input sequence it would " "pad the shorter sequences with ``None`` values, returning a sequence as long " "as the longest input sequence." msgstr "" # 670b1756521f4df18011f44916cb36fb #: ../src/Doc/howto/pyporting.rst:541 msgid "" "With Python 3, if the input sequences to ``map`` are of unequal length, " "``map`` will stop at the termination of the shortest of the sequences. For " "full compatibility with ``map`` from Python 2.x, wrap the sequence arguments " "in :func:`itertools.zip_longest`, e.g. ``map(func, *sequences)`` becomes " "``list(map(func, itertools.zip_longest(*sequences)))``." msgstr "" # b7ad2dfc09b946febf0368a4396b6e9e #: ../src/Doc/howto/pyporting.rst:548 msgid "Eliminate ``-3`` Warnings" msgstr "" # e582ca87c66549e9b12b2ddd4c770c3d #: ../src/Doc/howto/pyporting.rst:550 msgid "" "When you run your application's test suite, run it using the ``-3`` flag " "passed to Python. This will cause various warnings to be raised during " "execution about things that are semantic changes between Python 2 and 3. Try " "to eliminate those warnings to make your code even more portable to Python 3." msgstr "" # d09b14bd9c8b44958479a0bb9f05edca #: ../src/Doc/howto/pyporting.rst:557 msgid "Alternative Approaches" msgstr "" # dc892403cd044103ae82edb543c6a460 #: ../src/Doc/howto/pyporting.rst:559 msgid "" "While supporting Python 2 & 3 simultaneously is typically the preferred " "choice by people so that they can continue to improve code and have it work " "for the most number of users, your life may be easier if you only have to " "support one major version of Python going forward." msgstr "" # 0d0556a0631c48be938d2d8c2c9cc1df #: ../src/Doc/howto/pyporting.rst:565 msgid "Supporting Only Python 3 Going Forward From Python 2 Code" msgstr "" # 6d6fec7e753d4057b96c5a3d6d4178a9 #: ../src/Doc/howto/pyporting.rst:567 msgid "" "If you have Python 2 code but going forward only want to improve it as " "Python 3 code, then you can use 2to3_ to translate your Python 2 code to " "Python 3 code. This is only recommended, though, if your current version of " "your project is going into maintenance mode and you want all new features to " "be exclusive to Python 3." msgstr "" # a1a6ce0d6c02428eb912de02e38671d2 #: ../src/Doc/howto/pyporting.rst:575 msgid "Backporting Python 3 code to Python 2" msgstr "" # 53d0bbf2f18e405093b1768fe6759141 #: ../src/Doc/howto/pyporting.rst:577 msgid "" "If you have Python 3 code and have little interest in supporting Python 2 " "you can use 3to2_ to translate from Python 3 code to Python 2 code. This is " "only recommended if you don't plan to heavily support Python 2 users. " "Otherwise write your code for Python 3 and then backport as far back as you " "want. This is typically easier than going from Python 2 to 3 as you will " "have worked out any difficulties with e.g. bytes/strings, etc." msgstr "" # 4cceebf107a046e2850ba987f30e3b95 #: ../src/Doc/howto/pyporting.rst:586 msgid "Other Resources" msgstr "" # 6655928ffc2e4042a658bb55194bf3a0 #: ../src/Doc/howto/pyporting.rst:588 msgid "" "The authors of the following blog posts, wiki pages, and books deserve " "special thanks for making public their tips for porting Python 2 code to " "Python 3 (and thus helping provide information for this document and its " "various revisions over the years):" msgstr "" # 9db73da4a9584ab2981fa6d70077380b #: ../src/Doc/howto/pyporting.rst:593 msgid "https://wiki.python.org/moin/PortingPythonToPy3k" msgstr "" # 2ac7fa2afb1243a8b7cb24b692af8bbf #: ../src/Doc/howto/pyporting.rst:594 msgid "http://python3porting.com/" msgstr "" # fa3f5ab95f6340099a39df758243df01 #: ../src/Doc/howto/pyporting.rst:595 msgid "http://docs.pythonsprints.com/python3_porting/py-porting.html" msgstr "" # 7398b09a284d4dd983d7b2114154be6a #: ../src/Doc/howto/pyporting.rst:596 msgid "" "http://techspot.zzzeek.org/2011/01/24/zzzeek-s-guide-to-python-3-porting/" msgstr "" # ea7e371504e541e2b1514f85d1cb0fa1 #: ../src/Doc/howto/pyporting.rst:597 msgid "" "http://dabeaz.blogspot.com/2011/01/porting-py65-and-my-superboard-to.html" msgstr "" # 3e267d8b581943ada40d1a90d620285a #: ../src/Doc/howto/pyporting.rst:598 msgid "http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/" msgstr "" # 15e7c37ed1ae499b9ccdc23e45de02d3 #: ../src/Doc/howto/pyporting.rst:599 msgid "http://lucumr.pocoo.org/2010/2/11/porting-to-python-3-a-guide/" msgstr "" # 16f120124a3f4b0db197cf510f10c05b #: ../src/Doc/howto/pyporting.rst:600 msgid "https://wiki.ubuntu.com/Python/3" msgstr "" # 7cbcdce375074e9f8895d6fb39c1dbbf #: ../src/Doc/howto/pyporting.rst:602 msgid "" "If you feel there is something missing from this document that should be " "added, please email the python-porting_ mailing list." msgstr "" #: ../src/Doc/howto/regex.rst:5 msgid "Regular Expression HOWTO" msgstr "" #: ../src/Doc/howto/regex.rst:7 msgid "A.M. Kuchling " msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:56 msgid "Simple Patterns" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:68 msgid "Matching Characters" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # f2e1f4c7319f45fa975e980cf3295fa7 #: ../src/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 `." msgstr "" # 5c1e2667294f4772aad7eca567461998 #: ../src/Doc/howto/regex.rst:120 msgid "``\\d``" msgstr "" #: ../src/Doc/howto/regex.rst:121 msgid "Matches any decimal digit; this is equivalent to the class ``[0-9]``." msgstr "" # 3279bdfdd76d45dcbf3f0cb72dfd2559 #: ../src/Doc/howto/regex.rst:123 msgid "``\\D``" msgstr "" #: ../src/Doc/howto/regex.rst:124 msgid "" "Matches any non-digit character; this is equivalent to the class ``[^0-9]``." msgstr "" # 452c0eb3f4624ff5a54602cf5d843274 #: ../src/Doc/howto/regex.rst:127 msgid "``\\s``" msgstr "" #: ../src/Doc/howto/regex.rst:127 msgid "" "Matches any whitespace character; this is equivalent to the class ``[ \\t\\n" "\\r\\f\\v]``." msgstr "" # fa8217a70bdd491f895d3415da38c6b0 #: ../src/Doc/howto/regex.rst:131 msgid "``\\S``" msgstr "" #: ../src/Doc/howto/regex.rst:131 msgid "" "Matches any non-whitespace character; this is equivalent to the class ``[^ " "\\t\\n\\r\\f\\v]``." msgstr "" # 7e91aa755b5842cc816e4183fcdd929e #: ../src/Doc/howto/regex.rst:135 msgid "``\\w``" msgstr "" #: ../src/Doc/howto/regex.rst:135 msgid "" "Matches any alphanumeric character; this is equivalent to the class ``[a-zA-" "Z0-9_]``." msgstr "" # c7c443df2084432f9938aaaf39f93f88 #: ../src/Doc/howto/regex.rst:139 msgid "``\\W``" msgstr "" #: ../src/Doc/howto/regex.rst:139 msgid "" "Matches any non-alphanumeric character; this is equivalent to the class " "``[^a-zA-Z0-9_]``." msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:153 msgid "Repeating Things" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 few repetitions." msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:183 msgid "Step" msgstr "" #: ../src/Doc/howto/regex.rst:183 msgid "Matched" msgstr "" #: ../src/Doc/howto/regex.rst:183 msgid "Explanation" msgstr "" #: ../src/Doc/howto/regex.rst:185 msgid "1" msgstr "" #: ../src/Doc/howto/regex.rst:185 msgid "``a``" msgstr "" #: ../src/Doc/howto/regex.rst:185 msgid "The ``a`` in the RE matches." msgstr "" #: ../src/Doc/howto/regex.rst:187 msgid "2" msgstr "" #: ../src/Doc/howto/regex.rst:187 msgid "``abcbd``" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:191 msgid "3" msgstr "" #: ../src/Doc/howto/regex.rst:191 ../src/Doc/howto/regex.rst:199 msgid "*Failure*" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:196 msgid "4" msgstr "" #: ../src/Doc/howto/regex.rst:196 ../src/Doc/howto/regex.rst:207 msgid "``abcb``" msgstr "" #: ../src/Doc/howto/regex.rst:196 msgid "Back up, so that ``[bcd]*`` matches one less character." msgstr "" #: ../src/Doc/howto/regex.rst:199 msgid "5" msgstr "" #: ../src/Doc/howto/regex.rst:199 msgid "" "Try ``b`` again, but the current position is at the last character, which is " "a ``'d'``." msgstr "" #: ../src/Doc/howto/regex.rst:203 ../src/Doc/howto/regex.rst:207 msgid "6" msgstr "" #: ../src/Doc/howto/regex.rst:203 msgid "``abc``" msgstr "" #: ../src/Doc/howto/regex.rst:203 msgid "Back up again, so that ``[bcd]*`` is only matching ``bc``." msgstr "" #: ../src/Doc/howto/regex.rst:207 msgid "" "Try ``b`` again. This time the character at the current position is " "``'b'``, so it succeeds." msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:251 msgid "Using Regular Expressions" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:260 msgid "Compiling Regular Expressions" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:289 msgid "The Backslash Plague" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:305 msgid "Characters" msgstr "" #: ../src/Doc/howto/regex.rst:305 msgid "Stage" msgstr "" #: ../src/Doc/howto/regex.rst:307 msgid "``\\section``" msgstr "" #: ../src/Doc/howto/regex.rst:307 msgid "Text string to be matched" msgstr "" #: ../src/Doc/howto/regex.rst:309 msgid "``\\\\section``" msgstr "" #: ../src/Doc/howto/regex.rst:309 msgid "Escaped backslash for :func:`re.compile`" msgstr "" #: ../src/Doc/howto/regex.rst:311 ../src/Doc/howto/regex.rst:331 msgid "``\"\\\\\\\\section\"``" msgstr "" #: ../src/Doc/howto/regex.rst:311 msgid "Escaped backslashes for a string literal" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:327 msgid "Regular String" msgstr "" #: ../src/Doc/howto/regex.rst:327 msgid "Raw string" msgstr "" #: ../src/Doc/howto/regex.rst:329 msgid "``\"ab*\"``" msgstr "" #: ../src/Doc/howto/regex.rst:329 msgid "``r\"ab*\"``" msgstr "" #: ../src/Doc/howto/regex.rst:331 msgid "``r\"\\\\section\"``" msgstr "" #: ../src/Doc/howto/regex.rst:333 msgid "``\"\\\\w+\\\\s+\\\\1\"``" msgstr "" #: ../src/Doc/howto/regex.rst:333 msgid "``r\"\\w+\\s+\\1\"``" msgstr "" #: ../src/Doc/howto/regex.rst:338 msgid "Performing Matches" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:346 ../src/Doc/howto/regex.rst:407 #: ../src/Doc/howto/regex.rst:1039 msgid "Method/Attribute" msgstr "" #: ../src/Doc/howto/regex.rst:346 ../src/Doc/howto/regex.rst:407 #: ../src/Doc/howto/regex.rst:1039 msgid "Purpose" msgstr "" #: ../src/Doc/howto/regex.rst:348 msgid "``match()``" msgstr "" #: ../src/Doc/howto/regex.rst:348 msgid "Determine if the RE matches at the beginning of the string." msgstr "" #: ../src/Doc/howto/regex.rst:351 msgid "``search()``" msgstr "" #: ../src/Doc/howto/regex.rst:351 msgid "Scan through a string, looking for any location where this RE matches." msgstr "" #: ../src/Doc/howto/regex.rst:354 msgid "``findall()``" msgstr "" #: ../src/Doc/howto/regex.rst:354 msgid "Find all substrings where the RE matches, and returns them as a list." msgstr "" #: ../src/Doc/howto/regex.rst:357 msgid "``finditer()``" msgstr "" #: ../src/Doc/howto/regex.rst:357 msgid "" "Find all substrings where the RE matches, and returns them as an :term:" "`iterator`." msgstr "" # 0d281a82f3404c6bb56bbd844f743e7b #: ../src/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 ` instance is " "returned, containing information about the match: where it starts and ends, " "the substring it matched, and more." msgstr "" # 74da702c244b4300899078eb444a0158 #: ../src/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 `_ is also an interactive tool for developing and testing RE patterns." msgstr "" #: ../src/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 "" #: ../src/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 "" # a906fbd0f61444e6a0ec93146755384f #: ../src/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 `, " "so you should store the result in a variable for later use. ::" msgstr "" # 24750054c21e41ea81d85bee3f24e50b #: ../src/Doc/howto/regex.rst:402 msgid "" "Now you can query the :ref:`match object ` for information " "about the matching string. :ref:`match object ` instances " "also have several methods and attributes; the most important ones are:" msgstr "" #: ../src/Doc/howto/regex.rst:409 msgid "``group()``" msgstr "" #: ../src/Doc/howto/regex.rst:409 msgid "Return the string matched by the RE" msgstr "" #: ../src/Doc/howto/regex.rst:411 msgid "``start()``" msgstr "" #: ../src/Doc/howto/regex.rst:411 msgid "Return the starting position of the match" msgstr "" #: ../src/Doc/howto/regex.rst:413 msgid "``end()``" msgstr "" #: ../src/Doc/howto/regex.rst:413 msgid "Return the ending position of the match" msgstr "" #: ../src/Doc/howto/regex.rst:415 msgid "``span()``" msgstr "" #: ../src/Doc/howto/regex.rst:415 msgid "Return a tuple containing the (start, end) positions of the match" msgstr "" #: ../src/Doc/howto/regex.rst:419 msgid "Trying these methods will soon clarify their meaning::" msgstr "" #: ../src/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 "" # f8573c9beacf4f32b2a8fa80a1df355f #: ../src/Doc/howto/regex.rst:445 msgid "" "In actual programs, the most common style is to store the :ref:`match object " "` in a variable, and then check if it was ``None``. This " "usually looks like::" msgstr "" #: ../src/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 "" # 7eee9e17bebb4be998acab26a6fcfcbf #: ../src/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 ` instances as an :term:`iterator`. [#]_ ::" msgstr "" #: ../src/Doc/howto/regex.rst:479 msgid "Module-Level Functions" msgstr "" # 22f4aed7d8f049308dbb7ff4a8694a3c #: ../src/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 ` instance. ::" msgstr "" #: ../src/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 "" # 0a8b1c5cbbe04e9f86397b02d7e20de5 #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:517 msgid "Compilation Flags" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:527 msgid "" "Here's a table of the available flags, followed by a more detailed " "explanation of each one." msgstr "" #: ../src/Doc/howto/regex.rst:531 msgid "Flag" msgstr "" #: ../src/Doc/howto/regex.rst:531 msgid "Meaning" msgstr "" #: ../src/Doc/howto/regex.rst:533 msgid ":const:`DOTALL`, :const:`S`" msgstr "" #: ../src/Doc/howto/regex.rst:533 msgid "Make ``.`` match any character, including newlines" msgstr "" #: ../src/Doc/howto/regex.rst:536 msgid ":const:`IGNORECASE`, :const:`I`" msgstr "" #: ../src/Doc/howto/regex.rst:536 msgid "Do case-insensitive matches" msgstr "" #: ../src/Doc/howto/regex.rst:538 msgid ":const:`LOCALE`, :const:`L`" msgstr "" #: ../src/Doc/howto/regex.rst:538 msgid "Do a locale-aware match" msgstr "" #: ../src/Doc/howto/regex.rst:540 msgid ":const:`MULTILINE`, :const:`M`" msgstr "" #: ../src/Doc/howto/regex.rst:540 msgid "Multi-line matching, affecting ``^`` and ``$``" msgstr "" #: ../src/Doc/howto/regex.rst:543 msgid ":const:`VERBOSE`, :const:`X`" msgstr "" #: ../src/Doc/howto/regex.rst:543 msgid "" "Enable verbose REs, which can be organized more cleanly and understandably." msgstr "" # a9036e47c09740f1931da0c0449c79db #: ../src/Doc/howto/regex.rst:546 msgid ":const:`UNICODE`, :const:`U`" msgstr "" # df4dea7623334be188ee5357b0905f15 #: ../src/Doc/howto/regex.rst:546 msgid "" "Makes several escapes like ``\\w``, ``\\b``, ``\\s`` and ``\\d`` dependent " "on the Unicode character database." msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:567 msgid "" "Make ``\\w``, ``\\W``, ``\\b``, and ``\\B``, dependent on the current locale." msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:584 msgid "" "(``^`` and ``$`` haven't been explained yet; they'll be introduced in " "section :ref:`more-metacharacters`.)" msgstr "" #: ../src/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 "" #: ../src/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 "" # 409a3eff81934d09ad4bc56af2b1fd64 #: ../src/Doc/howto/regex.rst:608 msgid "" "Make ``\\w``, ``\\W``, ``\\b``, ``\\B``, ``\\d``, ``\\D``, ``\\s`` and ``" "\\S`` dependent on the Unicode character properties database." msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:638 msgid "Without the verbose setting, the RE would look like this::" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:650 msgid "More Pattern Power" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:660 msgid "More Metacharacters" msgstr "" #: ../src/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 "" #: ../src/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 "" # 5ec08fab486b4b859b146ac043f515a9 #: ../src/Doc/howto/regex.rst:680 msgid "``|``" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:680 msgid "" "To match a literal ``'|'``, use ``\\|``, or enclose it inside a character " "class, as in ``[|]``." msgstr "" # 7c7f6b7877b8411c8f2e906d99ea9663 #: ../src/Doc/howto/regex.rst:696 msgid "``^``" msgstr "" #: ../src/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 "" #: ../src/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 "" # 6dd13735dce1481db2415e7305f152ac #: ../src/Doc/howto/regex.rst:710 msgid "``$``" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:710 msgid "" "To match a literal ``'$'``, use ``\\$`` or enclose it inside a character " "class, as in ``[$]``." msgstr "" # 8355a4f6a25b405694a24af43ef0dfa1 #: ../src/Doc/howto/regex.rst:716 msgid "``\\A``" msgstr "" #: ../src/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 "" # 702918f54b794e869e82de9b667c1ce9 #: ../src/Doc/howto/regex.rst:719 msgid "``\\Z``" msgstr "" #: ../src/Doc/howto/regex.rst:720 msgid "Matches only at the end of the string." msgstr "" # c8602ee0ca0b40e486f4490d57f31980 #: ../src/Doc/howto/regex.rst:754 msgid "``\\b``" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # fbcb300e4fe542b1b2069f1bb4352898 #: ../src/Doc/howto/regex.rst:759 msgid "``\\B``" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:763 msgid "Grouping" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # 16373d7bac57435c9c5b96f28ed6a800 #: ../src/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 ` 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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:839 msgid "For example, the following RE detects doubled words in a string. ::" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:851 msgid "Non-capturing and Named Groups" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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...)`` 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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # cb2e6d565ea44b56a717ace23863bba8 #: ../src/Doc/howto/regex.rst:914 msgid "" "The syntax for a named group is one of the Python-specific extensions: ``(?" "P...)``. *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 ` 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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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\\b\\w+)\\s+(?" "P=word)``::" msgstr "" #: ../src/Doc/howto/regex.rst:956 msgid "Lookahead Assertions" msgstr "" #: ../src/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 "" # d9b3399647fd442d9bbf898c7385bc34 #: ../src/Doc/howto/regex.rst:965 msgid "``(?=...)``" msgstr "" #: ../src/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 "" # 2933d119182340a49ce28e51fac5d737 #: ../src/Doc/howto/regex.rst:970 msgid "``(?!...)``" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:978 msgid "The pattern to match this is quite simple:" msgstr "" #: ../src/Doc/howto/regex.rst:980 msgid "``.*[.].*$``" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:995 msgid "``.*[.]([^b]..|.[^a].|..[^t])$``" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:1005 msgid "``.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$``" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/regex.rst:1016 msgid "A negative lookahead cuts through all this confusion:" msgstr "" #: ../src/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." msgstr "" #: ../src/Doc/howto/regex.rst:1024 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 "" #: ../src/Doc/howto/regex.rst:1028 msgid "``.*[.](?!bat$|exe$).*$``" msgstr "" #: ../src/Doc/howto/regex.rst:1032 msgid "Modifying Strings" msgstr "" #: ../src/Doc/howto/regex.rst:1034 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 "" #: ../src/Doc/howto/regex.rst:1041 msgid "``split()``" msgstr "" #: ../src/Doc/howto/regex.rst:1041 msgid "Split the string into a list, splitting it wherever the RE matches" msgstr "" #: ../src/Doc/howto/regex.rst:1044 msgid "``sub()``" msgstr "" #: ../src/Doc/howto/regex.rst:1044 msgid "" "Find all substrings where the RE matches, and replace them with a different " "string" msgstr "" #: ../src/Doc/howto/regex.rst:1047 msgid "``subn()``" msgstr "" #: ../src/Doc/howto/regex.rst:1047 msgid "" "Does the same thing as :meth:`sub`, but returns the new string and the " "number of replacements" msgstr "" #: ../src/Doc/howto/regex.rst:1054 msgid "Splitting Strings" msgstr "" #: ../src/Doc/howto/regex.rst:1056 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 "" #: ../src/Doc/howto/regex.rst:1067 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 "" #: ../src/Doc/howto/regex.rst:1072 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 "" #: ../src/Doc/howto/regex.rst:1084 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 "" #: ../src/Doc/howto/regex.rst:1096 msgid "" "The module-level function :func:`re.split` adds the RE to be used as the " "first argument, but is otherwise the same. ::" msgstr "" #: ../src/Doc/howto/regex.rst:1108 msgid "Search and Replace" msgstr "" #: ../src/Doc/howto/regex.rst:1110 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 "" #: ../src/Doc/howto/regex.rst:1118 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 "" #: ../src/Doc/howto/regex.rst:1122 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 "" #: ../src/Doc/howto/regex.rst:1126 msgid "" "Here's a simple example of using the :meth:`sub` method. It replaces colour " "names with the word ``colour``::" msgstr "" #: ../src/Doc/howto/regex.rst:1135 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 "" #: ../src/Doc/howto/regex.rst:1144 msgid "" "Empty matches are replaced only when they're not adjacent to a previous " "match. ::" msgstr "" #: ../src/Doc/howto/regex.rst:1151 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 "" #: ../src/Doc/howto/regex.rst:1158 msgid "" "This example matches the word ``section`` followed by a string enclosed in " "``{``, ``}``, and changes ``section`` to ``subsection``::" msgstr "" #: ../src/Doc/howto/regex.rst:1165 msgid "" "There's also a syntax for referring to named groups as defined by the ``(?" "P...)`` syntax. ``\\g`` will use the substring matched by the " "group named ``name``, and ``\\g`` 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 "" # 55f2296ddf34434fbcf9979ba3564d52 #: ../src/Doc/howto/regex.rst:1182 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 ` argument for the match and can use " "this information to compute the desired replacement string and return it." msgstr "" # 4b4a08bd8694459ba512d24b01e29b4c #: ../src/Doc/howto/regex.rst:1188 msgid "" "In the following example, the replacement function translates decimals into " "hexadecimal::" msgstr "" #: ../src/Doc/howto/regex.rst:1200 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 "" #: ../src/Doc/howto/regex.rst:1208 msgid "Common Problems" msgstr "" #: ../src/Doc/howto/regex.rst:1210 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 "" #: ../src/Doc/howto/regex.rst:1216 msgid "Use String Methods" msgstr "" #: ../src/Doc/howto/regex.rst:1218 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 "" #: ../src/Doc/howto/regex.rst:1226 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 "" #: ../src/Doc/howto/regex.rst:1235 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 "" #: ../src/Doc/howto/regex.rst:1241 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 "" #: ../src/Doc/howto/regex.rst:1246 msgid "match() versus search()" msgstr "" #: ../src/Doc/howto/regex.rst:1248 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 "" #: ../src/Doc/howto/regex.rst:1259 msgid "" "On the other hand, :func:`search` will scan forward through the string, " "reporting the first match it finds. ::" msgstr "" #: ../src/Doc/howto/regex.rst:1267 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 "" #: ../src/Doc/howto/regex.rst:1276 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 "" #: ../src/Doc/howto/regex.rst:1282 msgid "Greedy versus Non-Greedy" msgstr "" #: ../src/Doc/howto/regex.rst:1284 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 "" #: ../src/Doc/howto/regex.rst:1298 msgid "" "The RE matches the ``'<'`` in ````, 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 ```` to the ``'>'`` in ````, which isn't what you want." msgstr "" #: ../src/Doc/howto/regex.rst:1305 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 "" #: ../src/Doc/howto/regex.rst:1314 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 "" # 5df698055ad74e8f835cf198efdb2043 #: ../src/Doc/howto/regex.rst:1322 msgid "Using re.VERBOSE" msgstr "" #: ../src/Doc/howto/regex.rst:1324 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 "" #: ../src/Doc/howto/regex.rst:1329 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 "" #: ../src/Doc/howto/regex.rst:1333 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 "" #: ../src/Doc/howto/regex.rst:1350 msgid "This is far more readable than::" msgstr "" #: ../src/Doc/howto/regex.rst:1356 msgid "Feedback" msgstr "" #: ../src/Doc/howto/regex.rst:1358 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 "" #: ../src/Doc/howto/regex.rst:1363 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 "" #: ../src/Doc/howto/regex.rst:1373 ../src/Doc/howto/urllib2.rst:556 msgid "Footnotes" msgstr "" #: ../src/Doc/howto/regex.rst:1374 msgid "Introduced in Python 2.2.2." msgstr "" #: ../src/Doc/howto/sockets.rst:5 msgid "Socket Programming HOWTO" msgstr "" #: ../src/Doc/howto/sockets.rst:7 msgid "Gordon McMillan" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/sockets.rst:20 msgid "Sockets" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/sockets.rst:40 msgid "History" msgstr "" # e7871668004045188ed6c94e54d4efbe #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/sockets.rst:54 msgid "Creating a Socket" msgstr "" #: ../src/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 "" # 3905ece01e6441f8afc1e6c38e889cb8 #: ../src/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 "" # ecb0daa4451d445a931574c5b45b359a #: ../src/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 "" # db84be2f300245108ba171f533a0cff2 #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # e55626a58ce64ac2ac88801517904a73 #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/sockets.rst:125 msgid "IPC" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/sockets.rst:137 msgid "Using a Socket" msgstr "" #: ../src/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 "" # 729d651ca80e4c2d8717cbcad950867e #: ../src/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 "" # dae25367caed44448f8e02023b0bbd6e #: ../src/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 "" # dfdbac43752945419feccf97f87cc592 #: ../src/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 "" # 3c37b186079d4ecd88dfc56883717ae4 #: ../src/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 "" # 47de6a40b8db48a0a0cf1df2e33902a3 #: ../src/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 "" #: ../src/Doc/howto/sockets.rst:183 msgid "" "Assuming you don't want to end the connection, the simplest solution is a " "fixed length message::" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/sockets.rst:255 msgid "Binary Data" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/sockets.rst:275 msgid "Disconnecting" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/sockets.rst:300 msgid "When Sockets Die" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/sockets.rst:316 msgid "Non-blocking Sockets" msgstr "" # 9eef3c101097417da3a048634c989364 #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/sockets.rst:337 msgid "Use ``select``." msgstr "" # 7793785b92b841b587d2381b06c5d5d8 #: ../src/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 "" #: ../src/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 "" # a343bae8dd47414082af0aefab04f924 #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/sockets.rst:395 msgid "Performance" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # 4284717d31514f3889f6b03c1e52a49c #: ../src/Doc/howto/sorting.rst:4 msgid "Sorting HOW TO" msgstr "" # d7a5018307884c6780bd3920bae9cdd8 #: ../src/Doc/howto/sorting.rst:6 msgid "Andrew Dalke and Raymond Hettinger" msgstr "" # 670fa45cbaa04a8ba63df9b070da9fc0 #: ../src/Doc/howto/sorting.rst:7 msgid "0.1" msgstr "" # 367e757cb278492cb65d416195d0b115 #: ../src/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 "" # 27622c84f7c947c3988d70b27d5a3feb #: ../src/Doc/howto/sorting.rst:14 msgid "" "In this document, we explore the various techniques for sorting data using " "Python." msgstr "" # cb1892243c144b9c96dff3a79b08b2ac #: ../src/Doc/howto/sorting.rst:18 msgid "Sorting Basics" msgstr "" # db6a4b548050492787ab88d2f5291c80 #: ../src/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 "" # 896c6bad8a05402fa5e80ab54cd98ffc #: ../src/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 "" # ca7cb8b097ae42dd9e89c0438e4a5ad0 #: ../src/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 "" # f4c199239f1b456cb3ca8a330df760ad #: ../src/Doc/howto/sorting.rst:43 msgid "Key Functions" msgstr "" # 983ae1c53cd548f9a7cfe908066dc496 #: ../src/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 "" # e415d3fdc29449d2ad18d1359c692660 #: ../src/Doc/howto/sorting.rst:49 msgid "For example, here's a case-insensitive string comparison:" msgstr "" # 0b790213124d4408951802a40f9c89a8 #: ../src/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 "" # 6cf7c0f828894071b143d85f8747d87a #: ../src/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 "" # 777ea18bfefc4093bd2de8dd7aaf5d92 #: ../src/Doc/howto/sorting.rst:69 msgid "" "The same technique works for objects with named attributes. For example:" msgstr "" # f7131f5aa9794cf485a9702c641f03ad #: ../src/Doc/howto/sorting.rst:88 msgid "Operator Module Functions" msgstr "" # a7f612173a9844769d26c10f3347aaee #: ../src/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 "" # 47c19b22ea784fce8c3b7b706fab7a38 #: ../src/Doc/howto/sorting.rst:95 msgid "Using those functions, the above examples become simpler and faster:" msgstr "" # 24bcc0055dc14ba692205dda1e48b60b #: ../src/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 "" # c6846cf8541d4dc2b494349d9df5f9ab #: ../src/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 "" # 616d6ee3d69243bda2d0667bfe01e0ae #: ../src/Doc/howto/sorting.rst:124 msgid "Ascending and Descending" msgstr "" # 60b013093eaf448ea404c21687b85268 #: ../src/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 "" # 097321de0759493d82c34c97df177fcb #: ../src/Doc/howto/sorting.rst:137 msgid "Sort Stability and Complex Sorts" msgstr "" # 15b52a2a732d4ad69bb50cfb4d4f6716 #: ../src/Doc/howto/sorting.rst:139 msgid "" "Starting with Python 2.2, sorts are guaranteed to be `stable `_\\. That means that when " "multiple records have the same key, their original order is preserved." msgstr "" # 4ebcb6dd76e24f8ba237c6ff71194b8f #: ../src/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 "" # b1b08e6444b944a6b1025f9dff000ee7 #: ../src/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 "" # 3bdbcc8410704821b6ed557401a2ccc0 #: ../src/Doc/howto/sorting.rst:158 msgid "" "The `Timsort `_ algorithm used in " "Python does multiple sorts efficiently because it can take advantage of any " "ordering already present in a dataset." msgstr "" # 79b92d0704844d5d9bc1b529840924a4 #: ../src/Doc/howto/sorting.rst:163 msgid "The Old Way Using Decorate-Sort-Undecorate" msgstr "" # 508062ce23484a88ae37b9f2660b2e43 #: ../src/Doc/howto/sorting.rst:165 msgid "This idiom is called Decorate-Sort-Undecorate after its three steps:" msgstr "" # b371b99cb45e4aee8e39184993763bfb #: ../src/Doc/howto/sorting.rst:167 msgid "" "First, the initial list is decorated with new values that control the sort " "order." msgstr "" # 3f6c58521d1e48579433b365ac911442 #: ../src/Doc/howto/sorting.rst:169 msgid "Second, the decorated list is sorted." msgstr "" # af5b5d5f652f499585381f8953b62e83 #: ../src/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 "" # ad2458b3badc4fb4bb166e21e6281a12 #: ../src/Doc/howto/sorting.rst:174 msgid "" "For example, to sort the student data by *grade* using the DSU approach:" msgstr "" # fec9a3f8caa649e19c958a0c14fe8a8a #: ../src/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 "" # 3081edc4364142d998f74d2c756591b8 #: ../src/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 "" # 8f67149c545a425da7da7362f80412d9 #: ../src/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 "" # b6a667eda2e44cd385bd19085d92ddeb #: ../src/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 "" # 7435aabd2ba645dabe1b33148df25ca4 #: ../src/Doc/howto/sorting.rst:196 msgid "" "Another name for this idiom is `Schwartzian transform `_\\, after Randal L. Schwartz, who " "popularized it among Perl programmers." msgstr "" # 3560fa1e26cd40768bfb61056dda6e88 #: ../src/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 "" # d3eef37605644be38cdc4fb08128ca57 #: ../src/Doc/howto/sorting.rst:206 msgid "The Old Way Using the *cmp* Parameter" msgstr "" # 0f0403618175490d931ef2673ff1d97b #: ../src/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 "" # dd1854578a0c435f945f478e37b2f76e #: ../src/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 "" # 78700606a4a94cb18a213c98f9fe6811 #: ../src/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 "" # 6d23858789884320a68794195c010650 #: ../src/Doc/howto/sorting.rst:227 msgid "Or you can reverse the order of comparison with:" msgstr "" # b7d66c05f7f14f74a75eb87338458b25 #: ../src/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 "" # 7a1ee2ce88d543a8ba1bdf4505989e18 #: ../src/Doc/howto/sorting.rst:257 msgid "To convert to a key function, just wrap the old comparison function:" msgstr "" # 3a7085471278443391dc3572228c7045 #: ../src/Doc/howto/sorting.rst:262 msgid "" "In Python 2.7, the :func:`functools.cmp_to_key` function was added to the " "functools module." msgstr "" # 5235e46413674c06acca5d257b8a29a3 #: ../src/Doc/howto/sorting.rst:266 msgid "Odd and Ends" msgstr "" # 92d06d7cbcb843a282ff05b5c38c98c8 #: ../src/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 "" # 1f3174fed1cb4f2982f6592227116214 #: ../src/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 "" # 9dad66f689e04eb8aedf696b5ec6c18f #: ../src/Doc/howto/sorting.rst:279 msgid "" "To create a standard sort order for a class, just add the appropriate rich " "comparison methods:" msgstr "" # 68ffd8547fec4928a04d3b37ce93650b #: ../src/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 "" # e0f7bfa23aaf4771bda22854ff475bf9 #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:3 msgid "Unicode HOWTO" msgstr "" # f0603228071d4d5b97ad98f6989a055b #: ../src/Doc/howto/unicode.rst:5 msgid "1.03" msgstr "" # 6031f6ca8abd4bada350990c6475ba09 #: ../src/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 ." msgstr "" #: ../src/Doc/howto/unicode.rst:13 msgid "Introduction to Unicode" msgstr "" #: ../src/Doc/howto/unicode.rst:16 msgid "History of Character Codes" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:38 msgid "" "Those messages should contain accents, and they just look wrong to someone " "who can read French." msgstr "" #: ../src/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 "" # 0ea94b9291bd4774b3398829a5b7384a #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:78 msgid "Definitions" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:115 msgid "Encodings" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:130 msgid "" "This representation is straightforward but using it presents a number of " "problems." msgstr "" #: ../src/Doc/howto/unicode.rst:133 msgid "It's not portable; different processors order the bytes differently." msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # cc1dab2c0009444e990243444649463a #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:182 msgid "" "If the code point is <128, it's represented by the corresponding byte value." msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:188 msgid "UTF-8 has several convenient properties:" msgstr "" #: ../src/Doc/howto/unicode.rst:190 msgid "It can handle any Unicode code point." msgstr "" #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:195 msgid "A string of ASCII text is also valid UTF-8 text." msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:207 msgid "" "The Unicode Consortium site at has character " "charts, a glossary, and PDF versions of the Unicode specification. Be " "prepared for some difficult reading. is a " "chronology of the origin and development of Unicode." msgstr "" #: ../src/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 ." msgstr "" #: ../src/Doc/howto/unicode.rst:216 msgid "" "Another good introductory article was written by Joel Spolsky . If this introduction didn't make " "things clear to you, you should try reading this alternate article before " "continuing." msgstr "" #: ../src/Doc/howto/unicode.rst:223 msgid "" "Wikipedia entries are often helpful; see the entries for \"character encoding" "\" and UTF-8 , for example." msgstr "" #: ../src/Doc/howto/unicode.rst:229 msgid "Python 2.x's Unicode Support" msgstr "" #: ../src/Doc/howto/unicode.rst:231 msgid "" "Now that you've learned the rudiments of Unicode, we can look at Python's " "Unicode features." msgstr "" # 95575318bd2e4649acf89c0a0c106253 #: ../src/Doc/howto/unicode.rst:236 msgid "The Unicode Type" msgstr "" # bc0af3d4b7124b2089f24fa1af29d6f7 #: ../src/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 "" # 06830998a1d645369f452933d329fe7b #: ../src/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 "" # 973b548a3a514d67a576ce9f755f76a2 #: ../src/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 "" # 75eddfe198e84048b080ba7ebf56dc89 #: ../src/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 "" # 3ba978cc66d64b6fa4037baa1804e478 #: ../src/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 "" # c9bf561bc2b44496a8ddac22e192fd73 #: ../src/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 "" # 0dbbed0604464c668161c390fce70bf1 #: ../src/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 "" # 9469a4c5d759425693d496fd2ad0ca43 #: ../src/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 "" # 78df166292b2405ea61b49d3267ab19e #: ../src/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 "" # 8b4c285a06cc404a9452289a42772537 #: ../src/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 "" #: ../src/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 "" # 6c38b4db0a664cc686b387b1bf7c54a2 #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:374 msgid "Unicode Literals in Python Source Code" msgstr "" # d0d2d155594c4d89ae17867aa5455b1b #: ../src/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 "" # 89cdfead9b054e709b24341f6d5e1b82 #: ../src/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 "" # 109ec1dceb734e6c8ef02ea4cf155a8d #: ../src/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 "" #: ../src/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 "" # 44e69958fa7a40c294a02b4da16484f3 #: ../src/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 "" #: ../src/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 "" # d947639e88ad4416b1710e017ab69960 #: ../src/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 "" # 723712f415c441e384800fc48cfef3bf #: ../src/Doc/howto/unicode.rst:433 msgid "When you run it with Python 2.4, it will output the following warning::" msgstr "" # b2a10168b08b46e2a4401359f5a3e9f5 #: ../src/Doc/howto/unicode.rst:440 msgid "Python 2.5 and higher are stricter and will produce a syntax error::" msgstr "" #: ../src/Doc/howto/unicode.rst:450 msgid "Unicode Properties" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:473 msgid "When run, this prints::" msgstr "" #: ../src/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 for a list of category codes." msgstr "" # 8c87d97a3fc04021837431c59183b511 #: ../src/Doc/howto/unicode.rst:494 msgid "" "The Unicode and 8-bit string types are described in the Python library " "reference at :ref:`typesseq`." msgstr "" #: ../src/Doc/howto/unicode.rst:497 msgid "The documentation for the :mod:`unicodedata` module." msgstr "" #: ../src/Doc/howto/unicode.rst:499 msgid "The documentation for the :mod:`codecs` module." msgstr "" # dce90c14394a4c8787c1696da2757602 #: ../src/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 , and is an excellent " "overview of the design of Python's Unicode features." msgstr "" #: ../src/Doc/howto/unicode.rst:508 msgid "Reading and Writing Unicode Data" msgstr "" #: ../src/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 "" #: ../src/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 "" # a16bd8622b3b4b50b66c9b908984b480 #: ../src/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 "" #: ../src/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 "" # 40a1ed8457d74005bef6d762f1cc2d63 #: ../src/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 "" # c1eb1099ff3343bea56bc19b556e9187 #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:553 msgid "Reading Unicode from a file is therefore simple::" msgstr "" #: ../src/Doc/howto/unicode.rst:560 msgid "" "It's also possible to open files in update mode, allowing both reading and " "writing::" msgstr "" # 2510edec2b454515a5076eee83963dae #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:580 msgid "Unicode filenames" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:602 msgid "" "Functions in the :mod:`os` module such as :func:`os.stat` will also accept " "Unicode filenames." msgstr "" # e5da669dd8bf47c5ba291d494abd38c8 #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:622 msgid "will produce the following output::" msgstr "" #: ../src/Doc/howto/unicode.rst:628 msgid "" "The first list contains UTF-8-encoded filenames, and the second list " "contains the Unicode versions." msgstr "" #: ../src/Doc/howto/unicode.rst:634 msgid "Tips for Writing Unicode-aware Programs" msgstr "" #: ../src/Doc/howto/unicode.rst:636 msgid "" "This section provides some suggestions on writing software that deals with " "Unicode." msgstr "" #: ../src/Doc/howto/unicode.rst:639 msgid "The most important tip is:" msgstr "" #: ../src/Doc/howto/unicode.rst:641 msgid "" "Software should only work with Unicode strings internally, converting to a " "particular encoding on output." msgstr "" # cdd3630aa19347d1955cba2331d28c29 #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:656 msgid "" "Include characters > 127 and, even better, characters > 255 in your test " "data." msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # ab5c90b2c2974f19b4e2a6b7c26ebb61 #: ../src/Doc/howto/unicode.rst:688 msgid "" "The PDF slides for Marc-André Lemburg's presentation \"Writing Unicode-aware " "Applications in Python\" are available at and " "discuss questions of character encodings as well as how to internationalize " "and localize an application." msgstr "" #: ../src/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 "" #: ../src/Doc/howto/unicode.rst:702 msgid "Version 1.0: posted August 5 2005." msgstr "" #: ../src/Doc/howto/unicode.rst:704 msgid "" "Version 1.01: posted August 7 2005. Corrects factual and markup errors; " "adds several links." msgstr "" #: ../src/Doc/howto/unicode.rst:707 msgid "Version 1.02: posted August 16 2005. Corrects factual errors." msgstr "" # a6fc3f10401e464b956f831ced5c1788 #: ../src/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 "" # 65623620ffe44193becd18e054d3732f #: ../src/Doc/howto/urllib2.rst:3 msgid "HOWTO Fetch Internet Resources Using urllib2" msgstr "" #: ../src/Doc/howto/urllib2.rst:5 msgid "`Michael Foord `_" msgstr "" # 53960c1e8aec49f2bffda275f14d2a84 #: ../src/Doc/howto/urllib2.rst:9 msgid "" "There is an French translation of an earlier revision of this HOWTO, " "available at `urllib2 - Le Manuel manquant `_." msgstr "" # 37ffef111acd4e24b36c46b02dd190c8 #: ../src/Doc/howto/urllib2.rst:20 msgid "" "You may also find useful the following article on fetching web resources " "with Python:" msgstr "" #: ../src/Doc/howto/urllib2.rst:23 msgid "" "`Basic Authentication `_" msgstr "" #: ../src/Doc/howto/urllib2.rst:25 msgid "A tutorial on *Basic Authentication*, with examples in Python." msgstr "" # f32bd4d9d7b347e9b240b3060e6ed1d6 #: ../src/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 "" # 18f5db69f47a400a84f93efb6f771cf9 #: ../src/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 "" # a2461a4aaf8241beaae755dd9678ff93 #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:49 msgid "Fetching URLs" msgstr "" # 824d055376664e5799516dfaf81e53dc #: ../src/Doc/howto/urllib2.rst:51 msgid "The simplest way to use urllib2 is as follows::" msgstr "" # 0a6c7e6f4cd14a368ec9f7f1e5868ad6 #: ../src/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 "" # 2c4d8714f18b49a6b7955a6a930c2d7e #: ../src/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 "" # df9c25fa0174438db81b2f330e060ef4 #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:88 msgid "Data" msgstr "" # bc401d47aca24bae9d59fadfeafc3e3a #: ../src/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 "" #: ../src/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 `_ for more details)." msgstr "" # d71ab805d8d54acbb86646b808ba07f6 #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:128 msgid "This is done as follows::" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:147 msgid "Headers" msgstr "" #: ../src/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 "" # 63d32013fbd24a6abd2e858b8ed44e7c #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:183 msgid "Handling Exceptions" msgstr "Gestion des exceptions" #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:189 msgid "" ":exc:`HTTPError` is the subclass of :exc:`URLError` raised in the specific " "case of HTTP URLs." msgstr "" #: ../src/Doc/howto/urllib2.rst:193 msgid "URLError" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:200 ../src/Doc/howto/urllib2.rst:445 msgid "e.g. ::" msgstr "" #: ../src/Doc/howto/urllib2.rst:211 msgid "HTTPError" msgstr "" # 9182cb4b493b4265bff4e08456108e64 #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:221 msgid "See section 10 of RFC 2616 for a reference on all the HTTP error codes." msgstr "" #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:227 msgid "Error Codes" msgstr "" #: ../src/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 "" # 5344668b550d48189024e40db7d8c04b #: ../src/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 "" # d15bb283b8424587b606098bd2114391 #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:326 msgid "Wrapping it Up" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:332 msgid "Number 1" msgstr "" #: ../src/Doc/howto/urllib2.rst:353 msgid "" "The ``except HTTPError`` *must* come first, otherwise ``except URLError`` " "will *also* catch an :exc:`HTTPError`." msgstr "" #: ../src/Doc/howto/urllib2.rst:357 msgid "Number 2" msgstr "" #: ../src/Doc/howto/urllib2.rst:377 msgid "info and geturl" msgstr "" # 6a98c8600eaf4e189c64358c806b9392 #: ../src/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 "" #: ../src/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 "" # 864bae0c9c6f4c0d8307bdc0e5a54720 #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:390 msgid "" "Typical headers include 'Content-length', 'Content-type', and so on. See the " "`Quick Reference to HTTP Headers `_ for a useful listing of HTTP headers with brief explanations of " "their meaning and use." msgstr "" #: ../src/Doc/howto/urllib2.rst:397 msgid "Openers and Handlers" msgstr "" # 75d1b95e6ca74639b4413076925bdae6 #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:411 msgid "" "To create an opener, instantiate an ``OpenerDirector``, and then call ``." "add_handler(some_handler_instance)`` repeatedly." msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:432 msgid "Basic Authentication" msgstr "" #: ../src/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 `_." msgstr "" # 7d1ffba9b9344d65a0e68c12d272e34d #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # 3cfeca7ca1f6413db2ce296f6249d120 #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:507 msgid "Proxies" msgstr "" # ea34a8ddd26347f4a85388db0e01dfe3 #: ../src/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 "" # 00fc391290a34cf0988312bacc9cc59d #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:528 msgid "Sockets and Layers" msgstr "" # 2e147482bbd9453aaa22b7173fe559fa #: ../src/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 "" # e53343191df94e3a9ad0f7c9dbe86bc6 #: ../src/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 "" #: ../src/Doc/howto/urllib2.rst:558 msgid "This document was reviewed and revised by John Lee." msgstr "" #: ../src/Doc/howto/urllib2.rst:560 msgid "" "For an introduction to the CGI protocol see `Writing Web Applications in " "Python `_." msgstr "" # 885c869c7df740f8b915b13fba3ce070 #: ../src/Doc/howto/urllib2.rst:562 msgid "" "Like Google for example. The *proper* way to use google from a program is to " "use `PyGoogle `_ of course." msgstr "" #: ../src/Doc/howto/urllib2.rst:564 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 "" #: ../src/Doc/howto/urllib2.rst:567 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 "" #: ../src/Doc/howto/urllib2.rst:569 msgid "" "For details of more HTTP request headers, see `Quick Reference to HTTP " "Headers`_." msgstr "" # 5d228402a5104663b6c4dc5842307541 #: ../src/Doc/howto/urllib2.rst:571 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 "" # b1baf60a72034136bf1db086e6a9a99e #: ../src/Doc/howto/urllib2.rst:576 msgid "" "urllib2 opener for SSL proxy (CONNECT method): `ASPN Cookbook Recipe `_." msgstr "" #: ../src/Doc/howto/webservers.rst:3 msgid "HOWTO Use Python in the web" msgstr "" #: ../src/Doc/howto/webservers.rst:5 msgid "Marek Kubica" msgstr "" #: ../src/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 "" #: ../src/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 "" # 9b6eb4bd2e8b41919d5a554c0663036a #: ../src/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 `_ may be more in sync with recent development." msgstr "" #: ../src/Doc/howto/webservers.rst:34 msgid "The Low-Level View" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:61 msgid "Common Gateway Interface" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:74 msgid "" "Writing CGI programs, while still possible, is no longer recommended. With :" "ref:`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 "" #: ../src/Doc/howto/webservers.rst:81 msgid "" "The Python standard library includes some modules that are helpful for " "creating plain CGI programs:" msgstr "" #: ../src/Doc/howto/webservers.rst:84 msgid ":mod:`cgi` -- Handling of user input in CGI scripts" msgstr "" #: ../src/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 "" # 24a5193d701f40b58c257244970fee65 #: ../src/Doc/howto/webservers.rst:88 msgid "" "The Python wiki features a page on `CGI scripts `_ with some additional information about CGI in Python." msgstr "" #: ../src/Doc/howto/webservers.rst:94 msgid "Simple script for testing CGI" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:125 msgid "Setting up CGI on your own server" msgstr "" #: ../src/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 "" #: ../src/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 `_, or Apache for short. Apache can " "be easily installed on nearly every system using the system's package " "management tool. `lighttpd `_ 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 "" #: ../src/Doc/howto/webservers.rst:143 msgid "" "On Apache you can take a look at the `Dynamic Content with CGI `_ 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 "" # 60997289570c43509daf0ed08881da82 #: ../src/Doc/howto/webservers.rst:148 msgid "" "On lighttpd you need to use the `CGI module `_\\ , which can be configured in a " "straightforward way. It boils down to setting ``cgi.assign`` properly." msgstr "" #: ../src/Doc/howto/webservers.rst:154 msgid "Common problems with CGI scripts" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:160 msgid "Some of these potential problems are:" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:210 msgid "mod_python" msgstr "mod_python" # 5e8b17673bd84a4887bbc10218a01eeb #: ../src/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 `_\\ , " "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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:244 msgid "FastCGI and SCGI" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:265 msgid "Setting up FastCGI" msgstr "" #: ../src/Doc/howto/webservers.rst:267 msgid "Each web server requires a specific module." msgstr "" # 31d3a58613b2473ab67ec0c40162146b #: ../src/Doc/howto/webservers.rst:269 msgid "" "Apache has both `mod_fastcgi `_ and " "`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 "" # 5d114d0b485c4eeb93c1488203ba552c #: ../src/Doc/howto/webservers.rst:275 msgid "" "lighttpd ships its own `FastCGI module `_ as well as an `SCGI module `_." msgstr "" #: ../src/Doc/howto/webservers.rst:279 msgid "" "`nginx `_ also supports `FastCGI `_." msgstr "" #: ../src/Doc/howto/webservers.rst:282 msgid "" "Once you have installed and configured the module, you can test it with the " "following WSGI-application::" msgstr "" # a57cb42d937140709d0a05581462253a #: ../src/Doc/howto/webservers.rst:303 msgid "" "This is a simple WSGI application, but you need to install `flup `_ first, as flup handles the low level " "FastCGI access." msgstr "" # 281193186bff42e893d6465dafb25cb7 #: ../src/Doc/howto/webservers.rst:309 msgid "" "There is some documentation on `setting up Django with 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 "" #: ../src/Doc/howto/webservers.rst:317 msgid "mod_wsgi" msgstr "" #: ../src/Doc/howto/webservers.rst:319 msgid "" "`mod_wsgi `_ 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 "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:337 msgid "Step back: WSGI" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # 7cc3b099af6345369e4e70cf8ab96afb #: ../src/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 `_ 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 "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:376 msgid "WSGI Servers" msgstr "" #: ../src/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 `_. 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 "" #: ../src/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 "" # 3bae285171d94873a63ee8c88ce45f7f #: ../src/Doc/howto/webservers.rst:391 msgid "" "A good overview of WSGI-related code can be found in the `WSGI homepage " "`_, which contains an extensive " "list of `WSGI servers `_ which " "can be used by *any* application supporting WSGI." msgstr "" #: ../src/Doc/howto/webservers.rst:396 msgid "" "You might be interested in some WSGI-supporting modules already contained in " "the standard library, namely:" msgstr "" #: ../src/Doc/howto/webservers.rst:399 msgid ":mod:`wsgiref` -- some tiny utilities and servers for WSGI" msgstr "" #: ../src/Doc/howto/webservers.rst:403 msgid "Case study: MoinMoin" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:409 msgid "" "One of the most widely used wiki software packages is `MoinMoin `_. 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 "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:421 msgid "Model-View-Controller" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:432 msgid "MVC stands for three components:" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:461 msgid "" "The English Wikipedia has an article about the `Model-View-Controller " "pattern `_. It includes " "a long list of web frameworks for various programming languages." msgstr "" #: ../src/Doc/howto/webservers.rst:467 msgid "Ingredients for Websites" msgstr "" #: ../src/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 "" # 0b70426b273842c7aeb0d13d84d59533 #: ../src/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 `_." msgstr "" #: ../src/Doc/howto/webservers.rst:485 msgid "Templates" msgstr "" #: ../src/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 "" # f28155ec1cbe47cc88eb8d6a2d1af868 #: ../src/Doc/howto/webservers.rst:493 msgid "Python already includes two ways to build simple templates::" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:518 msgid "Popular template engines include:" msgstr "" #: ../src/Doc/howto/webservers.rst:520 msgid "`Mako `_" msgstr "`Mako `_" #: ../src/Doc/howto/webservers.rst:521 msgid "`Genshi `_" msgstr "`Genshi `_" #: ../src/Doc/howto/webservers.rst:522 #, fuzzy msgid "`Jinja `_" msgstr "`Jinja `_" # 6645ceeebd304a038727a8fdc0649eda #: ../src/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 `_ 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 "" #: ../src/Doc/howto/webservers.rst:534 msgid "Data persistence" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:541 msgid "" "Often, relational database engines like `MySQL `_ or " "`PostgreSQL `_ 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 `_, 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 "" #: ../src/Doc/howto/webservers.rst:549 msgid "" "Relational databases are *queried* using a language called `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 `_ (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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" # b32960c4248544d4989eb91da5dd2faf #: ../src/Doc/howto/webservers.rst:578 msgid "" "`Persistence Tools `_ lists " "possibilities on how to save data in the file system. Some of these modules " "are part of the standard library" msgstr "" # b9b6ac249fc14aa9997f3ba4bab579ce #: ../src/Doc/howto/webservers.rst:582 msgid "" "`Database Programming `_ " "helps with choosing a method for saving data" msgstr "" #: ../src/Doc/howto/webservers.rst:585 msgid "" "`SQLAlchemy `_, the most powerful OR-Mapper for " "Python, and `Elixir `_, which makes SQLAlchemy " "easier to use" msgstr "" #: ../src/Doc/howto/webservers.rst:589 msgid "`SQLObject `_, another popular OR-Mapper" msgstr "" #: ../src/Doc/howto/webservers.rst:591 msgid "" "`ZODB `_ and `Durus `_, two object oriented databases" msgstr "" #: ../src/Doc/howto/webservers.rst:599 msgid "Frameworks" msgstr "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:635 msgid "Some notable frameworks" msgstr "" #: ../src/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 "" #: ../src/Doc/howto/webservers.rst:642 msgid "Django" msgstr "Django" # f21816ade0d647668a38054f6f2aa0f3 #: ../src/Doc/howto/webservers.rst:644 msgid "" "`Django `_ 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 "" # 51774238daa345ccb0572ecd7ba5129a #: ../src/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 `_ and the `Django " "book `_." msgstr "" # 4808cbb303f34a088363b19e6180eded #: ../src/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 `_." msgstr "" #: ../src/Doc/howto/webservers.rst:669 msgid "TurboGears" msgstr "TurboGears" #: ../src/Doc/howto/webservers.rst:671 msgid "" "Another popular web framework for Python is `TurboGears `_. 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 "" #: ../src/Doc/howto/webservers.rst:678 msgid "" "The documentation can be found in the `TurboGears wiki `_, 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 `_ published, " "which is a good starting point." msgstr "" # af4bd541aec84ab8be1a19f8b414c72a #: ../src/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 `_." msgstr "" #: ../src/Doc/howto/webservers.rst:691 msgid "Zope" msgstr "Zope" #: ../src/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 `_ (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 `_ " "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 `_." msgstr "" # 3d48b3d82e154f6ab37bb1041e751122 #: ../src/Doc/howto/webservers.rst:708 msgid "" "Zope is also the infrastructure used by the `Plone `_ " "content management system, one of the most powerful and popular content " "management systems available." msgstr "" #: ../src/Doc/howto/webservers.rst:714 msgid "Other notable frameworks" msgstr "" #: ../src/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 "" #: ../src/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 `_, an extensive set of tools " "which are handy for WSGI." msgstr "" #: ../src/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 "" # 842b2f2a42f941a3974843f2dbe6bf31 #: ../src/Doc/howto/webservers.rst:731 msgid "" "The Python wiki contains an extensive list of `web frameworks `_." msgstr "" # fd0de91d1f44499cad218f757a4e274f #: ../src/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. There is also a general \"Python in " "the Web\" IRC channel on freenode called `#python.web `_." msgstr "" #~ 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"