forked from AFPy/python-docs-fr
11982 lines
438 KiB
Plaintext
11982 lines
438 KiB
Plaintext
# SOME DESCRIPTIVE TITLE.
|
|
# Copyright (C) 1990-2010, Python Software Foundation
|
|
# This file is distributed under the same license as the Python package.
|
|
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
|
|
#, fuzzy
|
|
msgid ""
|
|
msgstr ""
|
|
"Project-Id-Version: PACKAGE VERSION\n"
|
|
"Report-Msgid-Bugs-To: \n"
|
|
"POT-Creation-Date: 2014-11-03 09:23\n"
|
|
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
|
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
|
"Language-Team: LANGUAGE <LL@li.org>\n"
|
|
"Language: \n"
|
|
"MIME-Version: 1.0\n"
|
|
"Content-Type: text/plain; charset=UTF-8\n"
|
|
"Content-Transfer-Encoding: 8bit\n"
|
|
"X-Generator: Translate Toolkit 1.7.0\n"
|
|
|
|
# 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 ""
|
|
|
|
# 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 "
|
|
"<http://cython.org/>`_. It translates a Python-like language to C. The "
|
|
"extension modules it creates are compatible with Python 3 and Python 2."
|
|
msgstr ""
|
|
|
|
#: ../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 "<python at rcn dot com>"
|
|
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 ""
|
|
|
|
#: ../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 ""
|
|
|
|
#: ../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 ""
|
|
|
|
#: ../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 ""
|
|
|
|
#: ../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 ""
|
|
|
|
#: ../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 <http://en.wikipedia."
|
|
"org/wiki/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 <http://www.ibm.com/developerworks/linux/library/l-prog/index."
|
|
"html>`__, `part 2 <http://www.ibm.com/developerworks/linux/library/l-prog2/"
|
|
"index.html>`__, and `part 3 <http://www.ibm.com/developerworks/linux/library/"
|
|
"l-prog3/index.html>`__,"
|
|
msgstr ""
|
|
|
|
#: ../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 <vinay_sajip at red-dove dot com>"
|
|
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 ``%(<dictionary key>)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 <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 <network-logging>` documents this approach in more detail and "
|
|
"includes a working socket receiver which can be used as a starting point for "
|
|
"you to adapt in your own applications."
|
|
msgstr ""
|
|
|
|
# 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 <https://docs.djangoproject.com/"
|
|
"en/1.3/topics/logging/#configuring-logging>`_. This dictionary is passed to :"
|
|
"func:`~config.dictConfig` to put the configuration into effect::"
|
|
msgstr ""
|
|
|
|
# d6557a9605484f1db1163ee13b579a07
|
|
#: ../src/Doc/howto/logging-cookbook.rst:708
|
|
msgid ""
|
|
"For more information about this configuration, you can see the `relevant "
|
|
"section <https://docs.djangoproject.com/en/1.6/topics/logging/#configuring-"
|
|
"logging>`_ of the Django documentation."
|
|
msgstr ""
|
|
|
|
# 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 <http://tools.ietf.org/html/rfc5424>`_ requires that a Unicode "
|
|
"message be sent to a syslog daemon as a set of bytes which have the "
|
|
"following structure: an optional pure-ASCII component, followed by a UTF-8 "
|
|
"Byte Order Mark (BOM), followed by Unicode encoded using UTF-8. (See the "
|
|
"`relevant section of the specification <http://tools.ietf.org/html/"
|
|
"rfc5424#section-6>`_.)"
|
|
msgstr ""
|
|
|
|
# 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 <https://pypi.python.org/pypi/caniusepython3>`__, `web "
|
|
"app <https://caniusepython3.com/>`__)"
|
|
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 <amk@amk.ca>"
|
|
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 <re-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 <match-objects>` 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 <http://kodos.sourceforge."
|
|
"net/>`_ 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 <match-objects>`, "
|
|
"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 <match-objects>` for information "
|
|
"about the matching string. :ref:`match object <match-objects>` instances "
|
|
"also have several methods and attributes; the most important ones are:"
|
|
msgstr ""
|
|
|
|
#: ../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 "
|
|
"<match-objects>` 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 <match-objects>` 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 <match-objects>` 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 <match-objects>` methods all have group 0 as "
|
|
"their default argument. Later we'll see how to express groups that don't "
|
|
"capture the span of text that they match. ::"
|
|
msgstr ""
|
|
|
|
#: ../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<name>...)`` defines a named group, and ``(?P=name)`` is a "
|
|
"backreference to a named group. If future versions of Perl 5 add similar "
|
|
"features using a different syntax, the :mod:`re` module will be changed to "
|
|
"support the new syntax, while preserving the Python-specific syntax for "
|
|
"compatibility's sake."
|
|
msgstr ""
|
|
|
|
#: ../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>...)``. *name* is, obviously, the name of the group. Named groups "
|
|
"also behave exactly like capturing groups, and additionally associate a name "
|
|
"with a group. The :ref:`match object <match-objects>` methods that deal "
|
|
"with capturing groups all accept either integers that refer to the group by "
|
|
"number or strings that contain the desired group's name. Named groups are "
|
|
"still given numbers, so you can retrieve information about a group in two "
|
|
"ways::"
|
|
msgstr ""
|
|
|
|
#: ../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<word>\\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<name>...)`` syntax. ``\\g<name>`` will use the substring matched by the "
|
|
"group named ``name``, and ``\\g<number>`` uses the corresponding group "
|
|
"number. ``\\g<2>`` is therefore equivalent to ``\\2``, but isn't ambiguous "
|
|
"in a replacement string such as ``\\g<2>0``. (``\\20`` would be interpreted "
|
|
"as a reference to group 20, not a reference to group 2 followed by the "
|
|
"literal character ``'0'``.) The following substitutions are all equivalent, "
|
|
"but use all three variations of the replacement string. ::"
|
|
msgstr ""
|
|
|
|
# 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 <match-objects>` 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 ``<html>``, and the ``.*`` consumes the rest "
|
|
"of the string. There's still more left in the RE, though, and the ``>`` "
|
|
"can't match at the end of the string, so the regular expression engine has "
|
|
"to backtrack character by character until it finds a match for the ``>``. "
|
|
"The final match extends from the ``'<'`` in ``<html>`` to the ``'>'`` in ``</"
|
|
"title>``, which isn't what you want."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://en."
|
|
"wikipedia.org/wiki/Sorting_algorithm#Stability>`_\\. 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 <http://en.wikipedia.org/wiki/Timsort>`_ algorithm used in "
|
|
"Python does multiple sorts efficiently because it can take advantage of any "
|
|
"ordering already present in a dataset."
|
|
msgstr ""
|
|
|
|
# 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 <http://en.wikipedia."
|
|
"org/wiki/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 <https://docs.python.org/3/howto/unicode.html>."
|
|
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 <http://www.unicode.org> has character "
|
|
"charts, a glossary, and PDF versions of the Unicode specification. Be "
|
|
"prepared for some difficult reading. <http://www.unicode.org/history/> is a "
|
|
"chronology of the origin and development of Unicode."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://www.cs."
|
|
"tut.fi/~jkorpela/unicode/guide.html>."
|
|
msgstr ""
|
|
|
|
#: ../src/Doc/howto/unicode.rst:216
|
|
msgid ""
|
|
"Another good introductory article was written by Joel Spolsky <http://www."
|
|
"joelonsoftware.com/articles/Unicode.html>. If this introduction didn't make "
|
|
"things clear to you, you should try reading this alternate article before "
|
|
"continuing."
|
|
msgstr ""
|
|
|
|
#: ../src/Doc/howto/unicode.rst:223
|
|
msgid ""
|
|
"Wikipedia entries are often helpful; see the entries for \"character encoding"
|
|
"\" <http://en.wikipedia.org/wiki/Character_encoding> and UTF-8 <http://en."
|
|
"wikipedia.org/wiki/UTF-8>, for example."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://www.unicode."
|
|
"org/reports/tr44/#General_Category_Values> 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 <https://"
|
|
"downloads.egenix.com/python/Unicode-EPC2002-Talk.pdf>, 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 <https://downloads.egenix.com/"
|
|
"python/LSM2005-Developing-Unicode-aware-applications-in-Python.pdf> and "
|
|
"discuss questions of character encodings as well as how to internationalize "
|
|
"and localize an application."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://www.voidspace.org.uk/python/index.shtml>`_"
|
|
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 <http://www.voidspace.org.uk/"
|
|
"python/articles/urllib2_francais.shtml>`_."
|
|
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 <http://www.voidspace.org.uk/python/articles/"
|
|
"authentication.shtml>`_"
|
|
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 <http://www.w3.org/TR/"
|
|
"REC-html40/interact/forms.html#h-17.13>`_ 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 ""
|
|
|
|
#: ../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 <http://www.cs.tut.fi/~jkorpela/http."
|
|
"html>`_ 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 <http://www.voidspace.org.uk/python/articles/"
|
|
"authentication.shtml>`_."
|
|
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 <http://www.pyzine.com/Issue008/Section_Articles/article_CGIOne."
|
|
"html>`_."
|
|
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 <http://pygoogle.sourceforge.net>`_ 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 <http://"
|
|
"code.activestate.com/recipes/456195/>`_."
|
|
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 <https://wiki.python."
|
|
"org/moin/WebProgramming>`_ 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 <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 <https://wiki.python.org/"
|
|
"moin/CgiScripts>`_ 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 <http://httpd.apache.org/>`_, or Apache for short. Apache can "
|
|
"be easily installed on nearly every system using the system's package "
|
|
"management tool. `lighttpd <http://www.lighttpd.net>`_ is another "
|
|
"alternative and is said to have better performance. On many systems this "
|
|
"server can also be installed using the package management tool, so manually "
|
|
"compiling the web server may not be needed."
|
|
msgstr ""
|
|
|
|
#: ../src/Doc/howto/webservers.rst:143
|
|
msgid ""
|
|
"On Apache you can take a look at the `Dynamic Content with CGI <http://httpd."
|
|
"apache.org/docs/2.2/howto/cgi.html>`_ tutorial, where everything is "
|
|
"described. Most of the time it is enough just to set ``+ExecCGI``. The "
|
|
"tutorial also describes the most common gotchas that might arise."
|
|
msgstr ""
|
|
|
|
# 60997289570c43509daf0ed08881da82
|
|
#: ../src/Doc/howto/webservers.rst:148
|
|
msgid ""
|
|
"On lighttpd you need to use the `CGI module <http://redmine.lighttpd.net/"
|
|
"projects/lighttpd/wiki/Docs_ModCGI>`_\\ , which can be configured in a "
|
|
"straightforward way. It boils down to setting ``cgi.assign`` properly."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://modpython.org/>`_\\ , "
|
|
"because they think that this is the equivalent to ``mod_php``. Actually, "
|
|
"there are many differences. What ``mod_python`` does is embed the "
|
|
"interpreter into the Apache process, thus speeding up requests by not having "
|
|
"to start a Python interpreter for each request. On the other hand, it is "
|
|
"not \"Python intermixed with HTML\" in the way that PHP is often intermixed "
|
|
"with HTML. The Python equivalent of that is a template engine. "
|
|
"``mod_python`` itself is much more powerful and provides more access to "
|
|
"Apache internals. It can emulate CGI, work in a \"Python Server Pages\" "
|
|
"mode (similar to JSP) which is \"HTML intermingled with Python\", and it has "
|
|
"a \"Publisher\" which designates one file to accept all requests and decide "
|
|
"what to do with them."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://www.fastcgi.com/drupal/>`_ and "
|
|
"`mod_fcgid <http://httpd.apache.org/mod_fcgid/>`_. ``mod_fastcgi`` is the "
|
|
"original one, but it has some licensing issues, which is why it is sometimes "
|
|
"considered non-free. ``mod_fcgid`` is a smaller, compatible alternative. "
|
|
"One of these modules needs to be loaded by Apache."
|
|
msgstr ""
|
|
|
|
# 5d114d0b485c4eeb93c1488203ba552c
|
|
#: ../src/Doc/howto/webservers.rst:275
|
|
msgid ""
|
|
"lighttpd ships its own `FastCGI module <http://redmine.lighttpd.net/projects/"
|
|
"lighttpd/wiki/Docs_ModFastCGI>`_ as well as an `SCGI module <http://redmine."
|
|
"lighttpd.net/projects/lighttpd/wiki/Docs_ModSCGI>`_."
|
|
msgstr ""
|
|
|
|
#: ../src/Doc/howto/webservers.rst:279
|
|
msgid ""
|
|
"`nginx <http://nginx.org/>`_ also supports `FastCGI <http://wiki.nginx.org/"
|
|
"NginxSimplePythonFCGI>`_."
|
|
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 <https://"
|
|
"pypi.python.org/pypi/flup/1.0>`_ 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 <https://docs."
|
|
"djangoproject.com/en/dev/howto/deployment/fastcgi/>`_, most of which can be "
|
|
"reused for other WSGI-compliant frameworks and libraries. Only the ``manage."
|
|
"py`` part has to be changed, the example used here can be used instead. "
|
|
"Django does more or less the exact same thing."
|
|
msgstr ""
|
|
|
|
#: ../src/Doc/howto/webservers.rst:317
|
|
msgid "mod_wsgi"
|
|
msgstr ""
|
|
|
|
#: ../src/Doc/howto/webservers.rst:319
|
|
msgid ""
|
|
"`mod_wsgi <http://code.google.com/p/modwsgi/>`_ is an attempt to get rid of "
|
|
"the low level gateways. Given that FastCGI, SCGI, and mod_python are mostly "
|
|
"used to deploy WSGI applications, mod_wsgi was started to directly embed "
|
|
"WSGI applications into the Apache web server. mod_wsgi is specifically "
|
|
"designed to host WSGI applications. It makes the deployment of WSGI "
|
|
"applications much easier than deployment using other low level methods, "
|
|
"which need glue code. The downside is that mod_wsgi is limited to the "
|
|
"Apache web server; other servers would need their own implementations of "
|
|
"mod_wsgi."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://www.wsgi.org/en/latest/libraries.html>`_ already "
|
|
"available. For example, instead of writing your own session management "
|
|
"(HTTP is a stateless protocol, so to associate multiple HTTP requests with a "
|
|
"single user your application must create and manage such state via a "
|
|
"session), you can just download middleware which does that, plug it in, and "
|
|
"get on with coding the unique parts of your application. The same thing "
|
|
"with compression -- there is existing middleware which handles compressing "
|
|
"your HTML using gzip to save on your server's bandwidth. Authentication is "
|
|
"another a problem easily solved using existing middleware."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://en.wikipedia.org/"
|
|
"wiki/Apache_JServ_Protocol>`_. Some of these servers are written in Python, "
|
|
"as ``flup`` is, but there also exist others which are written in C and can "
|
|
"be used as drop-in replacements."
|
|
msgstr ""
|
|
|
|
#: ../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 "
|
|
"<http://www.wsgi.org/en/latest/index.html>`_, which contains an extensive "
|
|
"list of `WSGI servers <http://www.wsgi.org/en/latest/servers.html>`_ which "
|
|
"can be used by *any* application supporting WSGI."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://"
|
|
"moinmo.in/>`_. It was created in 2000, so it predates WSGI by about three "
|
|
"years. Older versions needed separate code to run on CGI, mod_python, "
|
|
"FastCGI and standalone."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://en.wikipedia.org/wiki/Model-view-controller>`_. 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 <https://wiki."
|
|
"python.org/moin/WebComponents>`_."
|
|
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 <http://www.makotemplates.org/>`_"
|
|
msgstr "`Mako <http://www.makotemplates.org/>`_"
|
|
|
|
#: ../src/Doc/howto/webservers.rst:521
|
|
msgid "`Genshi <http://genshi.edgewall.org/>`_"
|
|
msgstr "`Genshi <http://genshi.edgewall.org/>`_"
|
|
|
|
#: ../src/Doc/howto/webservers.rst:522
|
|
#, fuzzy
|
|
msgid "`Jinja <http://jinja.pocoo.org/>`_"
|
|
msgstr "`Jinja <http://jinja.pocoo.org/2/>`_"
|
|
|
|
# 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 <https://wiki."
|
|
"python.org/moin/Templating>`_ in the wiki lists a big, ever-growing number "
|
|
"of these. The three listed above are considered \"second generation\" "
|
|
"template engines and are a good place to start."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://www.mysql.com/>`_ or "
|
|
"`PostgreSQL <http://www.postgresql.org/>`_ are used because of their good "
|
|
"performance when handling very large databases consisting of millions of "
|
|
"entries. There is also a small database engine called `SQLite <http://www."
|
|
"sqlite.org/>`_, which is bundled with Python in the :mod:`sqlite3` module, "
|
|
"and which uses only one file. It has no other dependencies. For smaller "
|
|
"sites SQLite is just enough."
|
|
msgstr ""
|
|
|
|
#: ../src/Doc/howto/webservers.rst:549
|
|
msgid ""
|
|
"Relational databases are *queried* using a language called `SQL <http://en."
|
|
"wikipedia.org/wiki/SQL>`_. Python programmers in general do not like SQL "
|
|
"too much, as they prefer to work with objects. It is possible to save "
|
|
"Python objects into a database using a technology called `ORM <http://en."
|
|
"wikipedia.org/wiki/Object-relational_mapping>`_ (Object Relational "
|
|
"Mapping). ORM translates all object-oriented access into SQL code under the "
|
|
"hood, so the developer does not need to think about it. Most `frameworks`_ "
|
|
"use ORMs, and it works quite well."
|
|
msgstr ""
|
|
|
|
#: ../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 <https://wiki.python.org/moin/PersistenceTools>`_ lists "
|
|
"possibilities on how to save data in the file system. Some of these modules "
|
|
"are part of the standard library"
|
|
msgstr ""
|
|
|
|
# b9b6ac249fc14aa9997f3ba4bab579ce
|
|
#: ../src/Doc/howto/webservers.rst:582
|
|
msgid ""
|
|
"`Database Programming <https://wiki.python.org/moin/DatabaseProgramming>`_ "
|
|
"helps with choosing a method for saving data"
|
|
msgstr ""
|
|
|
|
#: ../src/Doc/howto/webservers.rst:585
|
|
msgid ""
|
|
"`SQLAlchemy <http://www.sqlalchemy.org/>`_, the most powerful OR-Mapper for "
|
|
"Python, and `Elixir <http://elixir.ematia.de/>`_, which makes SQLAlchemy "
|
|
"easier to use"
|
|
msgstr ""
|
|
|
|
#: ../src/Doc/howto/webservers.rst:589
|
|
msgid "`SQLObject <http://www.sqlobject.org/>`_, another popular OR-Mapper"
|
|
msgstr ""
|
|
|
|
#: ../src/Doc/howto/webservers.rst:591
|
|
msgid ""
|
|
"`ZODB <https://launchpad.net/zodb>`_ and `Durus <http://www.mems-exchange."
|
|
"org/software/durus/>`_, two object oriented databases"
|
|
msgstr ""
|
|
|
|
#: ../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 <https://www.djangoproject.com/>`_ is a framework consisting of "
|
|
"several tightly coupled elements which were written from scratch and work "
|
|
"together very well. It includes an ORM which is quite powerful while being "
|
|
"simple to use, and has a great online administration interface which makes "
|
|
"it possible to edit the data in the database with a browser. The template "
|
|
"engine is text-based and is designed to be usable for page designers who "
|
|
"cannot write Python. It supports template inheritance and filters (which "
|
|
"work like Unix pipes). Django has many handy features bundled, such as "
|
|
"creation of RSS feeds or generic views, which make it possible to create web "
|
|
"sites almost without writing any Python code."
|
|
msgstr ""
|
|
|
|
# 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 <https://docs.djangoproject.com/>`_ and the `Django "
|
|
"book <http://www.djangobook.com/>`_."
|
|
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 <https://docs."
|
|
"djangoproject.com/en/dev/faq/general/#django-appears-to-be-a-mvc-framework-"
|
|
"but-you-call-the-controller-the-view-and-the-view-the-template-how-come-you-"
|
|
"don-t-use-the-standard-names>`_."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://www."
|
|
"turbogears.org/>`_. TurboGears takes the approach of using already existing "
|
|
"components and combining them with glue code to create a seamless "
|
|
"experience. TurboGears gives the user flexibility in choosing components. "
|
|
"For example the ORM and template engine can be changed to use packages "
|
|
"different from those used by default."
|
|
msgstr ""
|
|
|
|
#: ../src/Doc/howto/webservers.rst:678
|
|
msgid ""
|
|
"The documentation can be found in the `TurboGears wiki <http://docs."
|
|
"turbogears.org/>`_, where links to screencasts can be found. TurboGears has "
|
|
"also an active user community which can respond to most related questions. "
|
|
"There is also a `TurboGears book <http://turbogearsbook.com/>`_ published, "
|
|
"which is a good starting point."
|
|
msgstr ""
|
|
|
|
# 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 <http://www.pylonsproject.org/>`_."
|
|
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 <https://launchpad.net/zodb>`_ (Zope Object "
|
|
"Database). Because of its highly integrated nature, Zope wound up in a "
|
|
"somewhat isolated ecosystem: code written for Zope wasn't very usable "
|
|
"outside of Zope, and vice-versa. To solve this problem the Zope 3 effort "
|
|
"was started. Zope 3 re-engineers Zope as a set of more cleanly isolated "
|
|
"components. This effort was started before the advent of the WSGI standard, "
|
|
"but there is WSGI support for Zope 3 from the `Repoze <http://repoze.org/>`_ "
|
|
"project. Zope components have many years of production use behind them, and "
|
|
"the Zope 3 project gives access to these components to the wider Python "
|
|
"community. There is even a separate framework based on the Zope components: "
|
|
"`Grok <http://grok.zope.org/>`_."
|
|
msgstr ""
|
|
|
|
# 3d48b3d82e154f6ab37bb1041e751122
|
|
#: ../src/Doc/howto/webservers.rst:708
|
|
msgid ""
|
|
"Zope is also the infrastructure used by the `Plone <https://plone.org/>`_ "
|
|
"content management system, one of the most powerful and popular content "
|
|
"management systems available."
|
|
msgstr ""
|
|
|
|
#: ../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 <http://pythonpaste.org/>`_, 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 <https://wiki."
|
|
"python.org/moin/WebFrameworks>`_."
|
|
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 <https://wiki.python."
|
|
"org/moin/PoundPythonWeb>`_."
|
|
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"
|