diff -r 85f290e474e2 build/.buildinfo --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/.buildinfo Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: ff002fe3fb4d67cf9f7514eb72352e1d +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff -r 85f290e474e2 build/.doctrees/buildbots.doctree Binary file build/.doctrees/buildbots.doctree has changed diff -r 85f290e474e2 build/.doctrees/clang.doctree Binary file build/.doctrees/clang.doctree has changed diff -r 85f290e474e2 build/.doctrees/committing.doctree Binary file build/.doctrees/committing.doctree has changed diff -r 85f290e474e2 build/.doctrees/communication.doctree Binary file build/.doctrees/communication.doctree has changed diff -r 85f290e474e2 build/.doctrees/compiler.doctree Binary file build/.doctrees/compiler.doctree has changed diff -r 85f290e474e2 build/.doctrees/coredev.doctree Binary file build/.doctrees/coredev.doctree has changed diff -r 85f290e474e2 build/.doctrees/coverage.doctree Binary file build/.doctrees/coverage.doctree has changed diff -r 85f290e474e2 build/.doctrees/coverity.doctree Binary file build/.doctrees/coverity.doctree has changed diff -r 85f290e474e2 build/.doctrees/devcycle.doctree Binary file build/.doctrees/devcycle.doctree has changed diff -r 85f290e474e2 build/.doctrees/developers.doctree Binary file build/.doctrees/developers.doctree has changed diff -r 85f290e474e2 build/.doctrees/docquality.doctree Binary file build/.doctrees/docquality.doctree has changed diff -r 85f290e474e2 build/.doctrees/documenting.doctree Binary file build/.doctrees/documenting.doctree has changed diff -r 85f290e474e2 build/.doctrees/emacs.doctree Binary file build/.doctrees/emacs.doctree has changed diff -r 85f290e474e2 build/.doctrees/environment.pickle Binary file build/.doctrees/environment.pickle has changed diff -r 85f290e474e2 build/.doctrees/experts.doctree Binary file build/.doctrees/experts.doctree has changed diff -r 85f290e474e2 build/.doctrees/faq.doctree Binary file build/.doctrees/faq.doctree has changed diff -r 85f290e474e2 build/.doctrees/fixingissues.doctree Binary file build/.doctrees/fixingissues.doctree has changed diff -r 85f290e474e2 build/.doctrees/gdb.doctree Binary file build/.doctrees/gdb.doctree has changed diff -r 85f290e474e2 build/.doctrees/grammar.doctree Binary file build/.doctrees/grammar.doctree has changed diff -r 85f290e474e2 build/.doctrees/help.doctree Binary file build/.doctrees/help.doctree has changed diff -r 85f290e474e2 build/.doctrees/index.doctree Binary file build/.doctrees/index.doctree has changed diff -r 85f290e474e2 build/.doctrees/langchanges.doctree Binary file build/.doctrees/langchanges.doctree has changed diff -r 85f290e474e2 build/.doctrees/patch.doctree Binary file build/.doctrees/patch.doctree has changed diff -r 85f290e474e2 build/.doctrees/runtests.doctree Binary file build/.doctrees/runtests.doctree has changed diff -r 85f290e474e2 build/.doctrees/setup.doctree Binary file build/.doctrees/setup.doctree has changed diff -r 85f290e474e2 build/.doctrees/setupWindows.doctree Binary file build/.doctrees/setupWindows.doctree has changed diff -r 85f290e474e2 build/.doctrees/silencewarnings.doctree Binary file build/.doctrees/silencewarnings.doctree has changed diff -r 85f290e474e2 build/.doctrees/stdlibchanges.doctree Binary file build/.doctrees/stdlibchanges.doctree has changed diff -r 85f290e474e2 build/.doctrees/tracker.doctree Binary file build/.doctrees/tracker.doctree has changed diff -r 85f290e474e2 build/.doctrees/triaging.doctree Binary file build/.doctrees/triaging.doctree has changed diff -r 85f290e474e2 build/_sources/buildbots.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/buildbots.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,208 @@ +.. _buildbots: + +Continuous Integration +====================== + +To assert that there are no regressions in the :doc:`development and maintenance +branches `, Python has a set of dedicated machines (called *buildbots* or +*build slaves*) used for continuous integration. They span a number of +hardware/operating system combinations. Furthermore, each machine hosts +several *builders*, one per active branch: when a new change is pushed +to this branch on the public Mercurial repository, all corresponding builders +will schedule a new build to be run as soon as possible. + +The build steps run by the buildbots are the following: + +* Checkout of the source tree for the changeset which triggered the build +* Compiling Python +* Running the test suite using :ref:`strenuous settings ` +* Cleaning up the build tree + +It is your responsibility, as a core developer, to check the automatic +build results after you push a change to the repository. It is therefore +important that you get acquainted with the way these results are presented, +and how various kinds of failures can be explained and diagnosed. + +Checking results of automatic builds +------------------------------------ + +There are two ways of visualizing recent build results: + +* The Web interface for each branch at http://python.org/dev/buildbot/, + where the so-called "waterfall" view presents a vertical rundown of recent + builds for each builder. When interested in one build, you'll have to + click on it to know which changesets it corresponds to. + +* The command-line ``bbreport.py`` client, which you can get from + http://code.google.com/p/bbreport/. Installing it is trivial: just add + the directory containing ``bbreport.py`` to your system path so that + you can run it from any filesystem location. For example, if you want + to display the latest build results on the development ("default") branch, + type:: + + bbreport.py -q 3.x + +Some buildbots are much faster than others. Over time, you will learn which +ones produce the quickest results after a build, and which ones take the +longest time. + +Also, when several changesets are pushed in a quick succession in the same +branch, it often happens that a single build is scheduled for all these +changesets. + +Stability +--------- + +A subset of the buildbots are marked "stable". They are taken into account +when making a new release. The rule is that all stable builders must be free of +persistent failures when the release is cut. It is absolutely **vital** +that core developers fix any issue they introduce on the stable buildbots, +as soon as possible. + +This does not mean that other builders' test results can be taken lightly, +either. Some of them are known for having platform-specific issues that +prevent some tests from succeeding (or even terminating at all), but +introducing additional failures should generally not be an option. + +Flags-dependent failures +------------------------ + +Sometimes, while you have run the :doc:`whole test suite ` before +committing, you may witness unexpected failures on the buildbots. One source +of such discrepancies is if different flags have been passed to the test runner +or to Python itself. To reproduce, make sure you use the same flags as the +buildbots: they can be found out simply by clicking the **stdio** link for +the failing build's tests. For example:: + + ./python.exe -Wd -E -bb ./Lib/test/regrtest.py -uall -rwW + +.. note:: + Running ``Lib/test/regrtest.py`` is exactly equivalent to running + ``-m test``. + +Ordering-dependent failures +--------------------------- + +Sometimes even the failure is subtler, as it relies on the order in which +the tests are run. The buildbots *randomize* test order (by using the ``-r`` +option to the test runner) to maximize the probability that potential +interferences between library modules are exercised; the downside is that it +can make for seemingly sporadic failures. + +The ``--randseed`` option makes it easy to reproduce the exact randomization +used in a given build. Again, open the ``stdio`` link for the failing test +run, and check the beginning of the test output proper. + +Let's assume, for the sake of example, that the output starts with:: + + ./python -Wd -E -bb Lib/test/regrtest.py -uall -rwW + == CPython 3.3a0 (default:22ae2b002865, Mar 30 2011, 13:58:40) [GCC 4.4.5] + == Linux-2.6.36-gentoo-r5-x86_64-AMD_Athlon-tm-_64_X2_Dual_Core_Processor_4400+-with-gentoo-1.12.14 little-endian + == /home/buildbot/buildarea/3.x.ochtman-gentoo-amd64/build/build/test_python_29628 + Testing with flags: sys.flags(debug=0, inspect=0, interactive=0, optimize=0, dont_write_bytecode=0, no_user_site=0, no_site=0, ignore_environment=1, verbose=0, bytes_warning=2, quiet=0) + Using random seed 2613169 + [ 1/353] test_augassign + [ 2/353] test_functools + +You can reproduce the exact same order using:: + + ./python -Wd -E -bb -m test -uall -rwW --randseed 2613169 + +It will run the following sequence (trimmed for brevity):: + + [ 1/353] test_augassign + [ 2/353] test_functools + [ 3/353] test_bool + [ 4/353] test_contains + [ 5/353] test_compileall + [ 6/353] test_unicode + +If this is enough to reproduce the failure on your setup, you can then +bisect the test sequence to look for the specific interference causing the +failure. Copy and paste the test sequence in a text file, then use the +``--fromfile`` (or ``-f``) option of the test runner to run the exact +sequence recorded in that text file:: + + ./python -Wd -E -bb -m test -uall -rwW --fromfile mytestsequence.txt + +In the example sequence above, if ``test_unicode`` had failed, you would +first test the following sequence:: + + [ 1/353] test_augassign + [ 2/353] test_functools + [ 3/353] test_bool + [ 6/353] test_unicode + +And, if it succeeds, the following one instead (which, hopefully, shall +fail):: + + [ 4/353] test_contains + [ 5/353] test_compileall + [ 6/353] test_unicode + +Then, recursively, narrow down the search until you get a single pair of +tests which triggers the failure. It is very rare that such an interference +involves more than **two** tests. If this is the case, we can only wish you +good luck! + +.. note:: + You cannot use the ``-j`` option (for parallel testing) when diagnosing + ordering-dependent failures. Using ``-j`` isolates each test in a + pristine subprocess and, therefore, prevents you from reproducing any + interference between tests. + + +Transient failures +------------------ + +While we try to make the test suite as reliable as possible, some tests do +not reach a perfect level of reproducibility. Some of them will sometimes +display spurious failures, depending on various conditions. Here are common +offenders: + +* Network-related tests, such as ``test_poplib``, ``test_urllibnet``, etc. + Their failures can stem from adverse network conditions, or imperfect + thread synchronization in the test code, which often has to run a + server in a separate thread. + +* Tests dealing with delicate issues such as inter-thread or inter-process + synchronization, or Unix signals: ``test_multiprocessing``, + ``test_threading``, ``test_subprocess``, ``test_threadsignals``. + +When you think a failure might be transient, it is recommended you confirm by +waiting for the next build. Still, even if the failure does turn out sporadic +and unpredictable, the issue should be reported on the bug tracker; even +better if it can be diagnosed and suppressed by fixing the test's implementation, +or by making its parameters - such as a timeout - more robust. + + +Custom builders +--------------- + +When working on a long-lived feature branch, or on a bugfix branch which +enables issue-specific debugging, you will probably want to test your +work on one or several buildbots. Since your work is hosted in a distinct +repository, you can't trigger builds on the regular builders. Instead, +you have to use one of the `custom builders +`_. + +When creating ("forcing") a build on a custom builder, you have to provide +at least two parameters: + +* The repository path, relative to http://hg.python.org. For example, + ``sandbox/myfixes`` if ``http://hg.python.org/sandbox/myfixes`` is the + full path to the repository. + +* The Mercurial id of the changeset you want to build. To make things less + tedious, we suggest you do your changes in a separate named branch: you can + then supply the branch name instead of a specific changeset id. + +If you are interested in the results of a specific test file only, we +recommend you change (temporarily, of course) the contents of the +``buildbottest`` clause in ``Makefile.pre.in``; or, for Windows builders, +the ``Tools/buildbot/test.bat`` and ``Tools/buildbot/test-amd64.bat`` +scripts. + +.. note:: + For security reasons, it is impossible to build repositories from outside + the http://hg.python.org realm. diff -r 85f290e474e2 build/_sources/clang.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/clang.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,338 @@ +********************************** + Dynamic Analysis with Clang +********************************** + +This document describes how to use Clang to perform analysis on Python and its +libraries. In addition to performing the analysis, the document will cover +downloading, building and installing the the latest Clang/LLVM combination +(which is currently 3.4). + +This document does not cover interpreting the findings. For a discussion of +interpreting results, see Marshall Clow's `Testing libc++ with +-fsanitize=undefined `_. The +blog posting is a detailed examinations of issues uncovered by Clang in +``libc++``. + +What is Clang? +============== + +Clang is the C, C++ and Objective C front-end for the LLVM compiler. The +front-end provides access to LLVM's optimizer and code generator. The +sanitizers - or checkers - are hooks into the code generation phase to +instrument compiled code so suspicious behavior is flagged. + +What are Sanitizers? +==================== + +Clang sanitizers are runtime checkers used to identify suspicious and undefined +behavior. The checking occurs at runtime with actual runtime parameters so false +positives are kept to a minimum. + +There are a number of sanitizers available, but two that should be used on a +regular basis are the Address Sanitizer (or ASan) and the Undefined Behavior +Sanitizer (or UBSan). ASan is invoked with the compiler option +``-fsanitize=address``, and UBSan is invoked with ``-fsanitize=undefined``. The +flags are passed through ``CFLAGS`` and ``CXXFLAGS``, and sometimes through +``CC`` and ``CXX`` (in addition to the compiler). + +A complete list of sanitizers can be found at `Controlling Code Generation +`_. + +.. note:: + + Because sanitizers operate at runtime on real program parameters, its + important to provide a complete set of positive and negative self tests. + +Clang and its sanitizers have strengths (and weaknesses). Its just one tool in +the war chest to uncovering bugs and improving code quality. Clang should be +used to compliment other methods, including Code Reviews, Valgrind, Coverity, +etc. + +Clang/LLVM Setup +================ + +This portion of the document covers downloading, building and installing Clang +and LLVM. There are three components to download and build. They are the LLVM +compiler, the compiler front end and the compiler runtime library. + +In preparation you should create a scratch directory. Also ensure you are using +Python 2 and not Python 3. Python 3 will cause the build to fail. + +Download, Build and Install +--------------------------- + +Perform the following to download, build and install the Clang/LLVM 3.4. :: + + # Download + wget http://llvm.org/releases/3.4/llvm-3.4.src.tar.gz + wget http://llvm.org/releases/3.4/clang-3.4.src.tar.gz + wget http://llvm.org/releases/3.4/compiler-rt-3.4.src.tar.gz + + # LLVM + tar xvf llvm-3.4.src.tar.gz + cd llvm-3.4/tools + + # Clang Front End + tar xvf ../../clang-3.4.src.tar.gz + mv clang-3.4 clang + + # Compiler RT + cd ../projects + tar xvf ../../compiler-rt-3.4.src.tar.gz + mv compiler-rt-3.4/ compiler-rt + + # Build + cd .. + ./configure --enable-optimized --prefix=/usr/local + make -j4 + sudo make install + +.. note:: + + If you receive an error ``'LibraryDependencies.inc' file not found``, then + ensure you are utilizing Python 2 and not Python 3. If you encounter the + error after switching to Python 2, then delete everything and start over. + +After ``make install`` executes, the compilers will be installed in +``/usr/local/bin`` and the various libraries will be installed in +``/usr/local/lib/clang/3.4/lib/linux/``: :: + + $ ls /usr/local/lib/clang/3.4/lib/linux/ + libclang_rt.asan-x86_64.a libclang_rt.profile-x86_64.a + libclang_rt.dfsan-x86_64.a libclang_rt.san-x86_64.a + libclang_rt.full-x86_64.a libclang_rt.tsan-x86_64.a + libclang_rt.lsan-x86_64.a libclang_rt.ubsan_cxx-x86_64.a + libclang_rt.msan-x86_64.a libclang_rt.ubsan-x86_64.a + +On Mac OS X, the libraries are installed in +``/usr/local/lib/clang/3.3/lib/darwin/``: :: + + $ ls /usr/local/lib/clang/3.3/lib/darwin/ + libclang_rt.10.4.a libclang_rt.ios.a + libclang_rt.asan_osx.a libclang_rt.osx.a + libclang_rt.asan_osx_dynamic.dylib libclang_rt.profile_ios.a + libclang_rt.cc_kext.a libclang_rt.profile_osx.a + libclang_rt.cc_kext_ios5.a libclang_rt.ubsan_osx.a + libclang_rt.eprintf.a + +.. note:: + + You should never have to add the libraries to a project. Clang will handle + it for you. If you find you cannot pass the ``-fsanitize=XXX`` flag through + ``make``'s implicit variables (``CFLAGS``, ``CXXFLAGS``, ``CC``, + ``CXXFLAGS``, ``LDFLAGS``) during ``configure``, then you should modify the + makefile after configuring to ensure the flag is passed through the + compiler. + +The installer does not install all the components needed on occasion. For +example, you might want to run a ``scan-build`` or examine the results with +``scan-veiw``. You can copy the components by hand with: :: + + sudo mkdir /usr/local/bin/scan-build + sudo cp -r llvm-3.4/tools/clang/tools/scan-build /usr/local/bin + sudo mkdir /usr/local/bin/scan-view + sudo cp -r llvm-3.4/tools/clang/tools/scan-view /usr/local/bin + +.. note:: + + Because the installer does not install all the components needed on + occasion, you should not delete the scratch directory until you are sure + things work as expected. If a library is missing, then you should search for + it in the Clang/LLVM build directory. + +Python Build Setup +================== + +This portion of the document covers invoking Clang and LLVM with the options +required so the sanitizers analyze Python with under its test suite. Two +checkers are used - ASan and UBSan. + +Because the sanitizers are runtime checkers, its best to have as many positive +and negative self tests as possible. You can never have enough self tests. + +The general idea is to compile and link with the sanitizer flags. At link time, +Clang will include the needed runtime libraries. However, you can't use +``CFLAGS`` and ``CXXFLAGS`` to pass the options through the compiler to the +linker because the makefile rules for ``BUILDPYTHON``, ``_testembed`` and +``_freeze_importlib`` don't use the implicit variables. + +As a workaround to the absence of flags to the linker, you can pass the +sanitizer options by way of the compilers - ``CC`` and ``CXX``. Passing the +flags though the compiler is used below, but passing them through ``LDFLAGS`` is +also reported to work. + +Building Python +--------------- + +To begin, export the variables of interest with the desired sanitizers. Its OK +to specify both sanitizers: :: + + # ASan + export CC="/usr/local/bin/clang -fsanitize=address" + export CXX="/usr/local/bin/clang++ -fsanitize=address -fno-sanitize=vptr" + +Or: :: + + # UBSan + export CC="/usr/local/bin/clang -fsanitize=undefined" + export CXX="/usr/local/bin/clang++ -fsanitize=undefined -fno-sanitize=vptr" + +The ``-fno-sanitize=vptr`` removes vtable checks that are part of UBSan from C++ +projects due to noise. Its not needed with Python, but you will likely need it +for other C++ projects. + +After exporting ``CC`` and ``CXX``, ``configure`` as normal: :: + + $ ./configure + checking build system type... x86_64-unknown-linux-gnu + checking host system type... x86_64-unknown-linux-gnu + checking for --enable-universalsdk... no + checking for --with-universal-archs... 32-bit + checking MACHDEP... linux + checking for --without-gcc... no + checking for gcc... /usr/local/bin/clang -fsanitize=undefined + checking whether the C compiler works... yes + ... + +Next is a standard ``make`` (formatting added for clarity): :: + + $ make + /usr/local/bin/clang -fsanitize=undefined -c -Wno-unused-result + -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes -I. + -IInclude -I./Include -DPy_BUILD_CORE -o Modules/python.o + ./Modules/python.c + /usr/local/bin/clang -fsanitize=undefined -c -Wno-unused-result + -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes -I. + -IInclude -I./Include -DPy_BUILD_CORE -o Parser/acceler.o + Parser/acceler.c + ... + +Finally is ``make test`` (formatting added for clarity): :: + + Objects/longobject.c:39:42: runtime error: index -1 out of bounds + for type 'PyLongObject [262]' + Objects/tupleobject.c:188:13: runtime error: member access within + misaligned address 0x2b76be018078 for type 'PyGC_Head' (aka + 'union _gc_head'), which requires 16 byte alignment + 0x2b76be018078: note: pointer points here + 00 00 00 00 40 53 5a b6 76 2b 00 00 60 52 5a b6 ... + ^ + ... + +If you are using the address sanitizer, its important to pipe the output through +``asan_symbolize.py`` to get a good trace. For example, from Issue 20953 during +compile (formatting added for clarity): :: + + $ make test 2>&1 | asan_symbolize.py + ... + + /usr/local/bin/clang -fsanitize=address -Xlinker -export-dynamic + -o python Modules/python.o libpython3.3m.a -ldl -lutil + /usr/local/ssl/lib/libssl.a /usr/local/ssl/lib/libcrypto.a -lm + ./python -E -S -m sysconfig --generate-posix-vars + ================================================================= + ==24064==ERROR: AddressSanitizer: heap-buffer-overflow on address + 0x619000004020 at pc 0x4ed4b2 bp 0x7fff80fff010 sp 0x7fff80fff008 + READ of size 4 at 0x619000004020 thread T0 + #0 0x4ed4b1 in PyObject_Free Python-3.3.5/./Objects/obmalloc.c:987 + #1 0x7a2141 in code_dealloc Python-3.3.5/./Objects/codeobject.c:359 + #2 0x620c00 in PyImport_ImportFrozenModuleObject + Python-3.3.5/./Python/import.c:1098 + #3 0x620d5c in PyImport_ImportFrozenModule + Python-3.3.5/./Python/import.c:1114 + #4 0x63fd07 in import_init Python-3.3.5/./Python/pythonrun.c:206 + #5 0x63f636 in _Py_InitializeEx_Private + Python-3.3.5/./Python/pythonrun.c:369 + #6 0x681d77 in Py_Main Python-3.3.5/./Modules/main.c:648 + #7 0x4e6894 in main Python-3.3.5/././Modules/python.c:62 + #8 0x2abf9a525eac in __libc_start_main + /home/aurel32/eglibc/eglibc-2.13/csu/libc-start.c:244 + #9 0x4e664c in _start (Python-3.3.5/./python+0x4e664c) + + AddressSanitizer can not describe address in more detail (wild + memory access suspected). + SUMMARY: AddressSanitizer: heap-buffer-overflow + Python-3.3.5/./Objects/obmalloc.c:987 PyObject_Free + Shadow bytes around the buggy address: + 0x0c327fff87b0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa + 0x0c327fff87c0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa + 0x0c327fff87d0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa + 0x0c327fff87e0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa + 0x0c327fff87f0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa + =>0x0c327fff8800: fa fa fa fa[fa]fa fa fa fa fa fa fa fa fa fa fa + 0x0c327fff8810: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa + 0x0c327fff8820: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa + 0x0c327fff8830: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa + 0x0c327fff8840: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa + 0x0c327fff8850: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa + Shadow byte legend (one shadow byte represents 8 application bytes): + Addressable: 00 + Partially addressable: 01 02 03 04 05 06 07 + Heap left redzone: fa + Heap right redzone: fb + Freed heap region: fd + Stack left redzone: f1 + Stack mid redzone: f2 + Stack right redzone: f3 + Stack partial redzone: f4 + Stack after return: f5 + Stack use after scope: f8 + Global redzone: f9 + Global init order: f6 + Poisoned by user: f7 + ASan internal: fe + ==24064==ABORTING + make: *** [pybuilddir.txt] Error 1 + +.. note:: + + ``asan_symbolize.py`` is supposed to be installed during ``make install``. + If its not installed, then look in the Clang/LLVM build directory for it and + copy it to ``/usr/local/bin``. + +Blacklisting (Ignoring) Findings +-------------------------------- + +Clang allows you to alter the behavior of sanitizer tools for certain +source-level by providing a special blacklist file at compile-time. The +blacklist is needed because it reports every instance of an issue, even if the +issue is reported 10's of thousands of time in un-managed library code. + +You specify the blacklist with ``-fsanitize-blacklist=XXX``. For example: :: + + -fsanitize-blacklist=my_blacklist.txt + +``my_blacklist.txt`` would then contain entries such as the following. The entry +will ignore a bug in ``libc++``'s ``ios`` formatting functions: :: + + fun:_Ios_Fmtflags + +As an example with Python 3.4.0, ``audioop.c`` will produce a number of +findings: :: + + ./Modules/audioop.c:422:11: runtime error: left shift of negative value -1 + ./Modules/audioop.c:446:19: runtime error: left shift of negative value -1 + ./Modules/audioop.c:476:19: runtime error: left shift of negative value -1 + ./Modules/audioop.c:504:16: runtime error: left shift of negative value -1 + ./Modules/audioop.c:533:22: runtime error: left shift of negative value -128 + ./Modules/audioop.c:775:19: runtime error: left shift of negative value -70 + ./Modules/audioop.c:831:19: runtime error: left shift of negative value -70 + ./Modules/audioop.c:881:19: runtime error: left shift of negative value -1 + ./Modules/audioop.c:920:22: runtime error: left shift of negative value -70 + ./Modules/audioop.c:967:23: runtime error: left shift of negative value -70 + ./Modules/audioop.c:968:23: runtime error: left shift of negative value -70 + ... + +One of the function of interest is ``audioop_getsample_impl`` (flagged at line +422), and the blacklist entry would include: :: + + fun:audioop_getsample_imp + +Or, you could ignore the entire file with: :: + + src:Modules/audioop.c + +Unfortunately, you won't know what to blacklist until you run the sanitizer. + +The documentation is available at `Sanitizer special case list +`_. diff -r 85f290e474e2 build/_sources/committing.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/committing.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,577 @@ +.. _committing: + +Committing and Pushing Changes +============================== + +Is the change ready for committing? +----------------------------------- + +Before a change is committed, you must make sure it is ready to enter the +public source tree. Draft commits are prohibited. Therefore, you must +ensure your changes fulfill several mandatory criteria. + +.. note:: + If you want to share your work-in-progress code on a feature or bugfix, + either publish patches or create a public fork of the repository. + + +Does the test suite still pass? +''''''''''''''''''''''''''''''' + +You must :ref:`run the whole test suite ` to ensure that it +passes before pushing any code changes. + +.. note:: + You really need to run the **entire** test suite. Running a single test + is not enough as your changes may have unforeseen effects on other tests + or library modules. + + Running the entire test suite doesn't guarantee that your changes + will pass the :ref:`continuous integration ` tests, as those + will exercise more possibilities still (such as different platforms or + build options). But it will at least catch non-build specific, + non-platform specific errors, therefore minimizing the chance for + breakage. + +Patch checklist +''''''''''''''' + +Apart from running the tests, there's a simple patch checklist that +``make patchcheck`` (or ``./python.exe Tools/scripts/patchcheck.py`` on +Windows) will run through: + +* Are there any whitespace problems in Python files? + (using ``Tools/scripts/reindent.py``) +* Are there any whitespace problems in C files? +* Are there any whitespace problems in the documentation? + (using ``Tools/scripts/reindent-rst.py``) +* Has the documentation been updated? +* Has the test suite been updated? +* Has ``Misc/NEWS`` been updated? +* Has ``Misc/ACKS`` been updated? +* Has ``configure`` been regenerated, if necessary? +* Has ``pyconfig.h.in`` been regenerated, if necessary? + +Note that the automated patch check can't actually *answer* all of these +questions, and even if it could, it still wouldn't know whether or not +those answers were appropriate. Aside from the whitespace checks, it is just +a memory aid to help with remembering the various elements that can go into +making a complete patch. + + +Commit Style +------------ + +Once a change patch is ready and tested, it can be committed to the repository. +We usually prefer to put a whole feature or bugfix into a single commit, but no +more. In particular: + +* Do **not** fix more than one issue in the same commit (except, of course, if + one code change fixes all of them). +* Do **not** do cosmetic changes to unrelated code in the same commit as some + feature/bugfix. + +It is of course okay to pile up several commits to one branch and merge them +into another in one merge commit. + + +Handling Others' Code +--------------------- + +As a core developer you will occasionally want to commit a patch created by +someone else. When doing so you will want to make sure of some things. + +First, make sure the patch is in a good state. Both :ref:`patch` and +:ref:`helptriage` +explain what is to be expected of a patch. Typically patches that get cleared by +triagers are good to go except maybe lacking ``Misc/ACKS`` and ``Misc/NEWS`` +entries. + +Second, make sure the patch does not break backwards-compatibility without a +good reason. This means :ref:`running the entire test suite ` to +make sure everything still passes. It also means that if semantics do change +there must be a good reason for the breakage of code the change will cause +(and it **will** break someone's code). If you are unsure if the breakage +is worth it, ask on python-dev. + +Third, ensure the patch is attributed correctly by adding the contributor's +name to ``Misc/ACKS`` if they aren't already there (and didn't add themselves +in their patch) and by mentioning "Patch by " in the ``Misc/NEWS`` entry +and the checkin message. If the patch has been heavily modified then "Initial +patch by " is an appropriate alternate wording. + +If you omit correct attribution in the initial checkin, then update ``ACKS`` +and ``NEWS`` in a subsequent checkin (don't worry about trying to fix the +original checkin message in that case). + +Finally, especially for larger patches, check if the submitter of the +patch has a CLA in place (indicated by an asterisk following their username +in the issue tracker). If the asterisk is missing and the patch is +non-trivial, direct them to the electronic `Contributor Licensing Agreement`_ +to ensure the PSF has the appropriate authorizations in place to relicense +and redistribute their code. + + +Contributor Licensing Agreements +-------------------------------- + +It's unlikely bug fixes will require a `Contributor Licensing Agreement`_ +unless they touch a *lot* of code. For new features, it is preferable to +ask that the contributor submit a signed CLA to the PSF as the associated +comments, docstrings and documentation are far more likely to reach a +copyrightable standard. + +These days, the CLA can be signed electronically through the form linked +above, and this process is strongly preferred to the old mechanism that +involved sending a scanned copy of the signed paper form. + +As discussed on the PSF Contribution_ page, it is the CLA itself that gives +the PSF the necessary relicensing rights to redistribute contributions under +the Python license stack. This is an additional permission granted above and +beyond the normal permissions provided by the chosen open source license. + +Some developers may object to the relicensing permissions granted to the PSF +by the CLA. They're entirely within their rights to refuse to sign the CLA +on that basis, but that refusal *does* mean we can't accept their patches +for inclusion. + +.. _Contribution: http://www.python.org/psf/contrib/ +.. _Contributor Licensing Agreement: + http://www.python.org/psf/contrib/contrib-form/ + + +NEWS Entries +------------ + +Almost all changes made to the code base deserve an entry in ``Misc/NEWS``. +If the change is particularly interesting for end users (e.g. new features, +significant improvements, or backwards-incompatible changes), an entry in +the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added +as well. There are two notable exceptions to this general principle, and they +both relate to changes that *already* have a NEWS entry, and have not yet +been included in any formal release (including alpha and beta releases). +These exceptions are: + +* If a change is reverted prior to release, then the corresponding entry + is simply removed. Otherwise, a new entry must be added noting that the + change has been reverted (e.g. when a feature is released in an alpha and + then cut prior to the first beta). + +* If a change is a fix (or other adjustment) to an earlier unreleased change + and the original NEWS entry remains valid, then no additional entry is + needed. + +New NEWS entries are customarily added at or near the top of their +respective sections, so that entries within a section appear in approximate +order from newest to oldest. However, this is customary and not a +requirement. + +The NEWS file is now read by Sphinx to produce the "Changelog" page; accordingly +it should be valid reStructuredText. The "default role" (single backticks) can +be used to refer to objects in the documentation. Example NEWS entry:: + + - Issue #15304: Fix warning message when `os.chdir()` fails inside + `test.support.temp_cwd()`. Patch by Chris Jerdonek. + +(In all other ``.rst`` files, the single backticks should not be used. They are +allowed here because NEWS is meant to be as readable as possible unprocessed.) + +A nice trick to make Mercurial’s automatic file merge work more smoothly is to +put a new entry after the first or first two entries rather than at the very +top. This way if you commit, pull new changesets and merge, the merge will +succeed automatically. + + +Commit Messages +--------------- + +Every commit has a commit message to document why a change was made and to +communicate that reason to other core developers. Python core developers have +developed a standard way of formatting commit messages that everyone is +expected to follow. + +Our usual convention mimics that used in the ``Misc/NEWS`` file. Actually, +it is common to simply paste the NEWS entry into the commit message. Here +is an example:: + + Issue #42: the spam module is now more spammy. + The spam module sporadically came up short on spam. This change + raises the amount of spam in the module by making it more spammy. + Thanks to Monty Python for the patch. + +The first line or sentence is meant to be a dense, to-the-point explanation +of what the purpose of the commit is. If this is not enough detail for a commit, +a new paragraph(s) can be added to explain in proper depth what has happened +(detail should be good enough that a core developer reading the commit message +understands the justification for the change). Also, if a non-core developer +contributed to the resolution, it is good practice to credit them. + +Mercurial hooks +''''''''''''''' + +Special hooks have been added to the Mercurial repository to enable notifying +the issue tracker of a commit related to an issue. + +A commit message can mention one or several issues in one of the following +ways:: + + #12345 + issue12345 + issue 12345 + bug12345 + bug 12345 + +where 12345 is the number of the issue. The commit details (including its +changeset, branch and commit message) will then be posted as a message to the +issue's page in the tracker, for each mentioned issue. + +If "closes" (or "closed", or "closing") is prepended, the issue is +automatically closed as "fixed". + +Working with Mercurial_ +======================= + +As a core developer, the ability to push changes to the official Python +repositories means you have to be more careful with your workflow: + +* You should not push new named branches to the main repository. You can + still use them in clones that you use for development of patches; you can + also push these branches to a **separate** public repository that will be + dedicated to maintenance of the work before the work gets integrated in the + main repository. + +* You should collapse changesets of a single feature or bugfix before pushing + the result to the main repository. The reason is that we don't want the + history to be full of intermediate commits recording the private history + of the person working on a patch. If you are using the rebase_ extension, + consider adding the ``--collapse`` option to ``hg rebase``. The collapse_ + extension is another choice. + +Because of these constraints, it can be practical to use other approaches +such as mq_ (Mercurial Queues), in order to maintain patches in a single +local repository and to push them seamlessly when they are ready. + +It can also be useful to keep a pristine clone of the main repository around, +as it allows simple reversion of all local changes (even "committed" ones) if +your local clone gets into a state you aren't happy with. + + +.. _Mercurial: http://www.hg-scm.org/ +.. _mq: http://mercurial.selenic.com/wiki/MqExtension +.. _rebase: http://mercurial.selenic.com/wiki/RebaseExtension +.. _collapse: http://mercurial.selenic.com/wiki/CollapseExtension + + +Minimal Configuration +--------------------- + +To use Mercurial as a committer (both of your and others' patches), you should +set up some basic options in your `configuration file`_. Under Windows, +TortoiseHg has a graphical settings dialog for most options, meaning you +don't need to edit the file directly (it is still available in +``%USERPROFILE%\Mercurial.ini``). Under other platforms, you must edit +``~/.hgrc``. + +Here are the minimal options you need to activate: + +* your *username*: this setting defines the name that will be used when you + :ref:`commit ` changes. The usual convention is to also include + an e-mail contact address in there:: + + [ui] + username = Your Name + +* *extended diffing*: this setting enables an `extended diff format`_ + which is more useful than the standard unified diff format as it includes + metadata about file copies, permission bits, and is able to represent + binary files:: + + [diff] + git = on + +Under Windows, you should also enable the `eol extension`_, which will +fix any Windows-specific line endings your text editor might insert when you +create or modify versioned files. The public repository has a hook which +will reject all changesets having the wrong line endings, so enabling this +extension on your local computer is in your best interest. + + +.. _configuration file: http://www.selenic.com/mercurial/hgrc.5.html#files +.. _extended diff format: http://www.selenic.com/mercurial/hg.1.html#diffs +.. _eol extension: http://mercurial.selenic.com/wiki/EolExtension + + +Clones Setup +------------ + +There are several possible ways to set up your Mercurial clone(s). If you are +a core developer, you often need to work on the different branches, so the best +approach is to have a separate clone/directory for each active branch. If you +are a contributor, having a single clone might be enough. + +Single Clone Approach +''''''''''''''''''''' + +This approach has the advantage of being simpler because it requires a single +clone/directory, but, on the other hand, it requires you to recompile Python +every time you need to switch branch. For this reason, this approach is not +suggested to core developers, but it's usually suitable for contributors. + +See :ref:`checkout` to find information about cloning and switching branches. + +.. _multiple-clones: + +Multiple Clones Approach +'''''''''''''''''''''''' + +This approach requires you to keep a separate clone/directory for each active +branch, but, on the other hand, it doesn't require you to switch branches and +recompile Python, so it saves times while merging and testing a patch on the +different branches. For this reason, this approach is suggested to core +developers. + +The easiest way to do this is by using the `share extension`_, that can be +enabled by adding the following lines to your ``~/.hgrc``:: + + [extensions] + share = + +Once you have :ref:`cloned the hg.python.org/cpython repository ` +you can create the other shared clones using:: + + $ hg share cpython 2.7 # create a new shared clone + $ cd 2.7 # enter the directory + $ hg up 2.7 # switch to the 2.7 branch + +You can then repeat the same operation for the other active branches. +This will create different clones/directories that share the same history. +This means that once you commit or pull new changesets in one of the clones, +they will be immediately available in all the other clones (note however that +while you only need to use ``hg pull`` once, you still need to use ``hg up`` +in each clone to update its working copy). + +If you don't want to specify ssh://hg@hg.python.org/cpython every time you pull +or push, you should add to the ``.hg/hgrc`` files of the clones:: + + [paths] + default = ssh://hg@hg.python.org/cpython + +In order to apply a patch, commit, and merge it on all the branches, you can do +as follow:: + + $ cd 2.7 + $ hg pull + $ hg up + $ hg import --no-c http://bugs.python.org/url/to/the/patch.diff + $ # review, run tests, run `make patchcheck` + $ hg ci -m '#12345: fix some issue.' + $ # switch to 3.4 and port the changeset using `hg graft` + $ cd ../3.4 + $ hg up + $ hg graft 2.7 + $ # switch to 3.x, merge, commit, and push everything + $ cd ../3.x + $ hg up + $ hg merge 3.4 + $ hg ci -m '#12345: merge with 3.4.' + $ hg push + +Unless noted otherwise, the rest of the page will assume you are using the +multiple clone approach, and explain in more detail these basic steps. + +For more advanced explanations about :ref:`null merges `, +:ref:`heads merges `, :ref:`merge conflicts +`, etc., see the :ref:`FAQs for core developers +`. + +.. _share extension: http://mercurial.selenic.com/wiki/ShareExtension + + +Active branches +--------------- + +If you do ``hg branches`` you will see a :ref:`list of branches `. +``default`` is the in-development branch, and is the only branch that receives +new features. The other branches only receive bug fixes or security fixes. +Depending on what you are committing (feature, bug fix, or security fix), you +should commit to the oldest branch applicable, and then forward-port until the +in-development branch. + + +Merging order +------------- + +There are two separate lines of development: one for Python 2 (the ``2.x`` +branches) and one for Python 3 (the ``3.x`` branches and ``default``). +You should *never* merge between the two major versions (2.x and 3.x) --- +only between minor versions (e.g. 3.x->3.y). The merge always happens from +the oldest applicable branch to the newest branch within the same major +Python version. + + +.. _branch-merge: + +Merging between different branches (within the same major version) +------------------------------------------------------------------ + +Assume that Python 3.5 is the current in-development version of Python and that +you have a patch that should also be applied to Python 3.4. To properly port +the patch to both versions of Python, you should first apply the patch to +Python 3.4:: + + cd 3.4 + hg import --no-commit patch.diff + # Compile; run the test suite + hg ci -m '#12345: fix some issue.' + +Then you can switch to the ``3.5`` clone, merge, run the tests and commit:: + + cd ../3.5 + hg merge 3.4 + # Fix any conflicts (e.g. ``hg revert -r default Misc/NEWS``); compile; run the test suite + hg ci -m '#12345: merge with 3.4.' + +If you are not using the share extension, you will need to use +``hg pull ../3.4`` before being able to merge. + +.. note:: + Even when porting an already committed patch, you should *still* check the + test suite runs successfully before committing the patch to another branch. + Subtle differences between two branches sometimes make a patch bogus if + ported without any modifications. + + +Porting changesets between the two major Python versions (2.x and 3.x) +---------------------------------------------------------------------- + +Assume you just committed something on ``2.7``, and want to port it to ``3.4``. +You can use ``hg graft`` as follow:: + + cd ../3.4 + hg graft 2.7 + +This will port the latest changeset committed in the 2.7 clone to the 3.4 clone. +``hg graft`` always commits automatically, except in case of conflicts, when +you have to resolve them and run ``hg graft --continue`` afterwards. +Instead of the branch name you can also specify a changeset id, and you can +also graft changesets from 3.x to 2.7. + +On older version of Mercurial where ``hg graft`` is not available, you can use:: + + cd ../3.4 + hg export 2.7 | hg import - + +The result will be the same, but in case of conflict this will create ``.rej`` +files rather than using Mercurial merge capabilities. + +A third option is to apply manually the patch on ``3.4``. This is convenient +when there are too many differences with ``2.7`` or when there is already a +specific patch for ``3.4``. + +.. warning:: + Never use ``hg merge`` to port changes between 2.x and 3.x (or vice versa). + + +Long-term development of features +--------------------------------- + +If you want to work on a feature long-term (perhaps you're implementing a +PEP), you will probably want to publish your work in a dedicated repository. +The following instructions will help you do so on `hg.python.org +`_'s infrastructure without requiring a lot of upload +bandwidth. + +Go to the main repository's Web page (http://hg.python.org/cpython/); there +you find a button labelled "server-side clone", which you can click on to +display a Web form. Enter the relative path of the repository you want to +create on the server, for example ``features/mywork``; and press the button. +A new repository gets created on the server with all the changesets of the +original repository (it will seem very fast; this is normal). + +You can now do a local clone of this repository on your disk:: + + $ hg clone ssh://hg@hg.python.org/features/mywork + $ cd mywork + +.. commented out: old instructions (without server-side cloning) + + First create a public (empty) repository on hg.python.org:: + + $ hg init ssh://hg@hg.python.org/features/mywork + + And do a local clone of that repository on your disk:: + + $ hg clone ssh://hg@hg.python.org/features/mywork + $ cd mywork + + There, pull all the contents from the main repository, either from a local + clone:: + + $ hg pull ../cpython + $ hg update + + or directly from the network (which is of course slower):: + + $ hg pull http://hg.python.org/cpython + $ hg update + +It is recommended that you create a new `named branch`_ for your work, so as +to easily track changes. That named branch will exist in your feature +repository, but not in the main repository:: + + $ hg branch mywork + $ hg commit -m "Creating branch mywork" + $ hg push --new-branch + +You can now work on your feature, commit changes as you will, and push them +when desired:: + + $ hg push + +When you push them, they will land in the public repository at +``ssh://hg@hg.python.org/features/mywork`` (or +``http://hg.python.org/features/mywork`` for the read-only URL). Other +people can clone the public repository and work on the code too. + +When you want to synchronize with CPython's upstream changes, you can pull +from the main repository, either from its remote URL:: + + $ hg pull http://hg.python.org/cpython + +or from a local clone that you may have on your disk (which is of course +faster):: + + $ hg pull ../cpython + +and merge all new changes from branch ``default`` to branch ``mywork``:: + + $ hg branch + mywork + $ hg merge default + +Rather than using a clone on ``python.org`` (which isn't particularly useful +for collaboration with folks that don't already have CPython commit rights), +Bitbucket_ also maintain an `up to date clone`_ of the main ``cpython`` +repository that can be used as the basis for a new clone or patch queue. + +.. _named branch: http://mercurial.selenic.com/wiki/NamedBranches +.. _Bitbucket: http://www.bitbucket.org +.. _up to date clone: https://bitbucket.org/mirror/cpython/overview + + +Uploading a patch for review +'''''''''''''''''''''''''''' + +In this scheme, your work will probably consist of many commits (some of +them merges). If you want to upload a patch for review somewhere, you need +a single aggregate patch. This is where having a dedicated named branch +``mywork`` gets handy. + +First ensure that you have pulled *and merged* all changes from the main +repository, as explained above. Then, assuming your :ref:`currently checked +out branch ` is still ``mywork``, simply do:: + + $ hg diff -r default > mywork.patch + +This will write to ``mywork.patch`` all the changes between ``default`` and +``mywork``. diff -r 85f290e474e2 build/_sources/communication.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/communication.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,81 @@ +.. _communication: + +Following Python's Development +============================== + +Python's development is communicated through a myriad of ways, mostly through +mailing lists, but also other forms. + +.. _mailinglists: + +Mailing Lists +------------- + +The primary mailing list where discussions about Python's development occur is +python-dev_. The list is open to the public and is subscribed to by all core +developers plus many people simply interested in following Python's +development. Discussion is focused on issues related to Python's development, +such as how to handle a specific issue, a PEP, etc. Ideas about new +functionality should **not** start here and instead should be sent to +python-ideas_. Technical support questions should also not be asked here and +instead should go to python-list_ or python-help_. + +The python-committers_ mailing list is a private mailing list for core +developers (the archives are publicly available). +If something only affects core developers (e.g., the +tree is frozen for commits, etc.), it is discussed here instead of python-dev +to keep traffic down on the latter. + +Python-ideas_ is a mailing list open to the public to discuss ideas on changing +Python. If a new idea does not start here (or python-list_, discussed below), +it will get redirected here. + +Python-checkins_ sends out an email for every commit to Python's various +repositories from http://hg.python.org. All core developers +subscribe to this list and are known to reply to these emails to make comments +about various issues they catch in the commit. Replies get redirected to +python-dev. + +There are two mailing lists related to issues on the `issue tracker`_. If you +only want an email for when a new issue is open, subscribe to +new-bugs-announce_. If you would rather receive an email for all changes made +to any issue, subscribe to python-bugs-list_. + +Sometimes people post new ideas to python-list_ to gather community opinion before +heading to python-ideas_. The list is also sometimes known as comp.lang.python, +the name of the newsgroup is mirrors (it is also known by the abbreviation +c.l.py). + +A complete list of Python mailing lists can be found at http://mail.python.org. +Most lists are also mirrored at http://news.gmane.org/ and can be read and +posted to in various ways, including via web browsers, NNTP newsreaders, and +RSS feed readers. + +.. _issue tracker: http://bugs.python.org +.. _new-bugs-announce: http://mail.python.org/mailman/listinfo/new-bugs-announce +.. _python-bugs-list: http://mail.python.org/mailman/listinfo/python-bugs-list +.. _python-checkins: http://mail.python.org/mailman/listinfo/python-checkins +.. _python-committers: http://mail.python.org/mailman/listinfo/python-committers +.. _python-dev: http://mail.python.org/mailman/listinfo/python-dev +.. _python-help: http://mail.python.org/mailman/listinfo/python-help +.. _python-ideas: http://mail.python.org/mailman/listinfo/python-ideas +.. _python-list: http://mail.python.org/mailman/listinfo/python-list + + +IRC +--- + +Some core developers enjoy spending time on IRC discussing various issues +regarding Python's development in the ``#python-dev`` channel on +``irc.freenode.net``. This is not a place to ask for help with Python, but to +discuss issues related to Python's own development. You can use freenode's +`Web interface `_ if you don't have an IRC +client. + + +Blogs +----- + +Several core developers are active bloggers and discuss Python's development +that way. You can find their blogs (and various other developers who use Python) +at http://planet.python.org/. diff -r 85f290e474e2 build/_sources/compiler.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/compiler.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,562 @@ +.. _compiler: + +Design of CPython's Compiler +============================ + + +Abstract +-------- + +Historically (through 2.4), compilation from source code to bytecode +involved two steps: + +1. Parse the source code into a parse tree (Parser/pgen.c) +2. Emit bytecode based on the parse tree (Python/compile.c) + +Historically, this is not how a standard compiler works. The usual +steps for compilation are: + +1. Parse source code into a parse tree (Parser/pgen.c) +2. Transform parse tree into an Abstract Syntax Tree (Python/ast.c) +3. Transform AST into a Control Flow Graph (Python/compile.c) +4. Emit bytecode based on the Control Flow Graph (Python/compile.c) + +Starting with Python 2.5, the above steps are now used. This change +was done to simplify compilation by breaking it into three steps. +The purpose of this document is to outline how the latter three steps +of the process work. + +This document does not touch on how parsing works beyond what is needed +to explain what is needed for compilation. It is also not exhaustive +in terms of the how the entire system works. You will most likely need +to read some source to have an exact understanding of all details. + + +Parse Trees +----------- + +Python's parser is an LL(1) parser mostly based off of the +implementation laid out in the Dragon Book [Aho86]_. + +The grammar file for Python can be found in Grammar/Grammar with the +numeric value of grammar rules are stored in Include/graminit.h. The +numeric values for types of tokens (literal tokens, such as ``:``, +numbers, etc.) are kept in Include/token.h). The parse tree made up of +``node *`` structs (as defined in Include/node.h). + +Querying data from the node structs can be done with the following +macros (which are all defined in Include/node.h): + +``CHILD(node *, int)`` + Returns the nth child of the node using zero-offset indexing +``RCHILD(node *, int)`` + Returns the nth child of the node from the right side; use + negative numbers! +``NCH(node *)`` + Number of children the node has +``STR(node *)`` + String representation of the node; e.g., will return ``:`` for a + COLON token +``TYPE(node *)`` + The type of node as specified in ``Include/graminit.h`` +``REQ(node *, TYPE)`` + Assert that the node is the type that is expected +``LINENO(node *)`` + retrieve the line number of the source code that led to the + creation of the parse rule; defined in Python/ast.c + +To tie all of this example, consider the rule for 'while':: + + while_stmt: 'while' test ':' suite ['else' ':' suite] + +The node representing this will have ``TYPE(node) == while_stmt`` and +the number of children can be 4 or 7 depending on if there is an 'else' +statement. To access what should be the first ':' and require it be an +actual ':' token, `(REQ(CHILD(node, 2), COLON)``. + + +Abstract Syntax Trees (AST) +--------------------------- + +The abstract syntax tree (AST) is a high-level representation of the +program structure without the necessity of containing the source code; +it can be thought of as an abstract representation of the source code. The +specification of the AST nodes is specified using the Zephyr Abstract +Syntax Definition Language (ASDL) [Wang97]_. + +The definition of the AST nodes for Python is found in the file +Parser/Python.asdl . + +Each AST node (representing statements, expressions, and several +specialized types, like list comprehensions and exception handlers) is +defined by the ASDL. Most definitions in the AST correspond to a +particular source construct, such as an 'if' statement or an attribute +lookup. The definition is independent of its realization in any +particular programming language. + +The following fragment of the Python ASDL construct demonstrates the +approach and syntax:: + + module Python + { + stmt = FunctionDef(identifier name, arguments args, stmt* body, + expr* decorators) + | Return(expr? value) | Yield(expr value) + attributes (int lineno) + } + +The preceding example describes three different kinds of statements; +function definitions, return statements, and yield statements. All +three kinds are considered of type stmt as shown by '|' separating the +various kinds. They all take arguments of various kinds and amounts. + +Modifiers on the argument type specify the number of values needed; '?' +means it is optional, '*' means 0 or more, no modifier means only one +value for the argument and it is required. FunctionDef, for instance, +takes an identifier for the name, 'arguments' for args, zero or more +stmt arguments for 'body', and zero or more expr arguments for +'decorators'. + +Do notice that something like 'arguments', which is a node type, is +represented as a single AST node and not as a sequence of nodes as with +stmt as one might expect. + +All three kinds also have an 'attributes' argument; this is shown by the +fact that 'attributes' lacks a '|' before it. + +The statement definitions above generate the following C structure type:: + + typedef struct _stmt *stmt_ty; + + struct _stmt { + enum { FunctionDef_kind=1, Return_kind=2, Yield_kind=3 } kind; + union { + struct { + identifier name; + arguments_ty args; + asdl_seq *body; + } FunctionDef; + + struct { + expr_ty value; + } Return; + + struct { + expr_ty value; + } Yield; + } v; + int lineno; + } + +Also generated are a series of constructor functions that allocate (in +this case) a stmt_ty struct with the appropriate initialization. The +'kind' field specifies which component of the union is initialized. The +FunctionDef() constructor function sets 'kind' to FunctionDef_kind and +initializes the 'name', 'args', 'body', and 'attributes' fields. + + +Memory Management +----------------- + +Before discussing the actual implementation of the compiler, a discussion of +how memory is handled is in order. To make memory management simple, an arena +is used. This means that a memory is pooled in a single location for easy +allocation and removal. What this gives us is the removal of explicit memory +deallocation. Because memory allocation for all needed memory in the compiler +registers that memory with the arena, a single call to free the arena is all +that is needed to completely free all memory used by the compiler. + +In general, unless you are working on the critical core of the compiler, memory +management can be completely ignored. But if you are working at either the +very beginning of the compiler or the end, you need to care about how the arena +works. All code relating to the arena is in either Include/pyarena.h or +Python/pyarena.c . + +PyArena_New() will create a new arena. The returned PyArena structure will +store pointers to all memory given to it. This does the bookkeeping of what +memory needs to be freed when the compiler is finished with the memory it used. +That freeing is done with PyArena_Free(). This needs to only be called in +strategic areas where the compiler exits. + +As stated above, in general you should not have to worry about memory +management when working on the compiler. The technical details have been +designed to be hidden from you for most cases. + +The only exception comes about when managing a PyObject. Since the rest +of Python uses reference counting, there is extra support added +to the arena to cleanup each PyObject that was allocated. These cases +are very rare. However, if you've allocated a PyObject, you must tell +the arena about it by calling ``PyArena_AddPyObject()``. + + +Parse Tree to AST +----------------- + +The AST is generated from the parse tree (see Python/ast.c) using the +function ``PyAST_FromNode()``. + +The function begins a tree walk of the parse tree, creating various AST +nodes as it goes along. It does this by allocating all new nodes it +needs, calling the proper AST node creation functions for any required +supporting functions, and connecting them as needed. + +Do realize that there is no automated nor symbolic connection between +the grammar specification and the nodes in the parse tree. No help is +directly provided by the parse tree as in yacc. + +For instance, one must keep track of which node in the parse tree +one is working with (e.g., if you are working with an 'if' statement +you need to watch out for the ':' token to find the end of the conditional). + +The functions called to generate AST nodes from the parse tree all have +the name ast_for_xx where xx is what the grammar rule that the function +handles (alias_for_import_name is the exception to this). These in turn +call the constructor functions as defined by the ASDL grammar and +contained in Python/Python-ast.c (which was generated by +Parser/asdl_c.py) to create the nodes of the AST. This all leads to a +sequence of AST nodes stored in asdl_seq structs. + + +Function and macros for creating and using ``asdl_seq *`` types as found +in Python/asdl.c and Include/asdl.h: + +``asdl_seq_new()`` + Allocate memory for an asdl_seq for the specified length +``asdl_seq_GET()`` + Get item held at a specific position in an asdl_seq +``asdl_seq_SET()`` + Set a specific index in an asdl_seq to the specified value +``asdl_seq_LEN(asdl_seq *)`` + Return the length of an asdl_seq + +If you are working with statements, you must also worry about keeping +track of what line number generated the statement. Currently the line +number is passed as the last parameter to each stmt_ty function. + + +Control Flow Graphs +------------------- + +A control flow graph (often referenced by its acronym, CFG) is a +directed graph that models the flow of a program using basic blocks that +contain the intermediate representation (abbreviated "IR", and in this +case is Python bytecode) within the blocks. Basic blocks themselves are +a block of IR that has a single entry point but possibly multiple exit +points. The single entry point is the key to basic blocks; it all has +to do with jumps. An entry point is the target of something that +changes control flow (such as a function call or a jump) while exit +points are instructions that would change the flow of the program (such +as jumps and 'return' statements). What this means is that a basic +block is a chunk of code that starts at the entry point and runs to an +exit point or the end of the block. + +As an example, consider an 'if' statement with an 'else' block. The +guard on the 'if' is a basic block which is pointed to by the basic +block containing the code leading to the 'if' statement. The 'if' +statement block contains jumps (which are exit points) to the true body +of the 'if' and the 'else' body (which may be NULL), each of which are +their own basic blocks. Both of those blocks in turn point to the +basic block representing the code following the entire 'if' statement. + +CFGs are usually one step away from final code output. Code is directly +generated from the basic blocks (with jump targets adjusted based on the +output order) by doing a post-order depth-first search on the CFG +following the edges. + + +AST to CFG to Bytecode +---------------------- + +With the AST created, the next step is to create the CFG. The first step +is to convert the AST to Python bytecode without having jump targets +resolved to specific offsets (this is calculated when the CFG goes to +final bytecode). Essentially, this transforms the AST into Python +bytecode with control flow represented by the edges of the CFG. + +Conversion is done in two passes. The first creates the namespace +(variables can be classified as local, free/cell for closures, or +global). With that done, the second pass essentially flattens the CFG +into a list and calculates jump offsets for final output of bytecode. + +The conversion process is initiated by a call to the function +``PyAST_Compile()`` in Python/compile.c . This function does both the +conversion of the AST to a CFG and +outputting final bytecode from the CFG. The AST to CFG step is handled +mostly by two functions called by PyAST_Compile(); PySymtable_Build() and +compiler_mod() . The former is in Python/symtable.c while the latter is in +Python/compile.c . + +PySymtable_Build() begins by entering the starting code block for the +AST (passed-in) and then calling the proper symtable_visit_xx function +(with xx being the AST node type). Next, the AST tree is walked with +the various code blocks that delineate the reach of a local variable +as blocks are entered and exited using symtable_enter_block() and +symtable_exit_block(), respectively. + +Once the symbol table is created, it is time for CFG creation, whose +code is in Python/compile.c . This is handled by several functions +that break the task down by various AST node types. The functions are +all named compiler_visit_xx where xx is the name of the node type (such +as stmt, expr, etc.). Each function receives a ``struct compiler *`` +and xx_ty where xx is the AST node type. Typically these functions +consist of a large 'switch' statement, branching based on the kind of +node type passed to it. Simple things are handled inline in the +'switch' statement with more complex transformations farmed out to other +functions named compiler_xx with xx being a descriptive name of what is +being handled. + +When transforming an arbitrary AST node, use the VISIT() macro. +The appropriate compiler_visit_xx function is called, based on the value +passed in for (so ``VISIT(c, expr, node)`` calls +``compiler_visit_expr(c, node)``). The VISIT_SEQ macro is very similar, +but is called on AST node sequences (those values that were created as +arguments to a node that used the '*' modifier). There is also +VISIT_SLICE() just for handling slices. + +Emission of bytecode is handled by the following macros: + +``ADDOP()`` + add a specified opcode +``ADDOP_I()`` + add an opcode that takes an argument +``ADDOP_O(struct compiler *c, int op, PyObject *type, PyObject *obj)`` + add an opcode with the proper argument based on the position of the + specified PyObject in PyObject sequence object, but with no handling of + mangled names; used for when you + need to do named lookups of objects such as globals, consts, or + parameters where name mangling is not possible and the scope of the + name is known +``ADDOP_NAME()`` + just like ADDOP_O, but name mangling is also handled; used for + attribute loading or importing based on name +``ADDOP_JABS()`` + create an absolute jump to a basic block +``ADDOP_JREL()`` + create a relative jump to a basic block + +Several helper functions that will emit bytecode and are named +compiler_xx() where xx is what the function helps with (list, boolop, +etc.). A rather useful one is compiler_nameop(). +This function looks up the scope of a variable and, based on the +expression context, emits the proper opcode to load, store, or delete +the variable. + +As for handling the line number on which a statement is defined, is +handled by compiler_visit_stmt() and thus is not a worry. + +In addition to emitting bytecode based on the AST node, handling the +creation of basic blocks must be done. Below are the macros and +functions used for managing basic blocks: + +``NEW_BLOCK()`` + create block and set it as current +``NEXT_BLOCK()`` + basically NEW_BLOCK() plus jump from current block +``compiler_new_block()`` + create a block but don't use it (used for generating jumps) + +Once the CFG is created, it must be flattened and then final emission of +bytecode occurs. Flattening is handled using a post-order depth-first +search. Once flattened, jump offsets are backpatched based on the +flattening and then a PyCodeObject file is created. All of this is +handled by calling assemble() . + + +Introducing New Bytecode +------------------------ + +Sometimes a new feature requires a new opcode. But adding new bytecode is +not as simple as just suddenly introducing new bytecode in the AST -> +bytecode step of the compiler. Several pieces of code throughout Python depend +on having correct information about what bytecode exists. + +First, you must choose a name and a unique identifier number. The official +list of bytecode can be found in Include/opcode.h . If the opcode is to take +an argument, it must be given a unique number greater than that assigned to +``HAVE_ARGUMENT`` (as found in Include/opcode.h). + +Once the name/number pair +has been chosen and entered in Include/opcode.h, you must also enter it into +Lib/opcode.py and Doc/library/dis.rst . + +With a new bytecode you must also change what is called the magic number for +.pyc files. The variable ``MAGIC`` in Python/import.c contains the number. +Changing this number will lead to all .pyc files with the old MAGIC +to be recompiled by the interpreter on import. + +Finally, you need to introduce the use of the new bytecode. Altering +Python/compile.c and Python/ceval.c will be the primary places to change. +But you will also need to change the 'compiler' package. The key files +to do that are Lib/compiler/pyassem.py and Lib/compiler/pycodegen.py . + +If you make a change here that can affect the output of bytecode that +is already in existence and you do not change the magic number constantly, make +sure to delete your old .py(c|o) files! Even though you will end up changing +the magic number if you change the bytecode, while you are debugging your work +you will be changing the bytecode output without constantly bumping up the +magic number. This means you end up with stale .pyc files that will not be +recreated. Running +``find . -name '*.py[co]' -exec rm -f {} ';'`` should delete all .pyc files you +have, forcing new ones to be created and thus allow you test out your new +bytecode properly. + + +Code Objects +------------ + +The result of ``PyAST_Compile()`` is a PyCodeObject which is defined in +Include/code.h . And with that you now have executable Python bytecode! + +The code objects (byte code) is executed in Python/ceval.c . This file +will also need a new case statement for the new opcode in the big switch +statement in PyEval_EvalFrameEx(). + + +Important Files +--------------- + ++ Parser/ + + Python.asdl + ASDL syntax file + + asdl.py + "An implementation of the Zephyr Abstract Syntax Definition + Language." Uses SPARK_ to parse the ASDL files. + + asdl_c.py + "Generate C code from an ASDL description." Generates + Python/Python-ast.c and Include/Python-ast.h . + + spark.py + SPARK_ parser generator + ++ Python/ + + Python-ast.c + Creates C structs corresponding to the ASDL types. Also + contains code for marshaling AST nodes (core ASDL types have + marshaling code in asdl.c). "File automatically generated by + Parser/asdl_c.py". This file must be committed separately + after every grammar change is committed since the __version__ + value is set to the latest grammar change revision number. + + asdl.c + Contains code to handle the ASDL sequence type. Also has code + to handle marshalling the core ASDL types, such as number and + identifier. used by Python-ast.c for marshaling AST nodes. + + ast.c + Converts Python's parse tree into the abstract syntax tree. + + ceval.c + Executes byte code (aka, eval loop). + + compile.c + Emits bytecode based on the AST. + + symtable.c + Generates a symbol table from AST. + + pyarena.c + Implementation of the arena memory manager. + + import.c + Home of the magic number (named ``MAGIC``) for bytecode versioning + + ++ Include/ + + Python-ast.h + Contains the actual definitions of the C structs as generated by + Python/Python-ast.c . + "Automatically generated by Parser/asdl_c.py". + + asdl.h + Header for the corresponding Python/ast.c . + + ast.h + Declares PyAST_FromNode() external (from Python/ast.c). + + code.h + Header file for Objects/codeobject.c; contains definition of + PyCodeObject. + + symtable.h + Header for Python/symtable.c . struct symtable and + PySTEntryObject are defined here. + + pyarena.h + Header file for the corresponding Python/pyarena.c . + + opcode.h + Master list of bytecode; if this file is modified you must modify + several other files accordingly (see "`Introducing New Bytecode`_") + ++ Objects/ + + codeobject.c + Contains PyCodeObject-related code (originally in + Python/compile.c). + ++ Lib/ + + opcode.py + One of the files that must be modified if Include/opcode.h is. + + compiler/ + + pyassem.py + One of the files that must be modified if Include/opcode.h is + changed. + + pycodegen.py + One of the files that must be modified if Include/opcode.h is + changed. + + +Known Compiler-related Experiments +---------------------------------- + +This section lists known experiments involving the compiler (including +bytecode). + +Skip Montanaro presented a paper at a Python workshop on a peephole optimizer +[#skip-peephole]_. + +Michael Hudson has a non-active SourceForge project named Bytecodehacks +[#Bytecodehacks]_ that provides functionality for playing with bytecode +directly. + +An opcode to combine the functionality of LOAD_ATTR/CALL_FUNCTION was created +named CALL_ATTR [#CALL_ATTR]_. Currently only works for classic classes and +for new-style classes rough benchmarking showed an actual slowdown thanks to +having to support both classic and new-style classes. + + + +References +---------- + +.. [Aho86] Alfred V. Aho, Ravi Sethi, Jeffrey D. Ullman. + `Compilers: Principles, Techniques, and Tools`, + http://www.amazon.com/exec/obidos/tg/detail/-/0201100886/104-0162389-6419108 + +.. [Wang97] Daniel C. Wang, Andrew W. Appel, Jeff L. Korn, and Chris + S. Serra. `The Zephyr Abstract Syntax Description Language.`_ + In Proceedings of the Conference on Domain-Specific Languages, pp. + 213--227, 1997. + +.. _The Zephyr Abstract Syntax Description Language.: + http://www.cs.princeton.edu/research/techreps/TR-554-97 + +.. _SPARK: http://pages.cpsc.ucalgary.ca/~aycock/spark/ + +.. [#skip-peephole] Skip Montanaro's Peephole Optimizer Paper + (http://www.python.org/workshops/1998-11/proceedings/papers/montanaro/montanaro.html) + +.. [#Bytecodehacks] Bytecodehacks Project + (http://bytecodehacks.sourceforge.net/bch-docs/bch/index.html) + +.. [#CALL_ATTR] CALL_ATTR opcode + (http://www.python.org/sf/709744) diff -r 85f290e474e2 build/_sources/coredev.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/coredev.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,153 @@ +.. _coredev: + +How to Become a Core Developer +============================== + +What it Takes +------------- + +When you have consistently contributed patches which meet quality standards +without requiring extensive rewrites prior to being committed, +you may qualify for +commit privileges and become a core developer of Python. You must also work +well with other core developers (and people in general) as you become an +ambassador for the Python project. + +Typically a core developer will offer you the chance to gain commit privilege. +The person making the offer will become your mentor and watch your commits for +a while to make sure you understand the development process. If other core +developers agree that you should gain commit privileges you are then extended +an official offer. + +You may request commit privileges yourself, but do not be surprised if your +request is turned down. Do not take this personally! It simply means that other +core developers think you need more time contributing patches before you are +able to commit them without supervision. + +A complete list of core developer usernames can be found at +http://hg.python.org/committers.txt. :ref:`developers` lists when and why +someone received commit privileges. + + +Gaining Commit Privileges +------------------------- + +When you have been extended an official offer to become a Python core +developer, there are several things you must do. + +Mailing Lists +''''''''''''' + +You are expected to subscribe to python-committers, python-dev, +python-checkins, and one of new-bugs-announce or python-bugs-list. See +:ref:`communication` for links to these mailing lists. + + +Issue Tracker +''''''''''''' + +If you did not gain the Developer role in the `issue tracker`_ before gaining +commit privileges, please say so. This will allow issues to be assigned to you. +A tracker admin should also flip your "is committer" bit in the tracker's +account screen. + +It is expected that on the issue tracker you have a username in the form of +"first_name.last_name". If your initial issue tracker username is not of this +form, please change it. This is so that it is easier to assign issues to the +right person. + + +SSH +''' + +You need to generate an SSH 2 RSA key to be able to commit code. You may have +multiple keys if you wish (e.g., for work and home). Send your key as an +attachment in an email to hgaccounts@python.org. Help in generating an SSH key +can be found in the :ref:`faq`. + +Your SSH key will be set to a username in the form of "first_name.last_name". +This should match your username on the issue tracker. + +You can verify your commit access by looking at +http://hg.python.org/committers.txt which lists all core developers by +username. If you want to practice, there is a `test repository +`_ where you can freely commit and push any +changes you like:: + + hg clone ssh://hg@hg.python.org/test/ hgtest + +An entry in the :ref:`developers` should also be entered for you. +Typically the person who sponsored your application to become a core developer +makes sure an entry is created for you. + + +.. _contributor_agreement: + +Sign a Contributor Agreement +'''''''''''''''''''''''''''' + +Submitting a `contributor form for Python`_ licenses any code you contribute to +the Python Software Foundation. While you retain the copyright, giving the PSF +the ability to license your code means it can be put under the PSF license so +it can be legally distributed with Python. + +This is a very important step! Hopefully you have already submitted a +contributor agreement if you have been submitting patches. But if you have not +done this yet, it is best to do this ASAP, probably before you even do your +first commit so as to not forget. + + +.. _contributor form for Python: http://www.python.org/psf/contrib/ + + + +Read/Write Checkout +''''''''''''''''''' + +With your commit privileges working and your contributor form submitted, you +can now get a read/write checkout of the code. URLs for read/write checkouts +are different than those for read-only checkouts as SSH is used instead of +HTTP. + +You can clone the repository (which contains all active branches) with:: + + hg clone ssh://hg@hg.python.org/cpython + +The default branch in that repository is the current development branch. +You can of course switch your working copy to one of the maintenance branches, +for example:: + + hg update 2.7 + + +Responsibilities +---------------- + +As a core developer, there are certain things that are expected of you. + +First and foremost, be a good person. This might sound melodramatic, but you +are now a member of the Python project and thus represent the project and your +fellow core developers whenever you discuss Python with anyone. We have a +reputation for being a very nice group of people and we would like to keep it +that way. + +Second, please be prompt in responding to questions. We are all volunteers so +what little free time one can dedicate to Python should be spent being +productive. If you have been asked to respond to an issue or answer a question +and you put it off it ends up stalling other people's work. It is completely +acceptable to say you are too busy, but you need to say that instead of +stringing people along. This obviously applies to anything you do on the issue +tracker as well. + +Third, please list what areas you want to be considered an expert in the +:ref:`experts`. This allows triagers to direct issues to you which involve +an area you are an expert in. But, +as stated in the second point above, if you do not have the time to answer +questions promptly then please remove yourself as needed from the file so that +you will not be bothered in the future. Once again, we all understand how life +gets in the way, so no one will be insulted if you remove yourself from the +list. + +And finally, enjoy yourself! Contributing to open source software should be fun +(overall). If you find yourself no longer enjoying the work then either take a +break or figure out what you need to do to make it enjoyable again. diff -r 85f290e474e2 build/_sources/coverage.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/coverage.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,260 @@ +.. _coverage: + +Increase Test Coverage +====================== + +Python development follows a practice that all semantic changes and additions +to the language and :abbr:`stdlib (standard library)` are accompanied by +appropriate unit tests. Unfortunately Python was in existence for a long time +before the practice came into effect. This has left chunks of the stdlib +untested which is not a desirable situation to be in. + +A good, easy way to become acquainted with Python's code and to help out is to +help increase the test coverage for Python's stdlib. Ideally we would like to +have 100% coverage, but any increase is a good one. Do realize, though, that +getting 100% coverage is not always possible. There could be platform-specific +code that simply will not execute for you, errors in the output, etc. You can +use your judgement as to what should and should not be covered, but being +conservative and assuming something should be covered is generally a good rule +to follow. + +Choosing what module you want to increase test coverage for can be done in a +couple of ways. +A third-party website at http://coverage.livinglogic.de/ provides an +overall view of how good coverage is for various modules (you will want to +focus on those in the ``Lib`` directory as those are the pure Python modules +from Python's stdlib, and thus easier to work with than the C extension +modules). But since this is a third-party site we cannot promise that it will +always be accessible or have useful information (i.e., be working properly). + +Another is to follow the examples below and simply see what +coverage your favorite module has. This is "stabbing in the dark", though, and +so it might take some time to find a module that needs coverage help. + +Finally, you can simply run the entire test suite yourself with coverage turned +on and see what modules need help. This has the drawback of running the entire +test suite under coverage measuring which takes some time to complete, but you +will have an accurate, up-to-date notion of what modules need the most work. + +Do make sure, though, that for any module you do decide to work on that you run +coverage for just that module. This will make sure you know how good the +explicit coverage of the module is from its own set of tests instead of from +implicit testing by other code that happens to use the module. + + +Common Gotchas +"""""""""""""" + +Please realize that coverage reports on modules already imported before coverage +data starts to be recorded will be wrong. Typically you can tell a module falls +into this category by the coverage report saying that global statements that +would obviously be executed upon import have gone unexecuted while local +statements have been covered. In these instances you can ignore the global +statement coverage and simply focus on the local statement coverage. + +When writing new tests to increase coverage, do take note of the style of tests +already provided for a module (e.g., whitebox, blackbox, etc.). As +some modules are primarily maintained by a single core developer they may have +a specific preference as to what kind of test is used (e.g., whitebox) and +prefer that other types of tests not be used (e.g., blackbox). When in doubt, +stick with whitebox testing in order to properly exercise the code. + + +Measuring Coverage +"""""""""""""""""" + +It should be noted that a quirk of running coverage over Python's own stdlib is +that certain modules are imported as part of interpreter startup. Those modules +required by Python itself will not be viewed as executed by the coverage tools +and thus look like they have very poor coverage (e.g., the :py:mod:`stat` +module). In these instances the module will appear to not have any coverage of +global statements but will have proper coverage of local statements (e.g., +function definitions will be not be traced, but the function bodies will). +Calculating the coverage of modules in this situation will simply require +manually looking at what local statements were not executed. + +Using coverage.py +----------------- + +One of the most popular third-party coverage tools is `coverage.py`_ which +provides very nice HTML output along with advanced features such as +:ref:`branch coverage `. If you prefer to stay with tools only +provided by the stdlib then you can by :ref:`using test.regrtest +`. + +Because the in-development version of Python is bleeding-edge, it is possible +that the latest release version of coverage.py will not work. In that case you +should try using the in-development of coverage.py to see if it has been +updated as needed. To do this you should clone/check out the development version +of coverage.py:: + + hg clone https://bitbucket.org/ned/coveragepy + +Another option is to use an installed copy of coverage.py if you already have an +installed copy. But if you do not already have it installed then it is preferred +you use a clone of coverage.py for gathering coverage results. + +If you are using a clone of coverage.py, the following should work (substitute +``COVERAGEDIR`` with the directory where your clone exists, e.g. +``../coveragepy``):: + + ./python COVERAGEDIR + +Coverage.py will print out a little bit of helper text verifying that +everything is working. If you are using an installed copy, you can do the +following instead:: + + ./python -m coverage + +The rest of the examples on how to use coverage.py will assume you are using a +cloned copy, but you can substitute the above and all instructions should still +be valid. + +To run the test suite under coverage.py, do the following:: + + ./python COVERAGEDIR run --pylib Lib/test/regrtest.py + +To run only a single test, specify the module/package being tested +in the ``--source`` flag (so as to prune the coverage reporting to only the +module/package you are interested in) and then append the name of the test you +wish to run to the command:: + + ./python COVERAGEDIR run --pylib --source=abc Lib/test/regrtest.py test_abc + +To see the results of the coverage run, you can view a text-based report with:: + + ./python COVERAGEDIR report + +You can use the ``--show-missing`` flag to get a list of lines that were not +executed:: + + ./python COVERAGEDIR report --show-missing + +But one of the strengths of coverage.py is its HTML-based reports which let +you visually see what lines of code were not tested:: + + ./python COVERAGEDIR html -i --include=`pwd`/Lib/* --omit="Lib/test/*,Lib/*/tests/*" + +This will generate an HTML report in a directory named ``htmlcov`` which +ignores any errors that may arise and ignores modules for which test coverage is +unimportant (e.g. tests, temp files, etc.). You can then open the +``htmlcov/index.html`` file in a web browser to view the coverage results along +with pages that visibly show what lines of code were or were not executed. + + +.. _branch_coverage: + +Branch Coverage +''''''''''''''' + +For the truly daring, you can use another powerful feature of coverage.py: +branch coverage. Testing every possible branch path through code, while a great +goal to strive for, is a secondary goal to getting 100% line +coverage for the entire stdlib (for now). + +If you decide you want to try to improve branch coverage, simply add the +``--branch`` flag to your coverage run:: + + ./python COVERAGEDIR run --pylib --branch + +This will lead to the report stating not only what lines were not covered, but +also what branch paths were not executed. + + +Coverage Results For Modules Imported Early On +'''''''''''''''''''''''''''''''''''''''''''''' + +For the *truly truly* daring, you can use a hack to get coverage.py to include +coverage for modules that are imported early on during CPython's startup (e.g. +the encodings module). Do not worry if you can't get this to work or it doesn't +make any sense; it's entirely optional and only important for a small number of +modules. + +If you still choose to try this, the first step is to build coverage.py's C +extension code. Assuming that coverage.py's clone is at ``COVERAGEDIR`` and +your clone of CPython is at ``CPYTHONDIR``, you execute the following in your +coverage.py clone:: + + CPPFLAGS="-I CPYTHONDIR -I CPYTHONDIR/Include" CPYTHONDIR/python setup.py build_ext --inplace + +This will build coverage.py's C extension code in-place, allowing the previous +instructions on how to gather coverage to continue to work. + +To get coverage.py to be able to gather the most accurate coverage data on as +many modules as possible +**with a HORRIBLE HACK that you should NEVER use in your own code**, run the +following from your CPython clone:: + + PYTHONPATH=COVERAGEDIR/coverage/fullcoverage ./python COVERAGEDIR run --pylib Lib/test/regrtest.py + +This will give you the most complete coverage possible for CPython's standard +library. + +.. _coverage.py: http://nedbatchelder.com/code/coverage/ + + +.. _coverage_by_regrtest: + +Using test.regrtest +------------------- + +If you prefer to rely solely on the stdlib to generate coverage data, you can +do so by passing the appropriate flags to :py:mod:`test.regrtest` (along with +any other flags you want to):: + + ./python -m test --coverage -D `pwd`/coverage_data + +Do note the argument to ``-D``; if you do not specify an absolute path to where +you want the coverage data to end up it will go somewhere you don't expect. + + +.. note:: + If you are running coverage over the entire test suite, make sure to + add ``-x test_importlib test_runpy test_trace`` to exclude those tests as + they trigger exceptions during coverage; see + http://bugs.python.org/issue10541 and http://bugs.python.org/issue10991. + +Once the tests are done you will find the directory you specified contains +files for each executed module along with which lines were executed how many +times. + + +Filing the Issue +"""""""""""""""" +Once you have increased coverage, you need to +:ref:`generate the patch ` and submit it to the `issue tracker`_. On the +issue set the "Components" to "Test" and "Versions" to the version of Python you +worked on (i.e., the in-development version). + +.. _issue tracker: http://bugs.python.org + + +Measuring coverage of C code with gcov and lcov +""""""""""""""""""""""""""""""""""""""""""""""" + +It's also possible to measure the function, line and branch coverage of +Python's C code. Right now only GCC with `gcov`_ is supported. In order to +create an instrumented build of Python with gcov, run:: + + make coverage + +Then run some code and gather coverage data with the ``gcov`` command. In +order to create a HTML report you can install `lcov`_. The command:: + + make coverage-lcov + +assembles coverage data, removes 3rd party and system libaries and finally +creates a report. You can skip both steps and just run:: + + make coverage-report + +if you like to generate a coverage report for Python's stdlib tests. It takes +about 20 to 30 minutes on a modern computer. + +.. note:: + + Multiple test jobs may not work properly. C coverage reporting has only + been tested with a single test process. + +.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html +.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php diff -r 85f290e474e2 build/_sources/coverity.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/coverity.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,153 @@ +============= +Coverity Scan +============= + +.. _coverity: + +Coverity Scan is a free service for static code analysis of Open Source +projects. It is based on Coverity's commercial product and is able to analyze +C, C++ and Java code. + +Coverity's static code analysis doesn't run the code. Instead of that it uses +abstract interpretation to gain information about the code's control flow and +data flow. It's able to follow all possible code paths that a program may +take. For example the analyzer understands that ``malloc()`` returns a memory +that must be freed with ``free()`` later. It follows all branches and function +calls to see if all possible combinations free the memory. The analyzer is +able to detect all sorts of issues like resource leaks (memory, file +descriptors), NULL dereferencing, use after free, unchecked return values, +dead code, buffer overflows, integer overflows, uninitialized variables, and +many more. + + +Access to analysis reports +========================== + +The results are available on the `Coverity Scan`_ website. In order to +access the results you have to create an account yourself. Then go to +*Projects using Scan* and add yourself to the Python project. New members must +be approved by an admin (see `Contact`_). + +Access is restricted to Python core developers only. Other individuals may be +given access at our own discretion, too. Every now and then Coverity detects a +critical issue in Python's code -- new analyzers may even find new bugs in +mature code. We don't want to disclose issues prematurely. + + +Building and uploading analysis +=============================== + +The process is automated. A script runs ``hg pull``, ``hg update``, +``cov-build`` and uploads the latest analysis to Coverity. Since Coverity has +limited the maximum number of builds per week Python is analyzed every second +day. The build runs on a dedicated virtual machine on PSF's infrastructure at +OSU Open Source Labs. The process is maintained by Christian Heimes (see +`Contact`_). At present only the tip is analyzed with the 64bit Linux tools. + + +Known limitations +================= + +Some aspects of Python's C code are not yet understood by Coverity. + +False positives +--------------- + +``Py_BuildValue("N", PyObject*)`` + Coverity doesn't understand that ``N`` format char passes the object along + without touching its reference count. On this ground the analyzer detects + a resource leak. CID 719685 + +``PyLong_FromLong()`` for negative values + Coverity claims that ``PyLong_FromLong()`` and other ``PyLong_From*()`` + functions cannot handle a negative value because the value might be used as + an array index in ``get_small_int()``. CID 486783 + +``PyLong_FromLong()`` for n in [-5 ... +255] + For integers in the range of Python's small int cache the ``PyLong_From*()`` + function can never fail and never returns NULL. CID 1058291 + +``PyArg_ParseTupleAndKeywords(args, kwargs, "s#", &data, &length)`` + Some functions use the format char combination such as ``s#``, ``u#`` or + ``z#`` to get data and length of a character array. Coverity doesn't + recognize the relation between data and length. Sometimes it detects a buffer + overflow if data is written to a fixed size buffer although + ``length <= sizeof(buffer)``. CID 486613 + +``path_converter()`` dereferencing after null check + The ``path_converter()`` function in ``posixmodule.c`` makes sure that + either ``path_t.narrow`` or ``path_t.wide`` is filled unless + ``path_t.nullable`` is explicitly enabled. CID 719648 + + +Intentionally +------------- + +``Py_VA_COPY()`` + Python is written in C89 (ANSI C), therefore it can't use C99 features such + as ``va_copy()``. Python's own variant ``Py_VA_COPY()`` uses ``memcpy()`` + to make a copy of a ``va_list`` variable. Coverity detects two issues in + this approach: "Passing argument "lva" of type "va_list" and sizeof(va_list) + to function memcpy() is suspicious." CID 486405 and "Uninitialized pointer + read" CID 486630. + + +Modeling +======== + +Modeling is explained in the *Coverity Help Center* which is available in +the help menu of `Coverity Connect`_. `coverity_model.c`_ contains a copy of +Python's modeling file for Coverity. Please keep the copy in sync with the +model file in *Analysis Settings* of `Coverity Scan`_. + + +Workflow +======== + +False positive and intentional issues +------------------------------------- + +If the problem is listed under `Known limitations`_ then please set the +classification to either "False positive" or "Intentional", the action to +"Ignore", owner to your own account and add a comment why the issue +is considered false positive or intentional. + +If you think it's a new false positive or intentional then please contact an +admin. The first step should be an updated to Python's `Modeling`_ file. + + +Positive issues +--------------- + +You should always create an issue unless it's really a trivial case. Please +add the full url to the ticket under *Ext. Reference* and add the CID +(Coverity ID) to both the ticket and the checkin message. It makes it much +easier to understand the relation between tickets, fixes and Coverity issues. + + +Contact +======= + +Please include both Brett and Christian in any mail regarding Coverity. Mails +to Coverity should go through Brett or Christian, too. + +Christian Heimes + admin, maintainer of build machine, intermediary between Python and Coverity + +Brett Cannon + co-admin + +Dakshesh Vyas + Technical Manager - Coverity Scan + + +.. seealso:: + + `Coverity Scan FAQ `_ + + +.. _Coverity Scan: http://scan.coverity.com/ + +.. _Coverity Connect: http://scan5.coverity.com:8080/ + +.. _coverity_model.c: http://hg.python.org/cpython/file/tip/Misc/coverity_model.c diff -r 85f290e474e2 build/_sources/devcycle.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/devcycle.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,190 @@ +.. _devcycle: + +Development Cycle +================= + +The responsibilities of a core developer shift based on what kind of branch of +Python a developer is working on and what stage the branch is in. + +To clarify terminology, Python uses a ``major.minor.micro`` nomenclature +for production-ready releases. So for Python 3.1.2 final, that is a *major +version* of 3, a *minor version* of 1, and a *micro version* of 2. + +* new *major versions* are exceptional; they only come when strongly + incompatible changes are deemed necessary, and are planned very long + in advance; + +* new *minor versions* are feature releases; they get released roughly + every 18 months, from the current :ref:`in-development ` + branch; + +* new *micro versions* are bugfix releases; they get released roughly + every 6 months, although they can come more often if necessary; they are + prepared in :ref:`maintenance ` branches. + +We also publish non-final versions which get an additional qualifier: +:ref:`alpha`, :ref:`beta`, :ref:`release candidate `. These versions +are aimed at testing by advanced users, not production use. + + +Branches +'''''''' + +There is a branch for each *feature version*, whether released or not (e.g. +2.7, 3.5). Development is handled separately for Python 2 and Python 3: +no merging happens between 2.x and 3.x branches. + +In each of the 2.x and 3.x realms, the branch for a feature version is always a +descendant of the previous feature version: for example, the ``3.3`` branch is a +descendant of the ``3.2`` branch. + +Therefore, each change should be made **first** in the oldest branch to which it +applies and forward-ported as appropriate: if a bug must be fixed in both Python +3.4 and 3.5, first fix it in ``3.4`` and then merge ``3.4`` into ``default`` +(which holds the future 3.5). + + +.. _indevbranch: + +In-development (main) branch +---------------------------- + +The ``default`` branch is the branch for the next feature release; it is +under active development for all kinds of changes: new features, semantic +changes, performance improvements, bug fixes. As the name indicates, it +is the branch :ref:`checked out ` by default by Mercurial. + +Once a :ref:`final` release (say, 3.3) is made from the in-development branch, a +new :ref:`maintenance branch ` is created to host all bug fixing +activity for further micro versions (3.3.1, 3.3.2, etc.). + + +.. _maintbranch: + +Maintenance branches +-------------------- + +A branch for a previous feature release, currently being maintained for bug +fixes. There are usually two maintenance branches at any given time: one for +Python 3.x and +one for Python 2.x. At some point in the future, Python 2.x will be closed +for bug fixes and there will be only one maintenance branch left. + +The only changes allowed to occur in a maintenance branch without debate are +bug fixes. Also, a general rule for maintenance branches is that compatibility +must not be broken at any point between sibling minor releases (3.3.1, 3.3.2, +etc.). For both rules, only rare exceptions are accepted and **must** be +discussed first. + +Sometime after a new maintenance branch is created (after a new *minor version* +is released), the old maintenance branch on that major version will go into +:ref:`security mode `, +usually after one last maintenance release at the discretion of the +release manager. For example, the 3.2 maintenance branch was put into +:ref:`security mode ` after the 3.2.4 final maintenance release +following the release of 3.3.0. + +.. _secbranch: + +Security branches +----------------- + +A branch less than 5 years old but no longer in maintenance mode. + +The only changes made to a security branch are those fixing issues exploitable +by attackers such as crashes, privilege escalation and, optionally, other +issues such as denial of service attacks. Any other changes are +**not** considered a security risk and thus not backported to a security branch. + +Commits to security branches are to be coordinated with the release manager +for the corresponding feature version, as listed below in the Summary_. +Any release made from a security branch is source-only and done only when actual +security patches have been applied to the branch. + + +.. _listbranch: + +Summary +------- + +There are 5 open branches right now in the Mercurial repository: + +- the ``default`` branch holds the future 3.5 version and descends from ``3.4`` + (future RM: Larry Hastings) +- the ``3.4`` branch holds bug fixes for future 3.4.x maintenance releases + and descends from ``3.3`` (RM: Larry Hastings) +- the ``3.3`` branch holds security fixes for future 3.3.x maintenance releases + and descends from ``3.2`` (RM: Georg Brandl) +- the ``3.2`` branch holds security fixes for future 3.2.x security releases + (RM: Georg Brandl) +- the ``3.1`` branch holds security fixes for future 3.1.x security releases + (RM: Benjamin Peterson) +- the ``2.7`` branch holds bug fixes for future 2.7.x maintenance releases and + descends from ``2.6`` (RM: Benjamin Peterson) + + +.. _stages: + +Stages +'''''' + +Based on what stage the :ref:`in-development ` version of Python +is in, the responsibilities of a core developer change in regards to commits +to the :abbr:`VCS (version control system)`. + + +Pre-alpha +--------- + +The branch is in this stage when no official release has been done since +the latest final release. There are no special restrictions placed on +commits, although the usual advice applies (getting patches reviewed, avoiding +breaking the buildbots). + +.. _alpha: + +Alpha +----- + +Alpha releases typically serve as a reminder to core developers that they +need to start getting in changes that change semantics or add something to +Python as such things should not be added during a Beta_. Otherwise no new +restrictions are in place while in alpha. + +.. _beta: + +Beta +---- + +After a first beta release is published, no new features are accepted. Only +bug fixes can now be committed. This is when core developers should concentrate +on the task of fixing regressions and other new issues filed by users who have +downloaded the alpha and beta releases. + +Being in beta can be viewed much like being in RC_ but without the extra overhead +of needing commit reviews. + +.. _rc: + +Release Candidate (RC) +---------------------- + +A branch preparing for an RC release can only have bugfixes applied that have +been reviewed by other core developers. Generally, these issues must be +severe enough (e.g. crashes) that they deserve fixing before the final release. +All other issues should be deferred to the next development cycle, since stability +is the strongest concern at this point. + +You **cannot** skip the peer review during an RC, no matter how small! Even if +it is a simple copy-and-paste change, **everything** requires peer review from +a core developer. + +.. _final: + +Final +----- + +When a final release is being cut, only the release manager (RM) can make +changes to the branch. After the final release is published, the full +:ref:`development cycle ` starts again for the next minor version. + diff -r 85f290e474e2 build/_sources/developers.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/developers.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,423 @@ +.. _developers: + +Developer Log +============= + +This file is a running log of developers given commit privileges for Python. + +The purpose is to provide some institutional memory of who was given access +and why. + +The first entry starts in April 2005. In keeping with the style of +Misc/NEWS, newer entries should be added to the top. +Entries should include the initials of the +project admin who made the change or granted access. + +Note, when giving new commit permissions, be sure to get a contributor agreement +from the committer. See http://www.python.org/psf/contrib/ for details. When +the agreement is signed, please note it in this log. SSH keys of the committer +should be sent to hgaccounts@python.org. + +This file is encoded in UTF-8. If the usual form for a name is not in +a Latin or extended Latin alphabet, make sure to include an ASCII +transliteration too. + +Permissions History +------------------- + +- Yury Selivanov was given push privileges on Jan 23 2014 by GFB, for "inspect" + module and general contributions, on recommendation by Nick Coghlan. + +- Donald Stufft was given push privileges on Aug 14 2013 by BAC, for PEP + editing, on the recommendation of Nick Coghlan. + +- Ethan Furman was given push privileges on May 11 2013 by BAC, for PEP 435 + work, on the recommendation of Eli Bendersky. + +- Roger Serwy was given push privileges on Mar 21 2013 by GFB, for IDLE + contributions, on recommendation by Ned Deily. + +- Serhiy Storchaka was given push privileges on Dec 26 2012 by GFB, for general + contributions, on recommendation by Trent Nelson. + +- Chris Jerdonek was given push privileges on Sep 24 2012 by GFB, for general + contributions, on recommendation by Ezio Melotti. + +- Daniel Holth was given push privileges on Sep 9 2012 by GFB, for PEP editing. + +- Eric Snow was given push privileges on Sep 5 2012 by Antoine Pitrou for + general contributions, on recommendation by Nick Coghlan. + +- Peter Moody was given push privileges on May 20 2012 by Antoine Pitrou for + authorship and maintenance of the ipaddress module (accepted in PEP 3144 by + Nick Coghlan). + +- Hynek Schlawack was given push privileges on May 14 2012 by Antoine Pitrou + for general contributions. + +- Richard Oudkerk was given push privileges on Apr 29 2012 by Antoine Pitrou + on recommendation by Charles-François Natali and Jesse Noller, for various + contributions to multiprocessing (and original authorship of + multiprocessing's predecessor, the processing package). + +- Andrew Svetlov was given push privileges on Mar 13 2012 by MvL at + the PyCon sprint. + +- Petri Lehtinen was given push privileges on Oct 22 2011 by GFB, for + general contributions, on recommendation by Antoine Pitrou. + +- Meador Inge was given push privileges on Sep 19 2011 by GFB, for + general contributions, on recommendation by Mark Dickinson. + +- Sandro Tosi was given push privileges on Aug 1 2011 by Antoine Pitrou, + for documentation and other contributions, on recommendation by Ezio + Melotti, R. David Murray and others. + +- Charles-François Natali was given push privileges on May 19 2011 by Antoine + Pitrou, for general contributions, on recommendation by Victor Stinner, + Brian Curtin and others. + +- Nadeem Vawda was given push privileges on Apr 10 2011 by GFB, for + general contributions, on recommendation by Antoine Pitrou. + +- Carl Friedrich Bolz was given push privileges on Mar 21 2011 by BAC, for + stdlib compatibility work for PyPy. + +- Alexis Métaireau, Elson Rodriguez, Kelsey Hightower, Michael Mulich and + Walker Hale were given push privileges on Mar 16 2011 by GFB, for + contributions to the packaging module. + +- Jeff Hardy was given push privileges on Mar 14 2011 by BAC, for stdlib + compatibility work for IronPython. + +- Alex Gaynor and Maciej Fijalkowski were given push privileges on Mar 13 2011 + by BAC, for stdlib compatibility work for PyPy. + +- Ross Lagerwall was given push privileges on Mar 13 2011 by GFB, + on recommendation by Antoine Pitrou and Ned Deily. + +- Eli Bendersky was given commit access on Jan 11 2011 by BAC, + on recommendation by Terry Reedy and Nick Coghlan. + +- Ned Deily was given commit access on Jan 9 2011 by MvL, + on recommendation by Antoine Pitrou. + +- David Malcolm was given commit access on Oct 27 2010 by GFB, + at recommendation by Antoine Pitrou and Raymond Hettinger. + +- Tal Einat was given commit access on Oct 4 2010 by MvL, + for improving IDLE. + +- Łukasz Langa was given commit access on Sep 08 2010 by GFB, + at suggestion of Antoine Pitrou, for general bug fixing. + +- Daniel Stutzbach was given commit access on Aug 22 2010 by MvL, + for general bug fixing. + +- Ask Solem was given commit access on Aug 17 2010 by MvL, + on recommendation by Jesse Noller, for work on the multiprocessing + library. + +- George Boutsioukis was given commit access on Aug 10 2010 + by MvL, for work on 2to3. + +- Éric Araujo was given commit access on Aug 10 2010 by BAC, + at suggestion of Tarek Ziadé. + +- Terry Reedy was given commit access on Aug 04 2010 by MvL, + at suggestion of Nick Coghlan. + +- Brian Quinlan was given commit access on Jul 26 2010 by GFB, + for work related to PEP 3148. + +- Reid Kleckner was given commit access on Jul 11 2010 by GFB, + for work on the py3k-jit branch, at suggestion of the Unladen + Swallow team. + +- Alexander Belopolsky was given commit access on May 25 2010 + by MvL at suggestion of Mark Dickinson. + +- Tim Golden was given commit access on April 21 2010 by MvL, + at suggestion of Michael Foord. + +- Giampaolo Rodolà was given commit access on April 17 2010 by + MvL, at suggestion of R. David Murray. + +- Jean-Paul Calderone was given commit access on April 6 2010 by + GFB, at suggestion of Michael Foord and others. + +- Brian Curtin was given commit access on March 24 2010 by MvL. + +- Florent Xicluna was given commit access on February 25 2010 by + MvL, based on Antoine Pitrou's recommendation. + +- Dino Viehland was given SVN access on February 23 2010 by Brett + Cannon, for backporting tests from IronPython. + +- Larry Hastings was given SVN access on February 22 2010 by + Andrew Kuchling, based on Brett Cannon's recommendation. + +- Victor Stinner was given SVN access on January 30 2010 by MvL, + at recommendation by Mark Dickinson and Amaury Forgeot d'Arc. + +- Stefan Krah was given SVN access on January 5 2010 by GFB, at + suggestion of Mark Dickinson, for work on the decimal module. + +- Doug Hellmann was given SVN access on September 19 2009 by GFB, at + suggestion of Jesse Noller, for documentation work. + +- Ezio Melotti was given SVN access on June 7 2009 by GFB, for work on and + fixes to the documentation. + +- Paul Kippes was given commit privileges at PyCon 2009 by BAC to work on 3to2. + +- Ron DuPlain was given commit privileges at PyCon 2009 by BAC to work on 3to2. + +- Several developers of alternative Python implementations where + given access for test suite and library adaptions by MvL: + Allison Randal (Parrot), Michael Foord (IronPython), + Jim Baker, Philip Jenvey, and Frank Wierzbicki (all Jython). + +- R. David Murray was given SVN access on March 30 2009 by MvL, after + recommendation by BAC. + +- Chris Withers was given SVN access on March 8 2009 by MvL, + after recommendation by GvR. + +- Tarek Ziadé was given SVN access on December 21 2008 by NCN, + for maintenance of distutils. + +- Hirokazu Yamamoto was given SVN access on August 12 2008 by MvL, + for contributions to the Windows build. + +- Antoine Pitrou was given SVN access on July 16 2008, by recommendation + from GvR, for general contributions to Python. + +- Jesse Noller was given SVN access on 16 June 2008 by GFB, + for work on the multiprocessing module. + +- Gregor Lingl was given SVN access on 10 June 2008 by MvL, + for work on the turtle module. + +- Robert Schuppenies was given SVN access on 21 May 2008 by MvL, + for GSoC contributions. + +- Rodrigo Bernardo Pimentel was given SVN access on 29 April 2008 by MvL, + for GSoC contributions. + +- Heiko Weinen was given SVN access on 29 April 2008 by MvL, + for GSoC contributions. + +- Jesus Cea was given SVN access on 24 April 2008 by MvL, + for maintenance of bsddb. + +- Guilherme Polo was given SVN access on 24 April 2008 by MvL, + for GSoC contributions. + +- Thomas Lee was given SVN access on 21 April 2008 by NCN, + for work on branches (ast/optimizer related). + +- Jeroen Ruigrok van der Werven was given SVN access on 12 April 2008 + by GFB, for documentation work. + +- Josiah Carlson was given SVN access on 26 March 2008 by GFB, + for work on asyncore/asynchat. + +- Benjamin Peterson was given SVN access on 25 March 2008 by GFB, + for bug triage work. + +- Jerry Seutter was given SVN access on 20 March 2008 by BAC, for + general contributions to Python. + +- Jeff Rush was given SVN access on 18 March 2008 by AMK, for Distutils work. + +- David Wolever was given SVN access on 17 March 2008 by MvL, + for 2to3 work. + +- Trent Nelson was given SVN access on 17 March 2008 by MvL, + for general contributions to Python. + +- Mark Dickinson was given SVN access on 6 January 2008 by Facundo + Batista for his work on mathematics and number related issues. + +- Amaury Forgeot d'Arc was given SVN access on 9 November 2007 by MvL, + for general contributions to Python. + +- Christian Heimes was given SVN access on 31 October 2007 by MvL, + for general contributions to Python. + +- Chris Monson was given SVN access on 20 October 2007 by NCN, + for his work on editing PEPs. + +- Bill Janssen was given SVN access on 28 August 2007 by NCN, + for his work on the SSL module and other things related to (SSL) sockets. + +- Jeffrey Yasskin was given SVN access on 9 August 2007 by NCN, + for his work on PEPs and other general patches. + +- Mark Summerfield was given SVN access on 1 August 2007 by GFB, + for work on documentation. + +- Armin Ronacher was given SVN access on 23 July 2007 by GFB, + for work on the documentation toolset. He now maintains the + ast module. + +- Senthil Kumaran was given SVN access on 16 June 2007 by MvL, + for his Summer-of-Code project, mentored by Skip Montanaro. + +- Alexandre Vassalotti was given SVN access on 21 May 2007 by MvL, + for his Summer-of-Code project, mentored by Brett Cannon. + +- Travis Oliphant was given SVN access on 17 Apr 2007 by MvL, + for implementing the extended buffer protocol. + +- Ziga Seilnacht was given SVN access on 09 Mar 2007 by MvL, + for general maintenance. + +- Pete Shinners was given SVN access on 04 Mar 2007 by NCN, + for PEP 3101 work in the sandbox. + +- Pat Maupin and Eric V. Smith were given SVN access on 28 Feb 2007 by NCN, + for PEP 3101 work in the sandbox. + +- Steven Bethard (SF name "bediviere") added to the SourceForge Python + project 26 Feb 2007, by NCN, as a tracker tech. + +- Josiah Carlson (SF name "josiahcarlson") added to the SourceForge Python + project 06 Jan 2007, by NCN, as a tracker tech. He will maintain asyncore. + +- Collin Winter was given SVN access on 05 Jan 2007 by NCN, for PEP + update access. + +- Lars Gustaebel was given SVN access on 20 Dec 2006 by NCN, for tarfile.py + related work. + +- 2006 Summer of Code entries: SoC developers are expected to work + primarily in nondist/sandbox or on a branch of their own, and will + have their work reviewed before changes are accepted into the trunk. + + - Matt Fleming was added on 25 May 2006 by AMK; he'll be working on + enhancing the Python debugger. + + - Jackilyn Hoxworth was added on 25 May 2006 by AMK; she'll be adding logging + to the standard library. + + - Mateusz Rukowicz was added on 30 May 2006 by AMK; he'll be + translating the decimal module into C. + +- SVN access granted to the "Need for Speed" Iceland sprint attendees, + between May 17 and 21, 2006, by Tim Peters. All work is to be done + in new sandbox projects or on new branches, with merging to the + trunk as approved: + + Andrew Dalke + Christian Tismer + Jack Diederich + John Benediktsson + Kristján V. Jónsson + Martin Blais + Richard Emslie + Richard Jones + Runar Petursson + Steve Holden + Richard M. Tew + +- Steven Bethard was given SVN access on 27 Apr 2006 by DJG, for PEP + update access. + +- Talin was given SVN access on 27 Apr 2006 by DJG, for PEP update + access. + +- George Yoshida (SF name "quiver") added to the SourceForge Python + project 14 Apr 2006, by Tim Peters, as a tracker admin. See + contemporaneous python-checkins thread with the unlikely Subject: + r45329 - python/trunk/Doc/whatsnew/whatsnew25.tex + +- Ronald Oussoren was given SVN access on 3 Mar 2006 by NCN, for Mac + related work. + +- Bob Ippolito was given SVN access on 2 Mar 2006 by NCN, for Mac + related work. + +- Nick Coghlan requested CVS access so he could update his PEP directly. + Granted by GvR on 16 Oct 2005. + +- Added two new developers for the Summer of Code project. 8 July 2005 + by RDH. Andrew Kuchling will be mentoring Gregory K Johnson for a + project to enhance mailbox. Brett Cannon requested access for Flovis + Bruynooghe (sirolf) to work on pstats, profile, and hotshot. Both users + are expected to work primarily in nondist/sandbox and have their work + reviewed before making updates to active code. + +- Georg Brandl was given SF tracker permissions on 28 May 2005 + by RDH. Since the beginning of 2005, he has been active in discussions + on python-dev and has submitted a dozen patch reviews. The permissions + add the ability to change tracker status and to attach patches. On + 3 June 2005, this was expanded by RDH to include checkin permissions. + +- Terry Reedy was given SF tracker permissions on 7 Apr 2005 by RDH. + +- Nick Coghlan was given SF tracker permissions on 5 Apr 2005 by RDH. + For several months, he has been active in reviewing and contributing + patches. The added permissions give him greater flexibility in + working with the tracker. + +- Eric Price was made a developer on 2 May 2003 by TGP. This was + specifically to work on the new ``decimal`` package, which lived in + ``nondist/sandbox/decimal/`` at the time. + +- Eric S. Raymond was made a developer on 2 Jul 2000 by TGP, for general + library work. His request is archived here: + http://mail.python.org/pipermail/python-dev/2000-July/005314.html + + +Permissions Dropped on Request +------------------------------ + +- Roy Smith, Matt Fleming and Richard Emslie sent drop requests. + 4 Aug 2008 GFB + +- Per note from Andrew Kuchling, the permissions for Gregory K Johnson + and the Summer Of Code project are no longer needed. 4 Aug 2008 GFB + +- Per note from Andrew Kuchling, the permissions for Gregory K Johnson + and the Summer Of Code project are no longer needed. AMK will make + any future checkins directly. 16 Oct 2005 RDH + +- Johannes Gijsbers sent a drop request. 27 July 2005 RDH + +- Flovis Bruynooghe sent a drop request. 14 July 2005 RDH + +- Paul Prescod sent a drop request. 30 Apr 2005 RDH + +- Finn Bock sent a drop request. 13 Apr 2005 RDH + +- Eric Price sent a drop request. 10 Apr 2005 RDH + +- Irmen de Jong requested dropping CVS access while keeping tracker + access. 10 Apr 2005 RDH + +- Moshe Zadka and Ken Manheimer sent drop requests. 8 Apr 2005 by RDH + +- Steve Holden, Gerhard Haring, and David Cole sent email stating that + they no longer use their access. 7 Apr 2005 RDH + + +Permissions Dropped after Loss of Contact +----------------------------------------- + +- Several unsuccessful efforts were made to contact Charles G Waldman. + Removed on 8 Apr 2005 by RDH. + + +Initials of Project Admins +-------------------------- + +* TGP: Tim Peters +* GFB: Georg Brandl +* BAC: Brett Cannon +* NCN: Neal Norwitz +* DJG: David Goodger +* MvL: Martin v. Loewis +* GvR: Guido van Rossum +* RDH: Raymond Hettinger diff -r 85f290e474e2 build/_sources/docquality.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/docquality.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,100 @@ +.. _docquality: + +Helping with Documentation +========================== + +Python is known for having good documentation. But maintaining all of it and +keeping a high level of quality takes a lot of effort. Help is always +appreciated with the documentation, and it requires little programming +experience (with or without Python). + +:ref:`Documenting Python ` covers the details of how Python's documentation works. +It includes an explanation of the markup used (although you can figure a lot +out simply by looking at pre-existing documentation) and :ref:`how to build +` the documentation (which allows you to see how your changes +will look along with validating that your new markup is correct). + +The documentation built from the :ref:`in-development ` and +:ref:`maintenance ` branches can be viewed from +http://docs.python.org/dev/. The in-development and most recent 2.x and 3.x +maintenance :ref:`branches ` are rebuilt once per day. + +If you care to get more involved with documentation, you may also consider +subscribing to the +`docs@python.org mailing list `_. +Documentation issues reported on the `issue tracker`_ are sent here as well as +some bug reports being directly emailed to the mailing list. There is also the +`docs-sig@python.org mailing list +`_ which discusses the +documentation toolchain, projects, standards, etc. + + +Helping with issues filed on the issue tracker +---------------------------------------------- + +If you look at `documentation issues`_ on the `issue tracker`_, you +will find various documentation problems that need work. Issues vary from +typos, to unclear documentation, to something completely lacking documentation. + +If you decide to tackle a documentation issue, you simply :ref:`create a patch +` for the issue and upload it. If you are worried that someone else might +be working simultaneously on the issue, simply leave a comment on the issue +saying you are going to try and create a patch and roughly how long you think +you will take to do it (this allows others to take on the issue if you happen +to forget or lose interest). + +.. _issue tracker: http://bugs.python.org +.. _documentation issues: http://bugs.python.org/issue?%40search_text=&ignore=file%3Acontent&title=&%40columns=title&id=&%40columns=id&stage=&creation=&creator=&activity=&%40columns=activity&%40sort=activity&actor=&nosy=&type=&components=4&versions=&dependencies=&assignee=&keywords=&priority=&%40group=priority&status=1&%40columns=status&resolution=&nosy_count=&message_count=&%40pagesize=50&%40startwith=0&%40queryname=&%40old-queryname=&%40action=search + + +Proofreading +------------ + +While an issue filed on the `issue tracker`_ means there is a known issue +somewhere, that does not mean there are not other issues lurking about in the +documentation. Simply proofreading parts of the documentation is enough to +uncover problems (e.g., documentation that needs to be updated for Python 3 +from Python 2). + +If you decide to proofread, then read a section of the documentation from start +to finish, filing issues in the issue tracker for each problem you find. Don't +file a single issue for an entire section containing multiple problems as that +makes it harder to break the work up for multiple people to help with. + + +.. _helping-with-the-developers-guide: + +Helping with the Developer's Guide +---------------------------------- + +.. highlight:: bash + +The Developer's Guide uses the same process as the main Python documentation, +except for some small differences. The source lives in a `separate +repository`_. Bug reports and patches should be submitted to the `Python +bug tracker`_ using the ``devguide`` component. Changes to the devguide +are normally published within a day, on a schedule that may be different from +the main documentation. + +.. _separate repository: http://hg.python.org/devguide +.. _Python bug tracker: http://bugs.python.org + +To clone the Developer's Guide:: + + $ hg clone http://hg.python.org/devguide + +Core developers should use:: + + $ hg clone ssh://hg@hg.python.org/devguide + +instead so that they can push back their edits to the server. + +To build the devguide, you must have `Sphinx`_ installed. The devguide HTML +can be built by running:: + + $ make html + +in the checkout directory, which will write the files to the ``_build/html`` +directory. + +.. _Sphinx: http://sphinx.pocoo.org/ diff -r 85f290e474e2 build/_sources/documenting.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/documenting.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,1528 @@ +.. _documenting: + +================== +Documenting Python +================== + +The Python language has a substantial body of documentation, much of it +contributed by various authors. The markup used for the Python documentation is +`reStructuredText`_, developed by the `docutils`_ project, amended by custom +directives and using a toolset named `Sphinx`_ to post-process the HTML output. + +This document describes the style guide for our documentation as well as the +custom reStructuredText markup introduced by Sphinx to support Python +documentation and how it should be used. + +The documentation in HTML, PDF or EPUB format is generated from text files +written using the :ref:`reStructuredText format ` and contained in the +:ref:`CPython Mercurial repository `. + +.. _reStructuredText: http://docutils.sf.net/rst.html + +.. note:: + + If you're interested in contributing to Python's documentation, there's no + need to write reStructuredText if you're not so inclined; plain text + contributions are more than welcome as well. Send an e-mail to + docs@python.org or open an issue on the :ref:`tracker `. + + +Introduction +============ + +Python's documentation has long been considered to be good for a free +programming language. There are a number of reasons for this, the most +important being the early commitment of Python's creator, Guido van Rossum, to +providing documentation on the language and its libraries, and the continuing +involvement of the user community in providing assistance for creating and +maintaining documentation. + +The involvement of the community takes many forms, from authoring to bug reports +to just plain complaining when the documentation could be more complete or +easier to use. + +This document is aimed at authors and potential authors of documentation for +Python. More specifically, it is for people contributing to the standard +documentation and developing additional documents using the same tools as the +standard documents. This guide will be less useful for authors using the Python +documentation tools for topics other than Python, and less useful still for +authors not using the tools at all. + +If your interest is in contributing to the Python documentation, but you don't +have the time or inclination to learn reStructuredText and the markup structures +documented here, there's a welcoming place for you among the Python contributors +as well. Any time you feel that you can clarify existing documentation or +provide documentation that's missing, the existing documentation team will +gladly work with you to integrate your text, dealing with the markup for you. +Please don't let the material in this document stand between the documentation +and your desire to help out! + + +Style guide +=========== + +Use of whitespace +----------------- + +All reST files use an indentation of 3 spaces; no tabs are allowed. The +maximum line length is 80 characters for normal text, but tables, deeply +indented code samples and long links may extend beyond that. Code example +bodies should use normal Python 4-space indentation. + +Make generous use of blank lines where applicable; they help grouping things +together. + +A sentence-ending period may be followed by one or two spaces; while reST +ignores the second space, it is customarily put in by some users, for example +to aid Emacs' auto-fill mode. + +Footnotes +--------- + +Footnotes are generally discouraged, though they may be used when they are the +best way to present specific information. When a footnote reference is added at +the end of the sentence, it should follow the sentence-ending punctuation. The +reST markup should appear something like this:: + + This sentence has a footnote reference. [#]_ This is the next sentence. + +Footnotes should be gathered at the end of a file, or if the file is very long, +at the end of a section. The docutils will automatically create backlinks to +the footnote reference. + +Footnotes may appear in the middle of sentences where appropriate. + +Capitalization +-------------- + +.. sidebar:: Sentence case + + Sentence case is a set of capitalization rules used in English + sentences: the first word is always capitalized and other words are + only capitalized if there is a specific rule requiring it. + +In the Python documentation, the use of sentence case in section titles is +preferable, but consistency within a unit is more important than +following this rule. If you add a section to a chapter where most +sections are in title case, you can either convert all titles to +sentence case or use the dominant style in the new section title. + +Sentences that start with a word for which specific rules require +starting it with a lower case letter should be avoided. + +.. note:: + + Sections that describe a library module often have titles in the + form of "modulename --- Short description of the module." In this + case, the description should be capitalized as a stand-alone + sentence. + +Many special names are used in the Python documentation, including the names of +operating systems, programming languages, standards bodies, and the like. Most +of these entities are not assigned any special markup, but the preferred +spellings are given here to aid authors in maintaining the consistency of +presentation in the Python documentation. + +Other terms and words deserve special mention as well; these conventions should +be used to ensure consistency throughout the documentation: + +CPU + For "central processing unit." Many style guides say this should be + spelled out on the first use (and if you must use it, do so!). For + the Python documentation, this abbreviation should be avoided since + there's no reasonable way to predict which occurrence will be the + first seen by the reader. It is better to use the word "processor" + instead. + +POSIX + The name assigned to a particular group of standards. This is always + uppercase. + +Python + The name of our favorite programming language is always capitalized. + +reST + For "reStructuredText," an easy to read, plaintext markup syntax + used to produce Python documentation. When spelled out, it is + always one word and both forms start with a lower case 'r'. + +Unicode + The name of a character coding system. This is always written + capitalized. + +Unix + The name of the operating system developed at AT&T Bell Labs in the early + 1970s. + +Affirmative Tone +---------------- + +The documentation focuses on affirmatively stating what the language does and +how to use it effectively. + +Except for certain security risks or segfault risks, the docs should avoid +wording along the lines of "feature x is dangerous" or "experts only". These +kinds of value judgments belong in external blogs and wikis, not in the core +documentation. + +Bad example (creating worry in the mind of a reader): + + Warning: failing to explicitly close a file could result in lost data or + excessive resource consumption. Never rely on reference counting to + automatically close a file. + +Good example (establishing confident knowledge in the effective use of the language): + + A best practice for using files is use a try/finally pair to explicitly + close a file after it is used. Alternatively, using a with-statement can + achieve the same effect. This assures that files are flushed and file + descriptor resources are released in a timely manner. + +Economy of Expression +--------------------- + +More documentation is not necessarily better documentation. Err on the side +of being succinct. + +It is an unfortunate fact that making documentation longer can be an impediment +to understanding and can result in even more ways to misread or misinterpret the +text. Long descriptions full of corner cases and caveats can create the +impression that a function is more complex or harder to use than it actually is. + +Security Considerations (and Other Concerns) +-------------------------------------------- + +Some modules provided with Python are inherently exposed to security issues +(e.g. shell injection vulnerabilities) due to the purpose of the module +(e.g. :mod:`ssl`). Littering the documentation of these modules with red +warning boxes for problems that are due to the task at hand, rather than +specifically to Python's support for that task, doesn't make for a good +reading experience. + +Instead, these security concerns should be gathered into a dedicated +"Security Considerations" section within the module's documentation, and +cross-referenced from the documentation of affected interfaces with a note +similar to ``"Please refer to the :ref:`security-considerations` section +for important information on how to avoid common mistakes."``. + +Similarly, if there is a common error that affects many interfaces in a +module (e.g. OS level pipe buffers filling up and stalling child processes), +these can be documented in a "Common Errors" section and cross-referenced +rather than repeated for every affected interface. + +Code Examples +------------- + +Short code examples can be a useful adjunct to understanding. Readers can often +grasp a simple example more quickly than they can digest a formal description in +prose. + +People learn faster with concrete, motivating examples that match the context of +a typical use case. For instance, the :func:`str.rpartition` method is better +demonstrated with an example splitting the domain from a URL than it would be +with an example of removing the last word from a line of Monty Python dialog. + +The ellipsis for the :attr:`sys.ps2` secondary interpreter prompt should only be +used sparingly, where it is necessary to clearly differentiate between input +lines and output lines. Besides contributing visual clutter, it makes it +difficult for readers to cut-and-paste examples so they can experiment with +variations. + +Code Equivalents +---------------- + +Giving pure Python code equivalents (or approximate equivalents) can be a useful +adjunct to a prose description. A documenter should carefully weigh whether the +code equivalent adds value. + +A good example is the code equivalent for :func:`all`. The short 4-line code +equivalent is easily digested; it re-emphasizes the early-out behavior; and it +clarifies the handling of the corner-case where the iterable is empty. In +addition, it serves as a model for people wanting to implement a commonly +requested alternative where :func:`all` would return the specific object +evaluating to False whenever the function terminates early. + +A more questionable example is the code for :func:`itertools.groupby`. Its code +equivalent borders on being too complex to be a quick aid to understanding. +Despite its complexity, the code equivalent was kept because it serves as a +model to alternative implementations and because the operation of the "grouper" +is more easily shown in code than in English prose. + +An example of when not to use a code equivalent is for the :func:`oct` function. +The exact steps in converting a number to octal doesn't add value for a user +trying to learn what the function does. + +Audience +-------- + +The tone of the tutorial (and all the docs) needs to be respectful of the +reader's intelligence. Don't presume that the readers are stupid. Lay out the +relevant information, show motivating use cases, provide glossary links, and do +your best to connect-the-dots, but don't talk down to them or waste their time. + +The tutorial is meant for newcomers, many of whom will be using the tutorial to +evaluate the language as a whole. The experience needs to be positive and not +leave the reader with worries that something bad will happen if they make a +misstep. The tutorial serves as guide for intelligent and curious readers, +saving details for the how-to guides and other sources. + +Be careful accepting requests for documentation changes from the rare but vocal +category of reader who is looking for vindication for one of their programming +errors ("I made a mistake, therefore the docs must be wrong ..."). Typically, +the documentation wasn't consulted until after the error was made. It is +unfortunate, but typically no documentation edit would have saved the user from +making false assumptions about the language ("I was surprised by ..."). + + +reStructuredText Primer +======================= + +This section is a brief introduction to reStructuredText (reST) concepts and +syntax, intended to provide authors with enough information to author documents +productively. Since reST was designed to be a simple, unobtrusive markup +language, this will not take too long. + +.. seealso:: + + The authoritative `reStructuredText User + Documentation `_. + + +Paragraphs +---------- + +The paragraph is the most basic block in a reST document. Paragraphs are simply +chunks of text separated by one or more blank lines. As in Python, indentation +is significant in reST, so all lines of the same paragraph must be left-aligned +to the same level of indentation. + + +Inline markup +------------- + +The standard reST inline markup is quite simple: use + +* one asterisk: ``*text*`` for emphasis (italics), +* two asterisks: ``**text**`` for strong emphasis (boldface), and +* backquotes: ````text```` for code samples. + +If asterisks or backquotes appear in running text and could be confused with +inline markup delimiters, they have to be escaped with a backslash. + +Be aware of some restrictions of this markup: + +* it may not be nested, +* content may not start or end with whitespace: ``* text*`` is wrong, +* it must be separated from surrounding text by non-word characters. Use a + backslash escaped space to work around that: ``thisis\ *one*\ word``. + +These restrictions may be lifted in future versions of the docutils. + +reST also allows for custom "interpreted text roles"', which signify that the +enclosed text should be interpreted in a specific way. Sphinx uses this to +provide semantic markup and cross-referencing of identifiers, as described in +the appropriate section. The general syntax is ``:rolename:`content```. + + +Lists and Quotes +---------------- + +List markup is natural: just place an asterisk at the start of a paragraph and +indent properly. The same goes for numbered lists; they can also be +automatically numbered using a ``#`` sign:: + + * This is a bulleted list. + * It has two items, the second + item uses two lines. + + 1. This is a numbered list. + 2. It has two items too. + + #. This is a numbered list. + #. It has two items too. + + +Nested lists are possible, but be aware that they must be separated from the +parent list items by blank lines:: + + * this is + * a list + + * with a nested list + * and some subitems + + * and here the parent list continues + +Definition lists are created as follows:: + + term (up to a line of text) + Definition of the term, which must be indented + + and can even consist of multiple paragraphs + + next term + Description. + + +Paragraphs are quoted by just indenting them more than the surrounding +paragraphs. + + +Source Code +----------- + +Literal code blocks are introduced by ending a paragraph with the special marker +``::``. The literal block must be indented:: + + This is a normal text paragraph. The next paragraph is a code sample:: + + It is not processed in any way, except + that the indentation is removed. + + It can span multiple lines. + + This is a normal text paragraph again. + +The handling of the ``::`` marker is smart: + +* If it occurs as a paragraph of its own, that paragraph is completely left + out of the document. +* If it is preceded by whitespace, the marker is removed. +* If it is preceded by non-whitespace, the marker is replaced by a single + colon. + +That way, the second sentence in the above example's first paragraph would be +rendered as "The next paragraph is a code sample:". + + +Hyperlinks +---------- + +External links +^^^^^^^^^^^^^^ + +Use ```Link text `_`` for inline web links. If the link text +should be the web address, you don't need special markup at all, the parser +finds links and mail addresses in ordinary text. + +Internal links +^^^^^^^^^^^^^^ + +Internal linking is done via a special reST role, see the section on specific +markup, :ref:`doc-ref-role`. + + +Sections +-------- + +Section headers are created by underlining (and optionally overlining) the +section title with a punctuation character, at least as long as the text:: + + ================= + This is a heading + ================= + +Normally, there are no heading levels assigned to certain characters as the +structure is determined from the succession of headings. However, for the +Python documentation, here is a suggested convention: + +* ``#`` with overline, for parts +* ``*`` with overline, for chapters +* ``=``, for sections +* ``-``, for subsections +* ``^``, for subsubsections +* ``"``, for paragraphs + + +Explicit Markup +--------------- + +"Explicit markup" is used in reST for most constructs that need special +handling, such as footnotes, specially-highlighted paragraphs, comments, and +generic directives. + +An explicit markup block begins with a line starting with ``..`` followed by +whitespace and is terminated by the next paragraph at the same level of +indentation. (There needs to be a blank line between explicit markup and normal +paragraphs. This may all sound a bit complicated, but it is intuitive enough +when you write it.) + + +Directives +---------- + +A directive is a generic block of explicit markup. Besides roles, it is one of +the extension mechanisms of reST, and Sphinx makes heavy use of it. + +Basically, a directive consists of a name, arguments, options and content. (Keep +this terminology in mind, it is used in the next chapter describing custom +directives.) Looking at this example, :: + + .. function:: foo(x) + foo(y, z) + :bar: no + + Return a line of text input from the user. + +``function`` is the directive name. It is given two arguments here, the +remainder of the first line and the second line, as well as one option ``bar`` +(as you can see, options are given in the lines immediately following the +arguments and indicated by the colons). + +The directive content follows after a blank line and is indented relative to the +directive start. + + +Footnotes +--------- + +For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote +body at the bottom of the document after a "Footnotes" rubric heading, like so:: + + Lorem ipsum [#]_ dolor sit amet ... [#]_ + + .. rubric:: Footnotes + + .. [#] Text of the first footnote. + .. [#] Text of the second footnote. + +You can also explicitly number the footnotes for better context. + + +Comments +-------- + +Every explicit markup block which isn't a valid markup construct (like the +footnotes above) is regarded as a comment. + + +Source encoding +--------------- + +Since the easiest way to include special characters like em dashes or copyright +signs in reST is to directly write them as Unicode characters, one has to +specify an encoding: + +All Python documentation source files must be in UTF-8 encoding, and the HTML +documents written from them will be in that encoding as well. + + +Gotchas +------- + +There are some problems one commonly runs into while authoring reST documents: + +* **Separation of inline markup:** As said above, inline markup spans must be + separated from the surrounding text by non-word characters, you have to use + an escaped space to get around that. + + +Additional Markup Constructs +============================ + +Sphinx adds a lot of new directives and interpreted text roles to standard reST +markup. This section contains the reference material for these facilities. +Documentation for "standard" reST constructs is not included here, though +they are used in the Python documentation. + +.. note:: + + This is just an overview of Sphinx' extended markup capabilities; full + coverage can be found in `its own documentation + `_. + + +Meta-information markup +----------------------- + +.. describe:: sectionauthor + + Identifies the author of the current section. The argument should include + the author's name such that it can be used for presentation (though it isn't) + and email address. The domain name portion of the address should be lower + case. Example:: + + .. sectionauthor:: Guido van Rossum + + Currently, this markup isn't reflected in the output in any way, but it helps + keep track of contributions. + + +Module-specific markup +---------------------- + +The markup described in this section is used to provide information about a +module being documented. Each module should be documented in its own file. +Normally this markup appears after the title heading of that file; a typical +file might start like this:: + + :mod:`parrot` -- Dead parrot access + =================================== + + .. module:: parrot + :platform: Unix, Windows + :synopsis: Analyze and reanimate dead parrots. + .. moduleauthor:: Eric Cleese + .. moduleauthor:: John Idle + +As you can see, the module-specific markup consists of two directives, the +``module`` directive and the ``moduleauthor`` directive. + +.. describe:: module + + This directive marks the beginning of the description of a module, package, + or submodule. The name should be fully qualified (i.e. including the + package name for submodules). + + The ``platform`` option, if present, is a comma-separated list of the + platforms on which the module is available (if it is available on all + platforms, the option should be omitted). The keys are short identifiers; + examples that are in use include "IRIX", "Mac", "Windows", and "Unix". It is + important to use a key which has already been used when applicable. + + The ``synopsis`` option should consist of one sentence describing the + module's purpose -- it is currently only used in the Global Module Index. + + The ``deprecated`` option can be given (with no value) to mark a module as + deprecated; it will be designated as such in various locations then. + +.. describe:: moduleauthor + + The ``moduleauthor`` directive, which can appear multiple times, names the + authors of the module code, just like ``sectionauthor`` names the author(s) + of a piece of documentation. It too does not result in any output currently. + +.. note:: + + It is important to make the section title of a module-describing file + meaningful since that value will be inserted in the table-of-contents trees + in overview files. + + +Information units +----------------- + +There are a number of directives used to describe specific features provided by +modules. Each directive requires one or more signatures to provide basic +information about what is being described, and the content should be the +description. The basic version makes entries in the general index; if no index +entry is desired, you can give the directive option flag ``:noindex:``. The +following example shows all of the features of this directive type:: + + .. function:: spam(eggs) + ham(eggs) + :noindex: + + Spam or ham the foo. + +The signatures of object methods or data attributes should not include the +class name, but be nested in a class directive. The generated files will +reflect this nesting, and the target identifiers (for HTML output) will use +both the class and method name, to enable consistent cross-references. If you +describe methods belonging to an abstract protocol such as context managers, +use a class directive with a (pseudo-)type name too to make the +index entries more informative. + +The directives are: + +.. describe:: c:function + + Describes a C function. The signature should be given as in C, e.g.:: + + .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) + + This is also used to describe function-like preprocessor macros. The names + of the arguments should be given so they may be used in the description. + + Note that you don't have to backslash-escape asterisks in the signature, + as it is not parsed by the reST inliner. + +.. describe:: c:member + + Describes a C struct member. Example signature:: + + .. c:member:: PyObject* PyTypeObject.tp_bases + + The text of the description should include the range of values allowed, how + the value should be interpreted, and whether the value can be changed. + References to structure members in text should use the ``member`` role. + +.. describe:: c:macro + + Describes a "simple" C macro. Simple macros are macros which are used + for code expansion, but which do not take arguments so cannot be described as + functions. This is not to be used for simple constant definitions. Examples + of its use in the Python documentation include :c:macro:`PyObject_HEAD` and + :c:macro:`Py_BEGIN_ALLOW_THREADS`. + +.. describe:: c:type + + Describes a C type. The signature should just be the type name. + +.. describe:: c:var + + Describes a global C variable. The signature should include the type, such + as:: + + .. cvar:: PyObject* PyClass_Type + +.. describe:: data + + Describes global data in a module, including both variables and values used + as "defined constants." Class and object attributes are not documented + using this directive. + +.. describe:: exception + + Describes an exception class. The signature can, but need not include + parentheses with constructor arguments. + +.. describe:: function + + Describes a module-level function. The signature should include the + parameters, enclosing optional parameters in brackets. Default values can be + given if it enhances clarity. For example:: + + .. function:: repeat([repeat=3[, number=1000000]]) + + Object methods are not documented using this directive. Bound object methods + placed in the module namespace as part of the public interface of the module + are documented using this, as they are equivalent to normal functions for + most purposes. + + The description should include information about the parameters required and + how they are used (especially whether mutable objects passed as parameters + are modified), side effects, and possible exceptions. A small example may be + provided. + +.. describe:: decorator + + Describes a decorator function. The signature should *not* represent the + signature of the actual function, but the usage as a decorator. For example, + given the functions + + .. code-block:: python + + def removename(func): + func.__name__ = '' + return func + + def setnewname(name): + def decorator(func): + func.__name__ = name + return func + return decorator + + the descriptions should look like this:: + + .. decorator:: removename + + Remove name of the decorated function. + + .. decorator:: setnewname(name) + + Set name of the decorated function to *name*. + + There is no ``deco`` role to link to a decorator that is marked up with + this directive; rather, use the ``:func:`` role. + +.. describe:: class + + Describes a class. The signature can include parentheses with parameters + which will be shown as the constructor arguments. + +.. describe:: attribute + + Describes an object data attribute. The description should include + information about the type of the data to be expected and whether it may be + changed directly. This directive should be nested in a class directive, + like in this example:: + + .. class:: Spam + + Description of the class. + + .. data:: ham + + Description of the attribute. + + If is also possible to document an attribute outside of a class directive, + for example if the documentation for different attributes and methods is + split in multiple sections. The class name should then be included + explicitly:: + + .. data:: Spam.eggs + +.. describe:: method + + Describes an object method. The parameters should not include the ``self`` + parameter. The description should include similar information to that + described for ``function``. This directive should be nested in a class + directive, like in the example above. + +.. describe:: decoratormethod + + Same as ``decorator``, but for decorators that are methods. + + Refer to a decorator method using the ``:meth:`` role. + +.. describe:: opcode + + Describes a Python :term:`bytecode` instruction. + +.. describe:: cmdoption + + Describes a Python command line option or switch. Option argument names + should be enclosed in angle brackets. Example:: + + .. cmdoption:: -m + + Run a module as a script. + +.. describe:: envvar + + Describes an environment variable that Python uses or defines. + + +There is also a generic version of these directives: + +.. describe:: describe + + This directive produces the same formatting as the specific ones explained + above but does not create index entries or cross-referencing targets. It is + used, for example, to describe the directives in this document. Example:: + + .. describe:: opcode + + Describes a Python bytecode instruction. + + +Showing code examples +--------------------- + +Examples of Python source code or interactive sessions are represented using +standard reST literal blocks. They are started by a ``::`` at the end of the +preceding paragraph and delimited by indentation. + +Representing an interactive session requires including the prompts and output +along with the Python code. No special markup is required for interactive +sessions. After the last line of input or output presented, there should not be +an "unused" primary prompt; this is an example of what *not* to do:: + + >>> 1 + 1 + 2 + >>> + +Syntax highlighting is handled in a smart way: + +* There is a "highlighting language" for each source file. Per default, + this is ``'python'`` as the majority of files will have to highlight Python + snippets. + +* Within Python highlighting mode, interactive sessions are recognized + automatically and highlighted appropriately. + +* The highlighting language can be changed using the ``highlightlang`` + directive, used as follows:: + + .. highlightlang:: c + + This language is used until the next ``highlightlang`` directive is + encountered. + +* The ``code-block`` directive can be used to specify the highlight language + of a single code block, e.g.:: + + .. code-block:: c + + #include + + void main() { + printf("Hello world!\n"); + } + +* The values normally used for the highlighting language are: + + * ``python`` (the default) + * ``c`` + * ``rest`` + * ``none`` (no highlighting) + +* If highlighting with the current language fails, the block is not highlighted + in any way. + +Longer displays of verbatim text may be included by storing the example text in +an external file containing only plain text. The file may be included using the +``literalinclude`` directive. [1]_ For example, to include the Python source file +:file:`example.py`, use:: + + .. literalinclude:: example.py + +The file name is relative to the current file's path. Documentation-specific +include files should be placed in the ``Doc/includes`` subdirectory. + + +Inline markup +------------- + +As said before, Sphinx uses interpreted text roles to insert semantic markup in +documents. + +Names of local variables, such as function/method arguments, are an exception, +they should be marked simply with ``*var*``. + +For all other roles, you have to write ``:rolename:`content```. + +There are some additional facilities that make cross-referencing roles more +versatile: + +* You may supply an explicit title and reference target, like in reST direct + hyperlinks: ``:role:`title ``` will refer to *target*, but the link + text will be *title*. + +* If you prefix the content with ``!``, no reference/hyperlink will be created. + +* For the Python object roles, if you prefix the content with ``~``, the link + text will only be the last component of the target. For example, + ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only + display ``get`` as the link text. + + In HTML output, the link's ``title`` attribute (that is e.g. shown as a + tool-tip on mouse-hover) will always be the full target name. + +The following roles refer to objects in modules and are possibly hyperlinked if +a matching identifier is found: + +.. describe:: mod + + The name of a module; a dotted name may be used. This should also be used for + package names. + +.. describe:: func + + The name of a Python function; dotted names may be used. The role text + should not include trailing parentheses to enhance readability. The + parentheses are stripped when searching for identifiers. + +.. describe:: data + + The name of a module-level variable or constant. + +.. describe:: const + + The name of a "defined" constant. This may be a C-language ``#define`` + or a Python variable that is not intended to be changed. + +.. describe:: class + + A class name; a dotted name may be used. + +.. describe:: meth + + The name of a method of an object. The role text should include the type + name and the method name. A dotted name may be used. + +.. describe:: attr + + The name of a data attribute of an object. + +.. describe:: exc + + The name of an exception. A dotted name may be used. + +The name enclosed in this markup can include a module name and/or a class name. +For example, ``:func:`filter``` could refer to a function named ``filter`` in +the current module, or the built-in function of that name. In contrast, +``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo`` +module. + +Normally, names in these roles are searched first without any further +qualification, then with the current module name prepended, then with the +current module and class name (if any) prepended. If you prefix the name with a +dot, this order is reversed. For example, in the documentation of the +:mod:`codecs` module, ``:func:`open``` always refers to the built-in function, +while ``:func:`.open``` refers to :func:`codecs.open`. + +A similar heuristic is used to determine whether the name is an attribute of +the currently documented class. + +The following roles create cross-references to C-language constructs if they +are defined in the API documentation: + +.. describe:: c:data + + The name of a C-language variable. + +.. describe:: c:func + + The name of a C-language function. Should include trailing parentheses. + +.. describe:: c:macro + + The name of a "simple" C macro, as defined above. + +.. describe:: c:type + + The name of a C-language type. + +.. describe:: c:member + + The name of a C type member, as defined above. + + +The following role does possibly create a cross-reference, but does not refer +to objects: + +.. describe:: token + + The name of a grammar token (used in the reference manual to create links + between production displays). + + +The following role creates a cross-reference to the term in the glossary: + +.. describe:: term + + Reference to a term in the glossary. The glossary is created using the + ``glossary`` directive containing a definition list with terms and + definitions. It does not have to be in the same file as the ``term`` + markup, in fact, by default the Python docs have one global glossary + in the ``glossary.rst`` file. + + If you use a term that's not explained in a glossary, you'll get a warning + during build. + +--------- + +The following roles don't do anything special except formatting the text +in a different style: + +.. describe:: command + + The name of an OS-level command, such as ``rm``. + +.. describe:: dfn + + Mark the defining instance of a term in the text. (No index entries are + generated.) + +.. describe:: envvar + + An environment variable. Index entries are generated. + +.. describe:: file + + The name of a file or directory. Within the contents, you can use curly + braces to indicate a "variable" part, for example:: + + ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ... + + In the built documentation, the ``x`` will be displayed differently to + indicate that it is to be replaced by the Python minor version. + +.. describe:: guilabel + + Labels presented as part of an interactive user interface should be marked + using ``guilabel``. This includes labels from text-based interfaces such as + those created using :mod:`curses` or other text-based libraries. Any label + used in the interface should be marked with this role, including button + labels, window titles, field names, menu and menu selection names, and even + values in selection lists. + +.. describe:: kbd + + Mark a sequence of keystrokes. What form the key sequence takes may depend + on platform- or application-specific conventions. When there are no relevant + conventions, the names of modifier keys should be spelled out, to improve + accessibility for new users and non-native speakers. For example, an + *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without + reference to a specific application or platform, the same sequence should be + marked as ``:kbd:`Control-x Control-f```. + +.. describe:: keyword + + The name of a Python keyword. Using this role will generate a link to the + documentation of the keyword. ``True``, ``False`` and ``None`` do not use + this role, but simple code markup (````True````), given that they're + fundamental to the language and should be known to any programmer. + +.. describe:: mailheader + + The name of an RFC 822-style mail header. This markup does not imply that + the header is being used in an email message, but can be used to refer to any + header of the same "style." This is also used for headers defined by the + various MIME specifications. The header name should be entered in the same + way it would normally be found in practice, with the camel-casing conventions + being preferred where there is more than one common usage. For example: + ``:mailheader:`Content-Type```. + +.. describe:: makevar + + The name of a :command:`make` variable. + +.. describe:: manpage + + A reference to a Unix manual page including the section, + e.g. ``:manpage:`ls(1)```. + +.. describe:: menuselection + + Menu selections should be marked using the ``menuselection`` role. This is + used to mark a complete sequence of menu selections, including selecting + submenus and choosing a specific operation, or any subsequence of such a + sequence. The names of individual selections should be separated by + ``-->``. + + For example, to mark the selection "Start > Programs", use this markup:: + + :menuselection:`Start --> Programs` + + When including a selection that includes some trailing indicator, such as the + ellipsis some operating systems use to indicate that the command opens a + dialog, the indicator should be omitted from the selection name. + +.. describe:: mimetype + + The name of a MIME type, or a component of a MIME type (the major or minor + portion, taken alone). + +.. describe:: newsgroup + + The name of a Usenet newsgroup. + +.. describe:: option + + A command-line option of Python. The leading hyphen(s) must be included. + If a matching ``cmdoption`` directive exists, it is linked to. For options + of other programs or scripts, use simple ````code```` markup. + +.. describe:: program + + The name of an executable program. This may differ from the file name for + the executable for some platforms. In particular, the ``.exe`` (or other) + extension should be omitted for Windows programs. + +.. describe:: regexp + + A regular expression. Quotes should not be included. + +.. describe:: samp + + A piece of literal text, such as code. Within the contents, you can use + curly braces to indicate a "variable" part, as in ``:file:``. + + If you don't need the "variable part" indication, use the standard + ````code```` instead. + + +The following roles generate external links: + +.. describe:: pep + + A reference to a Python Enhancement Proposal. This generates appropriate + index entries. The text "PEP *number*\ " is generated; in the HTML output, + this text is a hyperlink to an online copy of the specified PEP. + +.. describe:: rfc + + A reference to an Internet Request for Comments. This generates appropriate + index entries. The text "RFC *number*\ " is generated; in the HTML output, + this text is a hyperlink to an online copy of the specified RFC. + + +Note that there are no special roles for including hyperlinks as you can use +the standard reST markup for that purpose. + + +.. _doc-ref-role: + +Cross-linking markup +-------------------- + +To support cross-referencing to arbitrary sections in the documentation, the +standard reST labels are "abused" a bit: Every label must precede a section +title; and every label name must be unique throughout the entire documentation +source. + +You can then reference to these sections using the ``:ref:`label-name``` role. + +Example:: + + .. _my-reference-label: + + Section to cross-reference + -------------------------- + + This is the text of the section. + + It refers to the section itself, see :ref:`my-reference-label`. + +The ``:ref:`` invocation is replaced with the section title. + +Alternatively, you can reference any label (not just section titles) +if you provide the link text ``:ref:`link text ```. + +Paragraph-level markup +---------------------- + +These directives create short paragraphs and can be used inside information +units as well as normal text: + +.. describe:: note + + An especially important bit of information about an API that a user should be + aware of when using whatever bit of API the note pertains to. The content of + the directive should be written in complete sentences and include all + appropriate punctuation. + + Example:: + + .. note:: + + This function is not suitable for sending spam e-mails. + +.. describe:: warning + + An important bit of information about an API that a user should be aware of + when using whatever bit of API the warning pertains to. The content of the + directive should be written in complete sentences and include all appropriate + punctuation. In the interest of not scaring users away from pages filled + with warnings, this directive should only be chosen over ``note`` for + information regarding the possibility of crashes, data loss, or security + implications. + +.. describe:: versionadded + + This directive documents the version of Python which added the described + feature, or a part of it, to the library or C API. When this applies to an + entire module, it should be placed at the top of the module section before + any prose. + + The first argument must be given and is the version in question; if the + addition is only part of the described API element, you should add a second + argument consisting of a *brief* explanation of the change. + + Example:: + + .. versionadded:: 3.1 + The *spam* parameter. + + Note that there must be no blank line between the directive head and the + explanation; this is to make these blocks visually continuous in the markup. + +.. describe:: versionchanged + + Similar to ``versionadded``, but describes when and what changed in the named + feature in some way (changed side effects, platform support, etc.). This one + *must* have the second argument (explanation of the change). + +-------------- + +.. describe:: impl-detail + + This directive is used to mark CPython-specific information. Use either with + a block content or a single sentence as an argument, i.e. either :: + + .. impl-detail:: + + This describes some implementation detail. + + More explanation. + + or :: + + .. impl-detail:: This shortly mentions an implementation detail. + + "\ **CPython implementation detail:**\ " is automatically prepended to the + content. + +.. describe:: seealso + + Many sections include a list of references to module documentation or + external documents. These lists are created using the ``seealso`` directive. + + The ``seealso`` directive is typically placed in a section just before any + sub-sections. For the HTML output, it is shown boxed off from the main flow + of the text. + + The content of the ``seealso`` directive should be a reST definition list. + Example:: + + .. seealso:: + + Module :mod:`zipfile` + Documentation of the :mod:`zipfile` standard module. + + `GNU tar manual, Basic Tar Format `_ + Documentation for tar archive files, including GNU tar extensions. + +.. describe:: rubric + + This directive creates a paragraph heading that is not used to create a + table of contents node. It is currently used for the "Footnotes" caption. + +.. describe:: centered + + This directive creates a centered boldfaced paragraph. Use it as follows:: + + .. centered:: + + Paragraph contents. + + +Table-of-contents markup +------------------------ + +Since reST does not have facilities to interconnect several documents, or split +documents into multiple output files, Sphinx uses a custom directive to add +relations between the single files the documentation is made of, as well as +tables of contents. The ``toctree`` directive is the central element. + +.. describe:: toctree + + This directive inserts a "TOC tree" at the current location, using the + individual TOCs (including "sub-TOC trees") of the files given in the + directive body. A numeric ``maxdepth`` option may be given to indicate the + depth of the tree; by default, all levels are included. + + Consider this example (taken from the library reference index):: + + .. toctree:: + :maxdepth: 2 + + intro + strings + datatypes + numeric + (many more files listed here) + + This accomplishes two things: + + * Tables of contents from all those files are inserted, with a maximum depth + of two, that means one nested heading. ``toctree`` directives in those + files are also taken into account. + * Sphinx knows that the relative order of the files ``intro``, + ``strings`` and so forth, and it knows that they are children of the + shown file, the library index. From this information it generates "next + chapter", "previous chapter" and "parent chapter" links. + + In the end, all files included in the build process must occur in one + ``toctree`` directive; Sphinx will emit a warning if it finds a file that is + not included, because that means that this file will not be reachable through + standard navigation. + + The special file ``contents.rst`` at the root of the source directory is the + "root" of the TOC tree hierarchy; from it the "Contents" page is generated. + + +Index-generating markup +----------------------- + +Sphinx automatically creates index entries from all information units (like +functions, classes or attributes) like discussed before. + +However, there is also an explicit directive available, to make the index more +comprehensive and enable index entries in documents where information is not +mainly contained in information units, such as the language reference. + +The directive is ``index`` and contains one or more index entries. Each entry +consists of a type and a value, separated by a colon. + +For example:: + + .. index:: + single: execution; context + module: __main__ + module: sys + triple: module; search; path + +This directive contains five entries, which will be converted to entries in the +generated index which link to the exact location of the index statement (or, in +case of offline media, the corresponding page number). + +The possible entry types are: + +single + Creates a single index entry. Can be made a subentry by separating the + subentry text with a semicolon (this notation is also used below to describe + what entries are created). +pair + ``pair: loop; statement`` is a shortcut that creates two index entries, + namely ``loop; statement`` and ``statement; loop``. +triple + Likewise, ``triple: module; search; path`` is a shortcut that creates three + index entries, which are ``module; search path``, ``search; path, module`` and + ``path; module search``. +module, keyword, operator, object, exception, statement, builtin + These all create two index entries. For example, ``module: hashlib`` + creates the entries ``module; hashlib`` and ``hashlib; module``. The + builtin entry type is slightly different in that "built-in function" is used + in place of "builtin" when creating the two entries. + +For index directives containing only "single" entries, there is a shorthand +notation:: + + .. index:: BNF, grammar, syntax, notation + +This creates four index entries. + + +Grammar production displays +--------------------------- + +Special markup is available for displaying the productions of a formal grammar. +The markup is simple and does not attempt to model all aspects of BNF (or any +derived forms), but provides enough to allow context-free grammars to be +displayed in a way that causes uses of a symbol to be rendered as hyperlinks to +the definition of the symbol. There is this directive: + +.. describe:: productionlist + + This directive is used to enclose a group of productions. Each production is + given on a single line and consists of a name, separated by a colon from the + following definition. If the definition spans multiple lines, each + continuation line must begin with a colon placed at the same column as in the + first line. + + Blank lines are not allowed within ``productionlist`` directive arguments. + + The definition can contain token names which are marked as interpreted text + (e.g. ``unaryneg ::= "-" `integer```) -- this generates cross-references + to the productions of these tokens. + + Note that no further reST parsing is done in the production, so that you + don't have to escape ``*`` or ``|`` characters. + + +.. XXX describe optional first parameter + +The following is an example taken from the Python Reference Manual:: + + .. productionlist:: + try_stmt: try1_stmt | try2_stmt + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` + + +Substitutions +------------- + +The documentation system provides three substitutions that are defined by default. +They are set in the build configuration file :file:`conf.py`. + +.. describe:: |release| + + Replaced by the Python release the documentation refers to. This is the full + version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``. + +.. describe:: |version| + + Replaced by the Python version the documentation refers to. This consists + only of the major and minor version parts, e.g. ``2.5``, even for version + 2.5.1. + +.. describe:: |today| + + Replaced by either today's date, or the date set in the build configuration + file. Normally has the format ``April 14, 2007``. + + +.. rubric:: Footnotes + +.. [1] There is a standard ``.. include`` directive, but it raises errors if the + file is not found. This one only emits a warning. + + +.. _building-doc: + +Building the documentation +========================== + +The toolset used to build the docs is written in Python and is called Sphinx_. +Sphinx is maintained separately and is not included in this tree. Also needed +are docutils_, supplying the base markup that Sphinx uses; Jinja_, a templating +engine; and optionally Pygments_, a code highlighter. + +To build the documentation, follow the instructions from one of the sections +below. You can view the documentation after building the HTML by pointing +a browser at the file :file:`Doc/build/html/index.html`. + +In the Python 2.7 and 3.3 branches, the Sphinx toolchain will be checked out +using Subversion from ``svn.python.org`` by the Makefile. This toolchain will +need an installed Python 2 to run. + +In the Python 3.4 and later branches, you are expected to have installed a +recent version of Sphinx on your system, so that the Makefile can find the +``sphinx-build`` command. + + +Using make / make.bat +--------------------- + +On Unix, run the following from the root of your :ref:`repository clone +`:: + + cd Doc + make html + +or alternatively ``make -C Doc html``. This builds the output as HTML. + +For Windows users there is a :file:`make.bat` batchfile that tries to work like +``make`` does. + +Available :command:`make` targets are: + + * "html", which builds standalone HTML files for offline viewing. + + * "htmlhelp", which builds HTML files and a HTML Help project file usable to + convert them into a single Compiled HTML (.chm) file -- these are popular + under Microsoft Windows, but very handy on every platform. + + To create the CHM file, you need to run the Microsoft HTML Help Workshop + over the generated project (.hhp) file. + + * "latex", which builds LaTeX source files as input to "pdflatex" to produce + PDF documents. + + * "text", which builds a plain text file for each source file. + + * "linkcheck", which checks all external references to see whether they are + broken, redirected or malformed, and outputs this information to stdout + as well as a plain-text (.txt) file. + + * "changes", which builds an overview over all versionadded/versionchanged/ + deprecated items in the current version. This is meant as a help for the + writer of the "What's New" document. + + * "coverage", which builds a coverage overview for standard library modules + and C API. + + * "pydoc-topics", which builds a Python module containing a dictionary with + plain text documentation for the labels defined in + :file:`Doc/tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic + and keyword help. + + * "suspicious", which checks the parsed markup for text that looks like + malformed and thus unconverted reST. + + +Without make +------------ + +Install the Sphinx package and its dependencies from PyPI. + +Then, from the ``Docs`` directory, run :: + + sphinx-build -b . build/ + +where ```` is one of html, text, latex, or htmlhelp (for explanations +see the make targets above). + +.. _docutils: http://docutils.sourceforge.net/ +.. _Jinja: http://jinja.pocoo.org/ +.. _Pygments: http://pygments.org/ +.. _Sphinx: http://sphinx-doc.org/ diff -r 85f290e474e2 build/_sources/emacs.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/emacs.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,32 @@ +.. _emacs: + +============= +Emacs support +============= + +If you want to edit Python code in Emacs, you should download python-mode.el +and install it somewhere on your load-path. See the project page to download: +https://launchpad.net/python-mode + +While Emacs comes with a python.el file, it is not recommended. +python-mode.el is maintained by core Python developers and is generally +considered more Python programmer friendly. For example, python-mode.el +includes a killer feature called `pdbtrack` which allows you to set a pdb +breakpoint in your code, run your program in an Emacs shell buffer, and do gud +style debugging when the breakpoint is hit. + +python-mode.el is compatible with both GNU Emacs from the FSF, and XEmacs. + +For more information and bug reporting, see the above project page. For help, +development, or discussions, see the python-mode mailing list: +http://mail.python.org/mailman/listinfo/python-mode + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 78 + coding: utf-8 + End: diff -r 85f290e474e2 build/_sources/experts.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/experts.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,338 @@ +.. _experts: + +Experts Index +================= + +This document has tables that list Python Modules, Tools, Platforms and +Interest Areas and names for each item that indicate a maintainer or an +expert in the field. This list is intended to be used by issue submitters, +issue triage people, and other issue participants to find people to add to +the nosy list or to contact directly by email for help and decisions on +feature requests and bug fixes. People on this list may be asked to render +final judgement on a feature or bug. If no active maintainer is listed for +a given module, then questionable changes should go to python-dev, while +any other issues can and should be decided by any committer. + +Unless a name is followed by a '*', you should never assign an issue to +that person, only make them nosy. Names followed by a '*' may be assigned +issues involving the module or topic. + +.. TODO document automatic assignment/nosy: people need not add them manually + +The Platform and Interest Area tables list broader fields in which various +people have expertise. These people can also be contacted for help, +opinions, and decisions when issues involve their areas. + +If a listed maintainer does not respond to requests for comment for an +extended period (three weeks or more), they should be marked as inactive +in this list by placing the word 'inactive' in parenthesis behind their +tracker id. They are of course free to remove that inactive mark at +any time. + +Committers should update these tables as their areas of expertise widen. +New topics may be added to the Interest Area table at will. + +The existence of this list is not meant to indicate that these people +*must* be contacted for decisions; it is, rather, a resource to be used +by non-committers to find responsible parties, and by committers who do +not feel qualified to make a decision in a particular context. + +See also :PEP:`291` and :PEP:`360` for information about certain modules +with special rules. + + +Stdlib +------ +==================== ============================================= +Module Maintainers +==================== ============================================= +__future__ +__main__ gvanrossum, ncoghlan +_dummy_thread brett.cannon +_thread pitrou +abc +aifc r.david.murray +argparse bethard +array +ast benjamin.peterson +asynchat josiahcarlson, giampaolo.rodola, stutzbach +asyncio gvanrossum, haypo, pitrou, yselivanov +asyncore josiahcarlson, giampaolo.rodola, stutzbach +atexit +audioop +base64 +bdb +binascii +binhex +bisect rhettinger +builtins +bz2 nadeem.vawda +calendar rhettinger +cgi +cgitb +chunk +cmath mark.dickinson +cmd +code +codecs lemburg, doerwalter +codeop +collections rhettinger +collections.abc rhettinger, stutzbach +colorsys +compileall +concurrent.futures bquinlan +configparser lukasz.langa* +contextlib ncoghlan* +copy alexandre.vassalotti +copyreg alexandre.vassalotti +cProfile +crypt jafo* +csv skip.montanaro (inactive) +ctypes theller (inactive), belopolsky, amaury.forgeotdarc, + meador.inge +curses +datetime belopolsky +dbm +decimal facundobatista, rhettinger, mark.dickinson +difflib tim.peters (inactive) +dis ncoghlan* +distutils eric.araujo +doctest tim.peters (inactive) +dummy_threading brett.cannon +email barry, r.david.murray* +encodings lemburg, loewis +enum eli.bendersky*, barry, ethan.furman* +errno +exceptions +fcntl +filecmp +fileinput +fnmatch +formatter +fpectl +fractions mark.dickinson, rhettinger +ftplib giampaolo.rodola +functools ncoghlan, rhettinger +gc pitrou +getopt +getpass +gettext loewis +glob +grp +gzip +hashlib christian.heimes, gregory.p.smith +heapq rhettinger, stutzbach +hmac christian.heimes, gregory.p.smith +html ezio.melotti +http +idlelib kbk, terry.reedy, roger.serwy +imaplib +imghdr +imp +importlib brett.cannon +inspect yselivanov +io pitrou, benjamin.peterson, stutzbach +ipaddress pmoody, ncoghlan +itertools rhettinger +json bob.ippolito (inactive), ezio.melotti, rhettinger, pitrou +keyword +lib2to3 benjamin.peterson +linecache +locale loewis, lemburg +logging vinay.sajip +lzma nadeem.vawda +macpath +mailbox petri.lehtinen +mailcap +marshal +math mark.dickinson, rhettinger, stutzbach +mimetypes +mmap +modulefinder theller (inactive), jvr +msilib loewis +msvcrt +multiprocessing jnoller, sbt* +netrc +nis +nntplib pitrou +numbers +operator +optparse aronacher +os loewis +ossaudiodev +parser benjamin.peterson +pathlib pitrou* +pdb georg.brandl* +pickle alexandre.vassalotti, pitrou +pickletools alexandre.vassalotti +pipes +pkgutil +platform lemburg +plistlib +poplib giampaolo.rodola +posix +pprint fdrake +profile georg.brandl +pstats georg.brandl +pty +pwd +py_compile +pybench lemburg, pitrou +pyclbr +pydoc +queue rhettinger +quopri +random rhettinger, mark.dickinson +re effbot (inactive), pitrou, ezio.melotti +readline +reprlib +resource +rlcompleter +runpy ncoghlan +sched giampaolo.rodola +select +selectors +shelve +shlex +shutil tarek, hynek +signal +site +smtpd giampaolo.rodola +smtplib +sndhdr +socket pitrou +socketserver +spwd +sqlite3 ghaering +ssl janssen, pitrou, giampaolo.rodola, christian.heimes +stat christian.heimes +statistics +string georg.brandl* +stringprep +struct mark.dickinson, meador.inge +subprocess astrand (inactive) +sunau +symbol +symtable benjamin.peterson +sys +sysconfig tarek +syslog jafo* +tabnanny tim.peters (inactive) +tarfile lars.gustaebel +telnetlib +tempfile georg.brandl, ncoghlan +termios +test ezio.melotti +textwrap georg.brandl +threading pitrou +time belopolsky +timeit georg.brandl +tkinter gpolo +token georg.brandl +tokenize meador.inge +trace belopolsky +traceback georg.brandl* +tty +turtle gregorlingl +types +unicodedata loewis, lemburg, ezio.melotti +unittest michael.foord*, ezio.melotti +unittest.mock michael.foord* +urllib orsenthil +uu +uuid +venv vinay.sajip +warnings +wave +weakref fdrake, pitrou +webbrowser georg.brandl +winreg stutzbach +winsound effbot (inactive) +wsgiref pje +xdrlib +xml.dom +xml.dom.minidom +xml.dom.pulldom +xml.etree effbot (inactive), eli.bendersky*, scoder +xml.parsers.expat christian.heimes +xml.sax christian.heimes +xml.sax.handler +xml.sax.saxutils +xml.sax.xmlreader +xmlrpc loewis +zipfile alanmcintyre +zipimport +zlib nadeem.vawda +==================== ============================================= + + +Tools +----- +================== =========== +Tool Maintainers +================== =========== +pybench lemburg +================== =========== + + +Platforms +--------- +=================== =========== +Platform Maintainers +=================== =========== +AIX David.Edelsohn +Cygwin jlt63, stutzbach +FreeBSD +HP-UX +Linux +Mac OS X ronaldoussoren, ned.deily, hynek +NetBSD1 +OS2/EMX aimacintyre +Solaris/OpenIndiana jcea +Windows tim.golden +JVM/Java frank.wierzbicki +=================== =========== + + +Miscellaneous +------------- +================== =========== +Interest Area Maintainers +================== =========== +algorithms +ast/compiler ncoghlan, benjamin.peterson, brett.cannon, georg.brandl +autoconf/makefiles +bsd +benchmarks pitrou, brett.cannon +bug tracker ezio.melotti +buildbots pitrou +bytecode benjamin.peterson, pitrou, georg.brandl +context managers ncoghlan +coverity scan christian.heimes, brett.cannon +cryptography christian.heimes, gregory.p.smith +data formats mark.dickinson, georg.brandl +database lemburg +devguide ncoghlan, eric.araujo, ezio.melotti +documentation georg.brandl, ezio.melotti, eric.araujo +GUI +i18n lemburg, eric.araujo +import machinery brett.cannon, ncoghlan, eric.snow +io pitrou, benjamin.peterson, stutzbach, hynek +locale lemburg, loewis +mathematics mark.dickinson, eric.smith, lemburg, stutzbach +memory management tim.peters, lemburg +networking giampaolo.rodola, pitrou +object model benjamin.peterson +packaging tarek, lemburg, alexis, eric.araujo +py3 transition benjamin.peterson +release management tarek, lemburg, benjamin.peterson, barry, loewis, + gvanrossum, anthonybaxter, eric.araujo, ned.deily, + georg.brandl +str.format eric.smith +testing michael.foord, pitrou, ezio.melotti +test coverage ncoghlan, giampaolo.rodola, christian.heimes +threads pitrou +time and dates lemburg, belopolsky +unicode lemburg, ezio.melotti, haypo, benjamin.peterson, pitrou +version control eric.araujo, georg.brandl, ezio.melotti +================== =========== diff -r 85f290e474e2 build/_sources/faq.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/faq.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,996 @@ +:tocdepth: 2 + +.. _faq: + +Python Developer FAQ +~~~~~~~~~~~~~~~~~~~~ + +.. contents:: + :local: + + +Communications +============== + + +Where should I ask general Python questions? +-------------------------------------------- + +General Python questions should still go to `python-list`_ or `tutor`_ +or similar resources, such as StackOverflow_ or the ``#python`` IRC channel +on Freenode_. + +.. _python-list: http://mail.python.org/mailman/listinfo/python-list +.. _tutor: http://mail.python.org/mailman/listinfo/tutor +.. _StackOverflow: http://stackoverflow.com/ +.. _Freenode: http://freenode.net/ + + +.. index:: + single: PEP process; in FAQ + +.. _suggesting-changes: + +Where should I suggest new features and language changes? +--------------------------------------------------------- + +The `python-ideas`_ mailing list is specifically intended for discussion of +new features and language changes. Please don't be disappointed if your +idea isn't met with universal approval: as the long list of Rejected and +Withdrawn PEPs in the `PEP Index`_ attests, and as befits a reasonably mature +programming language, getting significant changes into Python isn't a simple +task. + +If the idea is reasonable, someone will suggest posting it as a feature +request on the `issue tracker`_, or, for larger changes, writing it up as +a `draft PEP`_. + +Sometimes core developers will differ in opinion, or merely be collectively +unconvinced. When there isn't an obvious victor then the +`Status Quo Wins a Stalemate`_ as outlined in the linked post. + +For some examples on language changes that were accepted please read +`Justifying Python Language Changes`_. + +See also the :ref:`langchanges` section of this guide. + +.. _python-ideas: http://mail.python.org/mailman/listinfo/python-ideas +.. _issue tracker: http://bugs.python.org +.. _PEP Index: http://www.python.org/dev/peps +.. _draft PEP: http://www.python.org/dev/peps/pep-0001/ +.. _Status Quo Wins a Stalemate: http://www.curiousefficiency.org/posts/2011/02/status-quo-wins-stalemate.html +.. _Justifying Python Language Changes: http://www.curiousefficiency.org/posts/2011/02/justifying-python-language-changes.html + +Where should I ask general questions about contributing to CPython? +------------------------------------------------------------------- + +The `Python Mentors`_ program is specifically about encouraging +developers and others that would like to contribute to Python development in +general, rather than necessarily being focused on one particular issue. +Some core developers are also available on the ``#python-dev`` IRC channel on +Freenode_. + +.. _Python Mentors: http://pythonmentors.com + + +Where should I report specific problems? +---------------------------------------- + +Specific problems should be posted to the `issue tracker`_. + + +What if I'm not sure it is a bug? +--------------------------------- + +The general Python help locations listed above are the best place to start +with that kind of question. If they agree it looks like a bug, then the +next step is to either post it to the `issue tracker`_ or else to ask further +on the core development mailing list, `python-dev`_. + +.. _python-dev: http://mail.python.org/mailman/listinfo/python-dev + + +What if I disagree with an issue resolution on the tracker? +----------------------------------------------------------- + +First, take some time to consider any comments made in association with the +resolution of the tracker issue. On reflection, they may seem more reasonable +than they first appeared. + +If you still feel the resolution is incorrect, then raise the question on +`python-dev`_. If the consensus there supports the disputed resolution, please +take any further objections to `python-ideas`_ (or some other forum). Further +argument on `python-dev`_ after a consensus has been reached amongst the core +developers is unlikely to win any converts. + + +How do I tell who is and isn't a core developer? +------------------------------------------------ + +You can check their name against the `full list of developers`_ with commit +rights to the main source control repository. + +On the `issue tracker`_, most core developers will have the Python logo +appear next to their name. + +.. _full list of developers: http://hg.python.org/committers.txt + + +What standards of behaviour are expected in these communication channels? +------------------------------------------------------------------------- + +We try to foster environments of mutual respect, tolerance and encouragement, +as described in the PSF's `Diversity Statement`_. Abiding by the guidelines +in this document and asking questions or posting suggestions in the +appropriate channels are an excellent way to get started on the mutual respect +part, greatly increasing the chances of receiving tolerance and encouragement +in return. + +.. _Diversity Statement: http://www.python.org/psf/diversity/ + + +Version Control +=============== + +For everyone +------------ + +The following FAQs are intended for both core developers and contributors. + +Where can I learn about the version control system used, Mercurial (hg)? +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Mercurial_'s (also known as ``hg``) official web site is at +http://mercurial.selenic.com/. A book on Mercurial published by +`O'Reilly Media`_, `Mercurial: The Definitive Guide`_, is available +for free online. Another resource is `Hg Init: a Mercurial tutorial`_ +by Joel Spolsky. + +With Mercurial installed, you can run the help tool that comes with +Mercurial to get help:: + + hg help + +The `man page`_ for ``hg`` provides a quick refresher on the details of +various commands, but doesn't provide any guidance on overall +workflow. + +.. _Mercurial: http://mercurial.selenic.com/ +.. _O'Reilly Media: http://www.oreilly.com/ +.. _Mercurial\: The Definitive Guide: http://hgbook.red-bean.com/ +.. _man page: http://www.selenic.com/mercurial/hg.1.html +.. _Hg Init\: a Mercurial tutorial: http://hginit.com/ + + +I already know how to use Git, can I use that instead? +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + +While the main workflow for core developers requires Mercurial, if +you just want to generate patches with ``git diff`` and post them to the +`issue tracker`_, Petri Lehtinen maintains a `git mirror`_ of the main +`CPython repository`_. To create a local clone based on this mirror rather +than the main repository:: + + git clone git://github.com/akheron/cpython + +The mirror's master branch tracks the main repository's default branch, +while the maintenance branch names (``2.7``, ``3.3``, etc) are mapped +directly. + +.. _git mirror: http://github.com/akheron/cpython +.. _CPython repository: http://hg.python.org/cpython + +Please only use this approach if you're already an experienced Git user and +don't require assistance with the specifics of version control commands. All +other parts of this developer's guide assume the use of Mercurial for local +version control. + + +What do I need to use Mercurial? +'''''''''''''''''''''''''''''''' + +UNIX +^^^^ + +First, you need to `download Mercurial`_. Most UNIX-based operating systems +have binary packages available. Most package management systems also +have native Mercurial packages available. + +If you have push rights, you need OpenSSH_. This is needed to verify +your identity when performing commits. As with Mercurial, binary packages +are typically available either online or through the platform's package +management system. + +Mercurial does not use its own compression via SSH +because it is better to enable compression at the SSH level. Enabling +SSH compression can make cloning a remote repository much faster. +You can configure it in your ``~/.ssh/config`` file; for example:: + + Host hg.python.org + Compression yes + +.. _download Mercurial: http://mercurial.selenic.com/downloads/ +.. _OpenSSH: http://www.openssh.org/ + + +Windows +^^^^^^^ + +The recommended option on Windows is to `download TortoiseHg`_ which +integrates with Windows Explorer and also bundles the command line client +(meaning you can type ``hg`` in a DOS box). Note that most +entries in this FAQ only cover the command line client in detail - refer +to the TortoiseHg documentation for assistance with its graphical interface. + +If you have push rights, you need to configure Mercurial to work with +your SSH keys. For that, open your Mercurial configuration file +(you can do so by opening the TortoiseHg Global Settings dialog and then +clicking *"Edit File"*). If there is no ``[ui]`` section, create it by +typing just that on a line by itself. Then add the following line:: + + ssh = TortoisePlink.exe -ssh -2 -C -i C:\path\to\yourkey.ppk + +where ``C:\path\to\yourkey.ppk`` should be replaced with the actual path +to your SSH private key. + +.. note:: + If your private key is in OpenSSH format, you must first convert it to + PuTTY format by loading it into `PuTTYgen`_. + +.. _download TortoiseHg: http://tortoisehg.bitbucket.org/download/index.html + + +What's a working copy? What's a repository? +''''''''''''''''''''''''''''''''''''''''''' + +Mercurial is a "distributed" version control system. This means that each +participant, even casual contributors, download a complete copy (called a +*clone*, since it is obtained by calling ``hg clone``) of the central +repository which can be treated as a stand-alone repository for all purposes. +That copy is called in the FAQ the *local repository*, to differentiate +with any *remote repository* you might also interact with. + +But you don't modify files directly in the local repository; Mercurial doesn't +allow for it. You modify files in what's called the *working copy* associated +with your local repository: you also run compilations and tests there. +Once you are satisfied with your changes, you can :ref:`commit them `; +committing records the changes as a new *revision* in the *local repository*. + +Changes in your *local repository* don't get automatically shared with the +rest of the world. Mercurial ensures that you have to do so explicitly +(this allows you to experiment quite freely with multiple branches of +development, all on your private computer). The main commands for doing +so are ``hg pull`` and ``hg push``. + + +Which branches are in my local repository? +'''''''''''''''''''''''''''''''''''''''''' + +Typing ``hg branches`` displays the open branches in your local repository:: + + $ hg branches + default 86781:52ec6a3eeda5 + 2.7 86776:dd12639b82bf + 3.3 86779:544b654d000c (inactive) + 3.2 86778:dda1a32748e0 (inactive) + 3.1 86777:b1ddcb220a7f (inactive) + +Why are some branches marked "inactive"? +'''''''''''''''''''''''''''''''''''''''' + +Assuming you get the following output:: + + $ hg branches + default 68042:8ff33af017ef + 3.3 68039:c17d7772c638 (inactive) + +This means all changesets in the "3.3" branch have been merged into the +"default" branch (or any other branch, if such exists). + + +.. _hg-current-branch: + +Which branch is currently checked out in my working copy? +''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Use:: + + $ hg branch + default + +Or to get more information:: + + $ hg summary + parent: 68026:f12ef116dd10 tip + In FTP.close() method, make sure to also close the socket object, not only the file. + branch: default + commit: (clean) + update: (current) + + +.. _hg-switch-branches: + +How do I switch between branches inside my working copy? +'''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Simply use ``hg update`` to checkout another branch in the current directory:: + + $ hg branch + default + $ hg update 3.3 + 86 files updated, 0 files merged, 11 files removed, 0 files unresolved + $ hg branch + 3.3 + +Adding the ``-v`` option to ``hg update`` will list all updated files. + +Note that, due to some previously built executables being used as a part of +the build process, you may sometimes run into issues when attempting to +switch between Python 2.x and Python 3.x branches. In these cases, it is +best to run a ``make distclean`` to ensure that all previously built files +are removed. + + +I want to keep a separate working copy per development branch, is it possible? +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +There are two ways: + +1) Use the "`share extension`_" as described in the :ref:`multiple-clones` + section; +2) Create several clones of your local repository; + +If you want to use the second way, you can do:: + + $ hg clone cpython py33 + updating to branch default + 3434 files updated, 0 files merged, 0 files removed, 0 files unresolved + $ cd py33 + $ hg update 3.3 + 86 files updated, 0 files merged, 11 files removed, 0 files unresolved + +The current branch in a working copy is "sticky": if you pull in some new +changes, ``hg update`` will update to the head of the *current branch*. + +.. _share extension: http://mercurial.selenic.com/wiki/ShareExtension + + +.. _hg-paths: + +How do I link my local repository to a particular remote repository? +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Your local repository is linked by default to the remote repository it +was *cloned* from. If you created it from scratch, however, it is not linked +to any remote repository. In ``.hg/hgrc`` file for the local repository, add +or modify the following section:: + + [paths] + default = ssh://hg@hg.python.org/devguide + +This example is for a local repository that mirrors the ``devguide`` repository +on ``hg.python.org``. The same approach works for other remote repositories. + +Anywhere that ```` is used in the commands in this +FAQ, ``hg`` will use the default remote repository if you omit the parameter. + + +How do I create a shorthand alias for a remote repository? +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +In your global ``.hgrc`` file add a section similar to the following:: + + [paths] + dg = ssh://hg@hg.python.org/devguide + +This example creates a ``dg`` alias for the ``devguide`` repository +on ``hg.python.org``. This allows "dg" to be entered instead of the +full URL for commands taking a repository argument (e.g. ``hg pull dg`` or +``hg outgoing dg``). + +Anywhere that ```` is used in the commands in this +FAQ, ``hg`` should accept an alias in place of a complete remote URL. + + +How do I compare my local repository to a remote repository? +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +To display the list of changes that are in your local repository, but not +in the remote, use:: + + hg outgoing + +This is the list of changes that will be sent if you call +``hg push ``. It does **not** include any :ref:`uncommitted +changes ` in your working copy! + +Conversely, for the list of changes that are in the remote repository but +not in the local, use:: + + hg incoming + +This is the list of changes that will be retrieved if you call +``hg pull ``. + +.. note:: + In most daily use, you will work against the default remote repository, + and therefore simply type ``hg outgoing`` and ``hg incoming``. + + In this case, you can also get a synthetic summary using + ``hg summary --remote``. + + +How do I update my local repository to be in sync with a remote repository? +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Run:: + + hg pull + +from the repository you wish to pull the latest changes into. Most of the +time, that repository is a clone of the repository you want to pull from, +so you can simply type:: + + hg pull + +This doesn't update your working copy, though. See below: + + +How do I update my working copy with the latest changes? +'''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Do:: + + hg update + +This will update your working copy with the latest changes on the +:ref:`current branch `. If you had :ref:`uncommitted +changes ` in your working copy, they will be merged in. + +If you find yourself typing often ``hg pull`` followed by ``hg update``, +be aware that you can combine them in a single command:: + + hg pull -u + + +.. _hg-local-workflow: + +How do I apply a patch? +''''''''''''''''''''''' + +If you want to try out or review a patch generated using Mercurial, do:: + + patch -p1 < somework.patch + +This will apply the changes in your working copy without committing them. +If the patch was not created by Mercurial (for example, a patch created by +Subversion and thus lacking any ``a``/``b`` directory prefixes in the patch), +replace ``-p1`` with ``-p0``. + +If the patch contains renames, deletions or copies, and you intend committing +it after your review, you might prefer using:: + + hg import --no-commit somework.patch + +If you want to work on the patch using mq_ (Mercurial Queues), type instead:: + + hg qimport somework.patch + +This will create a patch in your queue with a name that matches the filename. +You can use the ``-n`` argument to specify a different name. To have the +patch applied to the working copy, type:: + + hg qpush + +Finally, to delete the patch, first un-apply it if necessary using ``hg qpop``, +then do:: + + hg qdelete somework.patch + +.. _extended diff format: http://www.selenic.com/mercurial/hg.1.html#diffs +.. _mq: http://mercurial.selenic.com/wiki/MqExtension + + +.. _merge-patch: + +How do I solve conflicts when applying a patch fails? +''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The standard ``patch`` command, as well as ``hg import``, will produce +unhelpful ``*.rej`` files when it fails applying parts of a patch. +We suggest you try the mpatch_ utility, which can help resolve a number of +common causes of patch rejects. + +To make use of ``mpatch`` transparent, you can define a shell alias in one +of your startup files. For example, if you want it to open the ``kdiff3`` +merge program to fix failing patch hunks:: + + alias patch='mpatch --merge=kdiff3' + +or if you want it to automatically solve conflicts by using heuristics:: + + alias patch='mpatch --auto --no-merge' + +.. _mpatch: http://oss.oracle.com/~mason/mpatch/ + + +How do I add a file or directory to the repository? +''''''''''''''''''''''''''''''''''''''''''''''''''' + +Simply specify the path to the file or directory to add and run:: + + hg add PATH + +If ``PATH`` is a directory, Mercurial will recursively add any files in that +directory and its descendants. + +If you want Mercurial to figure out by itself which files should be added +and/or removed, just run:: + + hg addremove + +**Be careful** though, as it might add some files that are not desired in +the repository (such as build products, cache files, or other data). + +You will then need to run ``hg commit`` (as discussed below) to commit +the file(s) to your local repository. + + +What's the best way to split a file into several files? +''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +To split a file into several files (e.g. a module converted to a package or a +long doc file divided in two separate documents) use ``hg copy``:: + + hg copy module.rst module2.rst + +and then remove the parts that are not necessary from ``module.rst`` and +``module2.rst``. This allows Mercurial to know that the content of +``module2.rst`` used to be in ``module.rst``, and will make subsequent merges +easier. If necessary, you can also use ``hg copy`` several times. + +If you simply create ``module2.rst``, add it with ``hg add``, and copy part of +the content from ``module.rst``, Mercurial won't know that the two file are +related. + + +How do I delete a file or directory in the repository? +'''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Specify the path to be removed with:: + + hg remove PATH + +This will remove the file or the directory from your working copy; you will +have to :ref:`commit your changes ` for the removal to be recorded +in your local repository. + + +.. _hg-status: + +What files are modified in my working copy? +''''''''''''''''''''''''''''''''''''''''''' + +Running:: + + hg status + +will list any pending changes in the working copy. These changes will get +committed to the local repository if you issue an ``hg commit`` without +specifying any path. + +Some +key indicators that can appear in the first column of output are: + + = =========================== + A Scheduled to be added + R Scheduled to be removed + M Modified locally + ? Not under version control + = =========================== + +If you want a line-by-line listing of the differences, use:: + + hg diff + + +How do I revert a file I have modified back to the version in the repository? +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Running:: + + hg revert PATH + +will revert ``PATH`` to its version in the repository, throwing away any +changes you made locally. If you run:: + + hg revert -a + +from the root of your working copy it will recursively restore everything +to match up with the repository. + + +How do I find out who edited or what revision changed a line last? +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +You want:: + + hg annotate PATH + +This will output to stdout every line of the file along with which revision +last modified that line. When you have the revision number, it is then +easy to :ref:`display it in detail `. + + +.. _hg-log: + +How can I see a list of log messages for a file or specific revision? +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +To see the history of changes for a specific file, run:: + + hg log -v [PATH] + +That will list all messages of revisions which modified the file specified +in ``PATH``. If ``PATH`` is omitted, all revisions are listed. + +If you want to display line-by-line differences for each revision as well, +add the ``-p`` option:: + + hg log -vp [PATH] + +.. _hg-log-rev: + +If you want to view the differences for a specific revision, run:: + + hg log -vp -r + + +How can I see the changeset graph in my repository? +''''''''''''''''''''''''''''''''''''''''''''''''''' + +In Mercurial repositories, changesets don't form a simple list, but rather +a graph: every changeset has one or two parents (it's called a merge changeset +in the latter case), and can have any number of children. + +The graphlog_ extension is very useful for examining the structure of the +changeset graph. It is bundled with Mercurial. + +Graphical tools, such as TortoiseHG, will display the changeset graph +by default. + +.. _graphlog: http://mercurial.selenic.com/wiki/GraphlogExtension + + +How do I update to a specific release tag? +'''''''''''''''''''''''''''''''''''''''''' + +Run:: + + hg tags + +to get a list of tags. To update your working copy to a specific tag, use:: + + hg update + + +How do I find which changeset introduced a bug or regression? +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +``hg bisect``, as the name indicates, helps you do a bisection of a range of +changesets. + +You need two changesets to start the search: one that is "good" +(doesn't have the bug), and one that is "bad" (has the bug). Usually, you +have just noticed the bug in your working copy, so you can start with:: + + hg bisect --bad + +Then you must ``update`` to a previous changeset that doesn't have the bug. +You can conveniently choose a faraway changeset (for example a former release), +and check that it is indeed "good". Then type:: + + hg bisect --good + +Mercurial will automatically bisect so as to narrow the range of possible +culprits, until a single changeset is isolated. Each time Mercurial presents +you with a new changeset, re-compile Python and run the offending test, for +example:: + + make -j2 + ./python -m test -uall test_sometest + +Then, type either ``hg bisect --good`` or ``hg bisect --bad`` depending on +whether the test succeeded or failed. + + +How come feature XYZ isn't available in Mercurial? +'''''''''''''''''''''''''''''''''''''''''''''''''' + +Mercurial comes with many bundled extensions which can be explicitly enabled. +You can get a list of them by typing ``hg help extensions``. Some of these +extensions, such as ``color``, can prettify output; others, such as ``fetch`` +or ``graphlog``, add new Mercurial commands. + +There are also many `configuration options`_ to tweak various aspects of the +command line and other Mercurial behaviour; typing `man hgrc`_ displays +their documentation inside your terminal. + +In the end, please refer to the Mercurial `wiki`_, especially the pages about +`extensions`_ (including third-party ones) and the `tips and tricks`_. + + +.. _man hgrc: http://www.selenic.com/mercurial/hgrc.5.html +.. _wiki: http://mercurial.selenic.com/wiki/ +.. _extensions: http://mercurial.selenic.com/wiki/UsingExtensions +.. _tips and tricks: http://mercurial.selenic.com/wiki/TipsAndTricks +.. _configuration options: http://www.selenic.com/mercurial/hgrc.5.html + + +.. _core-devs-faqs: + +For core developers +------------------- + +These FAQs are intended mainly for core developers. + + +.. _hg-commit: + +How do I commit a change to a file? +''''''''''''''''''''''''''''''''''' + +To commit any changes to a file (which includes adding a new file or deleting +an existing one), you use the command:: + + hg commit [PATH] + +``PATH`` is optional: if it is omitted, all changes in your working copy +will be committed to the local repository. When you commit, be sure that all +changes are desired by :ref:`reviewing them first `; +also, when making commits that you intend to push to public repositories, +you should **not** commit together unrelated changes. + +To abort a commit that you are in the middle of, leave the message +empty (i.e., close the text editor without adding any text for the +message). Mercurial will then abort the commit operation so that you can +try again later. + +Once a change is committed to your local repository, it is still only visible +by you. This means you are free to experiment with as many local commits +you feel like. + +.. note:: + If you do not like the default text editor Mercurial uses for + entering commit messages, you may specify a different editor, + either by changing the ``EDITOR`` environment variable or by setting + a Mercurial-specific editor in your global ``.hgrc`` with the ``editor`` + option in the ``[ui]`` section. + + +.. _hg-merge-conflicts: + +How do I solve merge conflicts? +''''''''''''''''''''''''''''''' + +The easiest way is to install KDiff3 --- Mercurial will open it automatically +in case of conflicts, and you can then use it to solve the conflicts and +save the resulting file(s). KDiff3 will also take care of marking the +conflicts as resolved. + +If you don't use a merge tool, you can use ``hg resolve --list`` to list the +conflicting files, resolve the conflicts manually, and the use +``hg resolve --mark `` to mark these conflicts as resolved. +You can also use ``hg resolve -am`` to mark all the conflicts as resolved. + +.. note:: + Mercurial will use KDiff3 automatically if it's installed and it can find + it --- you don't need to change any settings. KDiff3 is also already + included in the installer of TortoiseHg. For more information, see + http://mercurial.selenic.com/wiki/KDiff3. + + +.. _hg-null-merge: + +How do I make a null merge? +''''''''''''''''''''''''''' + +If you committed something (e.g. on 3.3) that shouldn't be ported on newer +branches (e.g. on default), you have to do a *null merge*:: + + cd 3.x + hg merge 3.3 + hg revert -ar default + hg resolve -am # needed only if the merge created conflicts + hg ci -m '#12345: null merge with 3.3.' + +Before committing, ``hg status`` should list all the merged files as ``M``, +but ``hg diff`` should produce no output. This will record the merge without +actually changing the content of the files. + + +.. _hg-heads-merge: + +I got "abort: push creates new remote heads!" while pushing, what do I do? +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +If you see this message while pushing, it means that you committed something +on a clone that was not up to date, thus creating a new head. +This usually happens for two reasons: + +1. You forgot to run ``hg pull`` and/or ``hg up`` before committing; +2. Someone else pushed on the main repo just before you, causing a push race; + +First of all you should pull the new changesets using ``hg pull``. Then you can +use ``hg heads`` to see which branches have multiple heads. + +If only one branch has multiple heads, you can do:: + + cd default + hg heads . + hg up csid-of-the-other-head + hg merge + hg ci -m 'Merge heads.' + +``hg heads .`` will show you the two heads of the current branch: the one you +pulled and the one you created with your commit (you can also specify a branch +with ``hg heads ``). While not strictly necessary, it is highly +recommended to switch to the other head before merging. This way you will be +merging only your changeset with the rest, and in case of conflicts it will be +a lot easier. + +If more than one branch has multiple heads, you have to repeat these steps for +each branch. Since this creates new changesets, you will also have to +:ref:`merge them between branches `. For example, if both ``3.3`` +and ``default`` have multiple heads, you should first merge heads in ``3.3``, +then merge heads in ``default``, and finally merge ``3.3`` with ``default`` +using ``hg merge 3.3`` as usual. + +In order to avoid this, you should *always remember to pull and update before +committing*. + + +How do I undo the changes made in a recent commit? +'''''''''''''''''''''''''''''''''''''''''''''''''' + +First, this should not happen if you take the habit of :ref:`reviewing changes +` before committing them. + +In any case, run:: + + hg backout + +This will modify your working copy so that all changes in ```` +(including added or deleted files) are undone. You then need to :ref:`commit +` these changes so that the backout gets permanently recorded. + +.. note:: + These instructions are for Mercurial 1.7 and higher. ``hg backout`` has + a slightly different behaviour in versions before 1.7. + + +SSH +======= + +How do I generate an SSH 2 public key? +------------------------------------------------------------------------------- + +All generated SSH keys should be sent to hgaccounts@python.org for +adding to the list of keys. + +UNIX +'''' + +Run:: + + ssh-keygen -t rsa + +This will generate two files; your public key and your private key. Your +public key is the file ending in ``.pub``. + +Windows +''''''' + +Use PuTTYgen_ to generate your public key. Choose the "SSH2 DSA" radio button, +have it create an OpenSSH formatted key, choose a password, and save the private +key to a file. Copy the section with the public key (using Alt-P) to a file; +that file now has your public key. + +.. _PuTTYgen: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html + + +Is there a way to avoid having to constantly enter my password for my SSH 2 public key? +--------------------------------------------------------------------------------------- + +UNIX +'''' + +Use ``ssh-agent`` and ``ssh-add`` to register your private key with SSH for +your current session. The simplest solution, though, is to use KeyChain_, +which is a shell script that will handle ``ssh-agent`` and ``ssh-add`` for you +once per login instead of per session. + +.. _KeyChain: http://www.gentoo.org/proj/en/keychain/ + + +.. _pageant: + +Windows +''''''' + +The Pageant program is bundled with TortoiseHg. You can find it in its +installation directory (usually ``C:\Program Files (x86)\TortoiseHg\``); +you can also `download it separately +`_. + +Running Pageant will prevent you from having to type your password constantly. +If you add a shortcut to Pageant to your Autostart group and edit the shortcut +so that the command line includes an argument to your private key then Pageant +will load the key every time you log in. + + +Can I make commits from machines other than the one I generated the keys on? +------------------------------------------------------------------------------ + +You can :ref:`make commits ` from any machine, since they will be +recorded in your *local repository*. + +However, to push these changes to the remote server, you will need proper +credentials. All you need is to make sure that the machine you want to +push changes from has both the public and private keys in the standard +place that ssh will look for them (i.e. ~/.ssh on Unix machines). +Please note that although the key file ending in .pub contains your +user name and machine name in it, that information is not used by the +verification process, therefore these key files can be moved to a +different computer and used for verification. Please guard your keys +and never share your private key with anyone. If you lose the media +on which your keys are stored or the machine on which your keys are +stored, be sure to report this to pydotorg@python.org at the same time +that you change your keys. + + +General +======= + +How do I regenerate configure? +------------------------------ + +If a change is made to Python which relies on some POSIX system-specific +functionality (such as using a new system call), it is necessary to update the +``configure`` script to test for availability of the functionality. + +Python's ``configure`` script is generated from ``configure.ac`` using Autoconf. +Instead of editing ``configure``, edit ``configure.ac`` and then run +``autoreconf`` to regenerate ``configure`` and a number of other files (such as +``pyconfig.h``. + +When submitting a patch with changes made to ``configure.ac``, it is preferred +to leave out the generated files as differences between Autoconf versions +frequently results in many spurious changes cluttering the patch. Instead, +remind any potential reviewers on the tracker to run ``autoreconf``. + +Note that running ``autoreconf`` is not the same as running ``autoconf``. For +example, ``autoconf`` by itself will not regenerate ``pyconfig.h.in``. +``autoreconf`` runs ``autoconf`` and a number of other tools repeatedly as is +appropriate. + +Python's ``configure.ac`` script typically requires a specific version of +Autoconf. At the moment, this reads: ``version_required(2.65)`` + +If the system copy of Autoconf does not match this version, you will need to +install your own copy of Autoconf. + + +How do I update my auto-load-safe-path to allow test_gdb to run? +---------------------------------------------------------------- + +``test_gdb`` attempts to automatically load additional Python specific +hooks into gdb in order to test them. Unfortunately, the command line +options it uses to do this aren't always supported correctly. + +If ``test_gdb`` is being skipped with an "auto-loading has been declined" +message, then it is necessary to identify any Python build directories as +auto-load safe. One way to achieve this is to add a line like the following +to ``~/.gdbinit`` (edit the specific list of paths as appropriate):: + + add-auto-load-safe-path ~/devel/py3k:~/devel/py32:~/devel/py27 diff -r 85f290e474e2 build/_sources/fixingissues.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/fixingissues.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,25 @@ +.. _fixingissues: + +Fixing "easy" Issues (and Beyond) +================================= + +When you feel comfortable enough to want to help tackle issues by trying to +create a patch to fix an issue, you can start by looking at the `"easy" +issues`_. These issues *should* be ones where it should take no longer than a day +or weekend to fix. But because the "easy" classification is typically done at +triage time it can turn out to be inaccurate, so do feel free to leave a +comment if you think the classification no longer applies. + +For the truly adventurous looking for a challenge, you can look for issues that +are not considered easy and try to fix those. It must be warned, though, that +it is quite possible that a bug that has been left open has been left into that +state because of the difficulty compared to the benefit of the fix. It could +also still be open because no consensus has been reached on how to fix the +issue (although having a patch that proposes a fix can turn the tides of the +discussion to help bring it to a close). Regardless of why the issue is open, +you can also always provide useful comments if you do attempt a fix, successful +or not. + +.. _"easy" issues: http://bugs.python.org/issue?status=1&@sort=-activity&@dispname=Easy%20issues&@startwith=0&@filter=&@group=priority&@columns=id,activity,title,creator,status&keywords=6&@action=search&@pagesize=50 + +.. TODO: add something about no active core developer for the area? diff -r 85f290e474e2 build/_sources/gdb.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/gdb.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,291 @@ +.. _gdb: + +gdb Support +=========== + +If you experience low-level problems such as crashes or deadlocks +(e.g. when tinkering with parts of CPython which are written in C), +it can be convenient to use a low-level debugger such as gdb in +order to diagnose and fix the issue. By default, however, gdb (or any +of its front-ends) doesn't know about high-level information specific to the +CPython interpreter, such as which Python function is currently executing, +or what type or value has a given Python object represented by a standard +``PyObject *`` pointer. We hereafter present two ways to overcome this +limitation. + + +gdb 7 and later +--------------- + +In gdb 7, support for `extending gdb with Python +`_ was +added. When CPython is built you will notice a ``python-gdb.py`` file in the +root directory of your checkout. Read the module docstring for details on how +to use the file to enhance gdb for easier debugging of a CPython process. + +This is what a backtrace looks like (truncated) when this extension is +enabled:: + + #0 0x000000000041a6b1 in PyObject_Malloc (nbytes=Cannot access memory at address 0x7fffff7fefe8 + ) at Objects/obmalloc.c:748 + #1 0x000000000041b7c0 in _PyObject_DebugMallocApi (id=111 'o', nbytes=24) at Objects/obmalloc.c:1445 + #2 0x000000000041b717 in _PyObject_DebugMalloc (nbytes=24) at Objects/obmalloc.c:1412 + #3 0x000000000044060a in _PyUnicode_New (length=11) at Objects/unicodeobject.c:346 + #4 0x00000000004466aa in PyUnicodeUCS2_DecodeUTF8Stateful (s=0x5c2b8d "__lltrace__", size=11, errors=0x0, consumed= + 0x0) at Objects/unicodeobject.c:2531 + #5 0x0000000000446647 in PyUnicodeUCS2_DecodeUTF8 (s=0x5c2b8d "__lltrace__", size=11, errors=0x0) + at Objects/unicodeobject.c:2495 + #6 0x0000000000440d1b in PyUnicodeUCS2_FromStringAndSize (u=0x5c2b8d "__lltrace__", size=11) + at Objects/unicodeobject.c:551 + #7 0x0000000000440d94 in PyUnicodeUCS2_FromString (u=0x5c2b8d "__lltrace__") at Objects/unicodeobject.c:569 + #8 0x0000000000584abd in PyDict_GetItemString (v= + {'Yuck': , '__builtins__': , '__file__': 'Lib/test/crashers/nasty_eq_vs_dict.py', '__package__': None, 'y': , 'dict': {0: 0, 1: 1, 2: 2, 3: 3}, '__cached__': None, '__name__': '__main__', 'z': , '__doc__': None}, key= + 0x5c2b8d "__lltrace__") at Objects/dictobject.c:2171 + +(notice how the dictionary argument to ``PyDict_GetItemString`` is displayed +as its ``repr()``, rather than an opaque ``PyObject *`` pointer) + +The extension works by supplying a custom printing routine for values of type +``PyObject *``. If you need to access lower-level details of an object, then +cast the value to a pointer of the appropriate type. For example:: + + (gdb) p globals + $1 = {'__builtins__': , '__name__': + '__main__', 'ctypes': , '__doc__': None, + '__package__': None} + + (gdb) p *(PyDictObject*)globals + $2 = {ob_refcnt = 3, ob_type = 0x3dbdf85820, ma_fill = 5, ma_used = 5, + ma_mask = 7, ma_table = 0x63d0f8, ma_lookup = 0x3dbdc7ea70 + , ma_smalltable = {{me_hash = 7065186196740147912, + me_key = '__builtins__', me_value = }, + {me_hash = -368181376027291943, me_key = '__name__', + me_value ='__main__'}, {me_hash = 0, me_key = 0x0, me_value = 0x0}, + {me_hash = 0, me_key = 0x0, me_value = 0x0}, + {me_hash = -9177857982131165996, me_key = 'ctypes', + me_value = }, + {me_hash = -8518757509529533123, me_key = '__doc__', me_value = None}, + {me_hash = 0, me_key = 0x0, me_value = 0x0}, { + me_hash = 6614918939584953775, me_key = '__package__', me_value = None}}} + +The pretty-printers try to closely match the ``repr()`` implementation of the +underlying implementation of Python, and thus vary somewhat between Python 2 +and Python 3. + +An area that can be confusing is that the custom printer for some types look a +lot like gdb's built-in printer for standard types. For example, the +pretty-printer for a Python 3 ``int`` gives a ``repr()`` that is not +distinguishable from a printing of a regular machine-level integer:: + + (gdb) p some_machine_integer + $3 = 42 + + (gdb) p some_python_integer + $4 = 42 + + (gdb) p *(PyLongObject*)some_python_integer + $5 = {ob_base = {ob_base = {ob_refcnt = 8, ob_type = 0x3dad39f5e0}, ob_size = 1}, + ob_digit = {42}} + +A similar confusion can arise with the ``str`` type, where the output looks a +lot like gdb's built-in printer for ``char *``:: + + (gdb) p ptr_to_python_str + $6 = '__builtins__' + +The pretty-printer for ``str`` instances defaults to using single-quotes (as +does Python's ``repr`` for strings) whereas the standard printer for ``char *`` +values uses double-quotes and contains a hexadecimal address:: + + (gdb) p ptr_to_char_star + $7 = 0x6d72c0 "hello world" + +Here's how to see the implementation details of a ``str`` instance (for Python +3, where a ``str`` is a ``PyUnicodeObject *``):: + + (gdb) p *(PyUnicodeObject*)$6 + $8 = {ob_base = {ob_refcnt = 33, ob_type = 0x3dad3a95a0}, length = 12, + str = 0x7ffff2128500, hash = 7065186196740147912, state = 1, defenc = 0x0} + +As well as adding pretty-printing support for ``PyObject *``, the extension adds a number of commands to gdb + +``py-list`` + List the Python source code (if any) for the current frame in the selected + thread. The current line is marked with a ">":: + + (gdb) py-list + 901 if options.profile: + 902 options.profile = False + 903 profile_me() + 904 return + 905 + >906 u = UI() + 907 if not u.quit: + 908 try: + 909 gtk.main() + 910 except KeyboardInterrupt: + 911 # properly quit on a keyboard interrupt... + + Use ``py-list START`` to list at a different line number within the python + source, and ``py-list START,END`` to list a specific range of lines within + the python source. + +``py-up`` and ``py-down`` + The ``py-up`` and ``py-down`` commands are analogous to gdb's regular ``up`` + and ``down`` commands, but try to move at the level of CPython frames, rather + than C frames. + + gdb is not always able to read the relevant frame information, depending on + the optimization level with which CPython was compiled. Internally, the + commands look for C frames that are executing ``PyEval_EvalFrameEx`` (which + implements the core bytecode interpreter loop within CPython) and look up + the value of the related ``PyFrameObject *``. + + They emit the frame number (at the C level) within the thread. + + For example:: + + (gdb) py-up + #37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/ + gnome_sudoku/main.py, line 906, in start_game () + u = UI() + (gdb) py-up + #40 Frame 0x948e82c, for file /usr/lib/python2.6/site-packages/ + gnome_sudoku/gnome_sudoku.py, line 22, in start_game(main=) + main.start_game() + (gdb) py-up + Unable to find an older python frame + + so we're at the top of the python stack. Going back down:: + + (gdb) py-down + #37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/gnome_sudoku/main.py, line 906, in start_game () + u = UI() + (gdb) py-down + #34 (unable to read python frame information) + (gdb) py-down + #23 (unable to read python frame information) + (gdb) py-down + #19 (unable to read python frame information) + (gdb) py-down + #14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/game_selector.py, line 201, in run_swallowed_dialog (self=, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, 'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\n7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': , 'gsd.hints': 0, 'timer.active_time': , 'timer.total_time': }], dialog=, saved_game_model=, sudoku_maker=, main_page=0) at remote 0x98fa6e4>, d=) + gtk.main() + (gdb) py-down + #8 (unable to read python frame information) + (gdb) py-down + Unable to find a newer python frame + + and we're at the bottom of the python stack. + +``py-bt`` + The ``py-bt`` command attempts to display a Python-level backtrace of the + current thread. + + For example:: + + (gdb) py-bt + #8 (unable to read python frame information) + #11 Frame 0x9aead74, for file /usr/lib/python2.6/site-packages/gnome_sudoku/dialog_swallower.py, line 48, in run_dialog (self=, main_page=0) at remote 0x98fa6e4>, d=) + gtk.main() + #14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/game_selector.py, line 201, in run_swallowed_dialog (self=, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, 'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\n7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': , 'gsd.hints': 0, 'timer.active_time': , 'timer.total_time': }], dialog=, saved_game_model=, sudoku_maker=) + main.start_game() + + The frame numbers correspond to those displayed by gdb's standard ``backtrace`` command. + +``py-print`` + The ``py-print`` command looks up a Python name and tries to print it. It looks in locals within the current thread, then globals, then finally builtins:: + + (gdb) py-print self + local 'self' = , + main_page=0) at remote 0x98fa6e4> + (gdb) py-print __name__ + global '__name__' = 'gnome_sudoku.dialog_swallower' + (gdb) py-print len + builtin 'len' = + (gdb) py-print scarlet_pimpernel + 'scarlet_pimpernel' not found + +``py-locals`` + The ``py-locals`` command looks up all Python locals within the current Python frame in the selected thread, and prints their representations:: + + (gdb) py-locals + self = , + main_page=0) at remote 0x98fa6e4> + d = + +You can of course use other gdb commands. For example, the ``frame`` command takes you directly to a particular frame within the selected thread. We can use it to go a specific frame shown by ``py-bt`` like this:: + + (gdb) py-bt + (output snipped) + #68 Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in () + main() + (gdb) frame 68 + #68 0x00000000004cd1e6 in PyEval_EvalFrameEx (f=Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in (), throwflag=0) at Python/ceval.c:2665 + 2665 x = call_function(&sp, oparg); + (gdb) py-list + 1543 # Run the tests in a context manager that temporary changes the CWD to a + 1544 # temporary and writable directory. If it's not possible to create or + 1545 # change the CWD, the original CWD will be used. The original CWD is + 1546 # available from test_support.SAVEDCWD. + 1547 with test_support.temp_cwd(TESTCWD, quiet=True): + >1548 main() + +The ``info threads`` command will give you a list of the threads within the process, and you can use the ``thread`` command to select a different one:: + + (gdb) info threads + 105 Thread 0x7fffefa18710 (LWP 10260) sem_wait () at ../nptl/sysdeps/unix/sysv/linux/x86_64/sem_wait.S:86 + 104 Thread 0x7fffdf5fe710 (LWP 10259) sem_wait () at ../nptl/sysdeps/unix/sysv/linux/x86_64/sem_wait.S:86 + * 1 Thread 0x7ffff7fe2700 (LWP 10145) 0x00000038e46d73e3 in select () at ../sysdeps/unix/syscall-template.S:82 + +You can use ``thread apply all COMMAND`` or (``t a a COMMAND`` for short) to run a command on all threads. You can use this with ``py-bt`` to see what every thread is doing at the Python level:: + + (gdb) t a a py-bt + + Thread 105 (Thread 0x7fffefa18710 (LWP 10260)): + #5 Frame 0x7fffd00019d0, for file /home/david/coding/python-svn/Lib/threading.py, line 155, in _acquire_restore (self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, count_owner=(1, 140737213728528), count=1, owner=140737213728528) + self.__block.acquire() + #8 Frame 0x7fffac001640, for file /home/david/coding/python-svn/Lib/threading.py, line 269, in wait (self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, acquire=, _is_owned=, _release_save=, release=, _acquire_restore=, _Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, timeout=None, waiter=, saved_state=(1, 140737213728528)) + self._acquire_restore(saved_state) + #12 Frame 0x7fffb8001a10, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 348, in f () + cond.wait() + #16 Frame 0x7fffb8001c40, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 37, in task (tid=140737213728528) + f() + + Thread 104 (Thread 0x7fffdf5fe710 (LWP 10259)): + #5 Frame 0x7fffe4001580, for file /home/david/coding/python-svn/Lib/threading.py, line 155, in _acquire_restore (self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, count_owner=(1, 140736940992272), count=1, owner=140736940992272) + self.__block.acquire() + #8 Frame 0x7fffc8002090, for file /home/david/coding/python-svn/Lib/threading.py, line 269, in wait (self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, acquire=, _is_owned=, _release_save=, release=, _acquire_restore=, _Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, timeout=None, waiter=, saved_state=(1, 140736940992272)) + self._acquire_restore(saved_state) + #12 Frame 0x7fffac001c90, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 348, in f () + cond.wait() + #16 Frame 0x7fffac0011c0, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 37, in task (tid=140736940992272) + f() + + Thread 1 (Thread 0x7ffff7fe2700 (LWP 10145)): + #5 Frame 0xcb5380, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 16, in _wait () + time.sleep(0.01) + #8 Frame 0x7fffd00024a0, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 378, in _check_notify (self=, skipped=[], _mirrorOutput=False, testsRun=39, buffer=False, _original_stderr=, _stdout_buffer=, _stderr_buffer=, _moduleSetUpFailed=False, expectedFailures=[], errors=[], _previousTestClass=, unexpectedSuccesses=[], failures=[], shouldStop=False, failfast=False) at remote 0xc185a0>, _threads=(0,), _cleanups=[], _type_equality_funcs={: , : , : , : , `_ +that adding the floor division +operator (//) broke the parser module. + + +Checklist +--------- + +* Grammar/Grammar: OK, you'd probably worked this one out :) + +* Parser/Python.asdl may need changes to match the Grammar. Run make to + regenerate Include/Python-ast.h and Python/Python-ast.c. + +* Python/ast.c will need changes to create the AST objects involved with the + Grammar change. + +* Parser/pgen needs to be rerun to regenerate Include/graminit.h and + Python/graminit.c. (make should handle this for you.) + +* Python/symtable.c: This handles the symbol collection pass + that happens immediately before the compilation pass. + +* Python/compile.c: You will need to create or modify the + compiler_* functions to generate opcodes for your productions. + +* You may need to regenerate Lib/symbol.py and/or Lib/token.py + and/or Lib/keyword.py. + +* The parser module. Add some of your new syntax to test_parser, + bang on Modules/parsermodule.c until it passes. + +* Add some usage of your new syntax to test_grammar.py + +* If you've gone so far as to change the token structure of + Python, then the Lib/tokenizer.py library module will need to be changed. + +* Certain changes may require tweaks to the library module pyclbr. + +* Documentation must be written! + +* After everything has been checked in, you're likely to see a new + change to Python/Python-ast.c. This is because this + (generated) file contains the hg version of the source from + which it was generated. There's no way to avoid this; you just + have to submit this file separately. diff -r 85f290e474e2 build/_sources/help.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/help.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,69 @@ +.. _help: + +Where to Get Help +================= + +If you are working on Python it is very possible you will come across an issue +where you need some assistance to solve it (this happens to core developers +all the time). + +Should you require help, there are a :ref:`variety of options available +` to seek assistance. If the question involves process or tool +usage then please check the rest of this guide first (especially the +:ref:`FAQ`) as it should answer your question. + + +Ask #python-dev +----------------- + +If you are comfortable with IRC you can try asking on ``#python-dev`` (on +the `freenode`_ network). Typically there are a number of experienced +developers, ranging from triagers to core developers, who can answer +questions about developing for Python. Just remember that ``#python-dev`` +is for questions involving the development *of* Python whereas ``#python`` +is for questions concerning development *with* Python. + +.. _freenode: http://freenode.net/ + + +Core Mentorship +--------------- + +If you are interested in improving Python and contributing to its development, +but don’t yet feel entirely comfortable with the public channels mentioned +above, `Python Mentors`_ are here to help you. Python is fortunate to have a +community of volunteer core developers willing to mentor anyone wishing to +contribute code, work on bug fixes or improve documentation. Everyone is +welcomed and encouraged to contribute. + +.. _Python Mentors: http://pythonmentors.com + + +Mailing Lists +------------- + +Further options for seeking assistance include the `python-ideas`_ and +`python-dev`_ mailing lists. Python-ideas contains discussion of speculative +Python language ideas for possible inclusion into the language. If an idea +gains traction it can then be discussed and honed to the point of becoming a +solid proposal and presented on python-dev. Python-dev contains discussion +of current Python design issues, release mechanics, and maintenance of +existing releases. As with ``#python-dev``, these mailing lists are for +questions involving the development *of* Python, **not** for development +*with* Python. + +.. _python-ideas: http://mail.python.org/mailman/listinfo/python-ideas +.. _python-dev: http://mail.python.org/mailman/listinfo/python-dev + + +File a Bug +---------- + +If you strongly suspect you have stumbled on a bug (be it in the build +process, in the test suite, or in other areas), then open an issue on the +`issue tracker`_. As with every bug report it is strongly advised that +you detail which conditions triggered it (including the OS name and version, +and what you were trying to do), as well as the exact error message you +encountered. + +.. _issue tracker: http://bugs.python.org diff -r 85f290e474e2 build/_sources/index.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/index.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,230 @@ +======================== +Python Developer's Guide +======================== + +This guide is a comprehensive resource for :ref:`contributing ` +to Python_ -- for both new and experienced contributors. It is +:ref:`maintained ` by the same community +that maintains Python. We welcome your contributions to Python! + + +Quick Start +----------- + +Here are the basic steps needed to get :ref:`set up ` and contribute a +patch: + +1. :ref:`Get the source code `:: + + hg clone http://hg.python.org/cpython + +2. :ref:`Build Python `. On :ref:`UNIX `:: + + ./configure --with-pydebug && make -j2 + + On :ref:`Windows `, open the solution file + :file:`PCbuild\\pcbuild.sln` in Visual Studio, select :menuselection:`Debug`, + and :menuselection:`Build --> Build Solution`. Run + :file:`Tools\\buildbot\\external.bat` or + :file:`Tools\\buildbot\\external-amd64.bat` to download and compile 3rd + party libraries. Note: Visual Studio may throw errors, but Python will + be built. + +3. :doc:`Run the tests `:: + + ./python -m test -j3 + + On :ref:`most ` Mac OS X systems, replace :file:`./python` + with :file:`./python.exe`. On Windows, use :file:`PCbuild\\python_d.exe` or + check the :ref:`Windows instructions `. With Python 2.7, + replace ``test`` with ``test.regrtest``. +4. Make the :doc:`patch `. +5. Submit it to the `issue tracker`_. + + +Quick Links +----------- + +Here are some links that you probably will reference frequently while +contributing to Python. + +* `Issue tracker`_ +* `Buildbot status`_ +* :doc:`faq` +* PEPs_ (Python Enhancement Proposals) + + +.. _contributing: + +Contributing +------------ + +We encourage everyone to contribute to Python and that's why we have put up this +developer's guide. If you still have questions after reviewing the material in +this guide, then the `Python Mentors`_ group is available to help guide new +contributors through the process. The :doc:`Developer FAQ ` is another +useful source of information. + +Guide for contributing to Python: + +* :doc:`setup` +* :doc:`help` +* :doc:`patch` +* :doc:`runtests` +* Beginner tasks to become familiar with the development process + * :doc:`docquality` + * :doc:`coverage` +* Advanced tasks for once you are comfortable + * :doc:`silencewarnings` + * Fixing issues found by the :doc:`buildbots ` + * :doc:`fixingissues` +* :ref:`tracker` and :ref:`helptriage` + * :doc:`triaging` +* :doc:`communication` +* :doc:`coredev` + * :doc:`committing` + * :doc:`devcycle` + * :doc:`buildbots` + * :doc:`coverity` + +It is **recommended** that the above documents be read in the order listed. You +can stop where you feel comfortable and begin contributing immediately without +reading and understanding these documents all at once. If you do choose to skip +around within the documentation, be aware that it is written assuming preceding +documentation has been read so you may find it necessary to backtrack to fill in +missing concepts and terminology. + + +Proposing changes to Python itself +---------------------------------- + +Improving Python's code, documentation and tests are ongoing tasks that are +never going to be "finished", as Python operates as part of an ever-evolving +system of technology. An even more challenging ongoing task than these +necessary maintenance activities is finding ways to make Python, in the form of +the standard library and the language definition, an even better tool in a +developer's toolkit. + +While these kinds of change are much rarer than those described above, they do +happen and that process is also described as part of this guide: + +* :doc:`stdlibchanges` +* :doc:`langchanges` + +Also refer to :ref:`suggesting-changes` in the FAQ. + + +Other Interpreter Implementations +--------------------------------- + +This guide is specifically for contributing to the Python reference interpreter, +also known as CPython (while most of the standard library is written in Python, +the interpreter core is written in C and integrates most easily with the C and +C++ ecosystems). + +There are other Python implementations, each with a different focus. Like +CPython, they always have more things they would like to do than they have +developers to work on them. Some major example that may be of interest are: + +* PyPy_: A Python interpreter focused on high speed (JIT-compiled) operation + on major platforms +* Jython_: A Python interpreter focused on good integration with the Java + Virtual Machine (JVM) environment +* IronPython_: A Python interpreter focused on good integration with the + Common Language Runtime (CLR) provided by .NET and Mono +* Stackless_: A Python interpreter focused on providing lightweight + microthreads while remaining largely compatible with CPython specific + extension modules + + +Key Resources +------------- + +* Coding style guides + * :PEP:`7` (Style Guide for C Code) + * :PEP:`8` (Style Guide for Python Code) +* `Issue tracker`_ + * `Meta tracker `_ (issue + tracker for the issue tracker) + * :doc:`experts` + * `Firefox search engine plug-in`_ +* `Buildbot status`_ +* Source code + * `Browse online `_ + * `Snapshot of py3k `_ + * `Daily OS X installer `_ +* PEPs_ (Python Enhancement Proposals) +* :doc:`faq` +* :doc:`developers` + + +.. _resources: + +Additional Resources +-------------------- + +* Anyone can clone the sources for this guide. See + :ref:`helping-with-the-developers-guide`. +* Help with ... + * :doc:`grammar` + * :doc:`compiler` +* Tool support + * :doc:`emacs` + * :doc:`gdb` + * :doc:`clang` + * Various tools with configuration files as found in the `Misc directory`_ +* `python.org maintenance`_ + +* :ref:`Search this guide ` + + +.. _contents: + +Full Table of Contents +---------------------- + +.. toctree:: + :numbered: + + setup + setupwindows + help + patch + runtests + coverage + docquality + documenting + silencewarnings + fixingissues + tracker + triaging + communication + coredev + developers + committing + devcycle + buildbots + stdlibchanges + langchanges + experts + emacs + gdb + grammar + compiler + coverity + clang + faq + + +.. _Buildbot status: http://python.org/dev/buildbot/ +.. _Firefox search engine plug-in: http://www.python.org/dev/searchplugin/ +.. _Misc directory: http://hg.python.org/cpython/file/default/Misc +.. _PEPs: http://www.python.org/dev/peps +.. _python.org maintenance: http://python.org/dev/pydotorg/ +.. _Python: http://www.python.org/ +.. _Python Mentors: http://pythonmentors.com/ +.. _PyPy: http://www.pypy.org/ +.. _Jython: http://www.jython.org/ +.. _IronPython: http://ironpython.net/ +.. _Stackless: http://www.stackless.com/ +.. _Issue tracker: http://bugs.python.org/ diff -r 85f290e474e2 build/_sources/langchanges.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/langchanges.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,63 @@ +.. _langchanges: + +Changing the Python Language +============================ +On occasion people come up with an idea on how to change or improve Python as a +programming language. This document is meant to explain exactly what changes +have a reasonable chance of being considered and what the process is to propose +changes to the language. + + +What Qualifies +-------------- +First and foremost, it must be understood that changes to the Python +programming language are difficult to make. When the language changes, +**every** Python programmer already in existence and all Python programmers to +come will end up eventually learning about the change you want to propose. +Books will need updating, code will be changed, and a new way to do things will +need to be learned. Changes to the Python programming language are never taken +lightly. + +Because of the seriousness that language changes carry, any change must be +beneficial to a large proportion of Python users. If the change only benefits a +small percentage of Python developers then the change will not be made. A good +way to see if your idea would work for a large portion of the Python community +is to ask on :ref:`python-list or python-ideas `. You can also +go through Python's stdlib and find examples of code which would benefit from +your proposed change (which helps communicate the usefulness of your change to +others). For further guidance, see :ref:`suggesting-changes` in the FAQ. + +Your proposed change also needs to be *Pythonic*. While Guido is the only +person who can truly classify something as Pythonic, you can read the `Zen of +Python`_ for guidance. + +.. _Zen of Python: http://www.python.org/dev/peps/pep-0020/ + + +.. index:: PEP process + +PEP Process +----------- +Once you are certain you have a language change proposal which will appeal to +the general Python community, you can begin the process of officially proposing +the change. This process is the Python Enhancement Proposal (PEP) process. +:PEP:`1` describes it in detail. + +You will first need a PEP that you will present to python-ideas. You may be a +little hazy on the technical details as various core developers can help with +that, but do realize that if you do not present your idea to python-ideas or +python-list ahead of time you may find out it is technically not possible +(e.g., Python's parser will not support the grammar change as it is an LL(1) +parser). Expect extensive comments on the PEP, some of which will be negative. + +Once your PEP has been modified to be of proper quality and to take into +account comments made on python-ideas, it may proceed to python-dev. There it +will be assigned a PEP dictator and another general discussion will occur. Once +again, you will need to modify your PEP to incorporate the large amount of +comments you will receive. + +The PEP dictator decides if your PEP is accepted (typically based on whether +most core developers support the PEP). If that occurs then your proposed +language change will be introduced in the next release of Python. Otherwise +your PEP will be recorded as rejected along with an explanation as to why so +that others do not propose the same language change in the future. diff -r 85f290e474e2 build/_sources/patch.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/patch.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,187 @@ +.. _patch: + +Lifecycle of a Patch +==================== + + +Creating +-------- + +Tool Usage +'''''''''' + +.. _workflow: + +Mercurial allows for various workflows according to each person's or +project's preference. It is out of this guide's scope to present them all, +so we will stick to a basic workflow where you work on a patch in your +working copy without ever making any local commits. + +If you use this workflow, and your work adds or removes files to the +source tree, you will have to temporarily ``hg add`` or ``hg remove`` them, +respectively, before generating a patch. + +To generate a patch, just invoke ``hg diff`` which will print out a +patch of the working copy's changes against the current revision:: + + hg diff > mywork.patch + +If you want to undo your changes, you can revert them from the working copy:: + + hg revert -a + +You can later re-apply the changes if you want to continue working on the +patch:: + + hg import --no-commit mywork.patch + + +.. seealso:: + Refer to the :ref:`FAQ ` for + :ref:`more information on using Mercurial `. + + +Preparation +''''''''''' + +When creating a patch for submission, there are several things that you should +do to help ensure that your patch is accepted. + +First, make sure to follow Python's style guidelines. For Python code you +should follow :PEP:`8`, and for C code you should follow :PEP:`7`. If you have +one or two discrepancies those can be fixed by the core developer who commits +your patch. But if you have systematic deviations from the style guides your +patch will be put on hold until you fix the formatting issues. + +Second, be aware of backwards-compatibility considerations. While the core +developer who eventually handles your patch will make the final call on whether +something is acceptable, thinking about backwards-compatibility early +will help prevent having your patch rejected on these grounds. Put yourself in +the shoes of someone whose code will be broken by the change(s) introduced by +the patch. It is quite likely that any change made will break +someone's code, so you need to have a good reason to make a change as you will +be forcing someone to update their code. (This obviously does not apply to new +classes or functions; new arguments should be optional and have default values +which maintain the existing behavior.) If in doubt, have a look at +:PEP:`387` or :ref:`discuss ` the issue with experienced +developers. + +Third, make sure you have proper tests to verify your patch works as expected. +Patches will not be accepted without the proper tests! + +Fourth, make sure the entire test suite :ref:`runs ` **without +failure** because of your changes. It is not sufficient to only run whichever +test seems impacted by your changes, because there might be interferences +unknown to you between your changes and some other part of the interpreter. + +Fifth, proper :ref:`documentation ` +additions/changes should be included. + + +.. _patch-generation: + +Generation +'''''''''' + +To perform a quick sanity check on your patch, you can run:: + + make patchcheck + +This will check and/or fix various common things people forget to do for +patches, such as adding any new files needed for the patch to work (note +that not all checks apply to non-core developers). On Windows, use this +command:: + + ./python.exe Tools/scripts/patchcheck.py + +Assuming you are using the :ref:`basic approach ` suggested earlier, +just type the following:: + + hg diff > mywork.patch + +If you are using another approach, you probably need to find out the right +invocation of ``hg diff`` for your purposes; see ``hg help diff`` and ``hg +help revisions``. Just please make sure that you generate a +**single, condensed** patch rather than a series of several changesets. + + +Licensing +--------- + +For non-trivial changes, we must have your formal approval for distributing +your work under the `PSF license`_. Therefore, you need to fill out a +`contributor form`_ which allows the `Python Software Foundation`_ to +license your code for use with Python (you retain the copyright). + +.. note:: + You only have to sign this document once, it will then apply to all + your further contributions to Python. + + +.. _PSF license: http://docs.python.org/3.4/license.html#terms-and-conditions-for-accessing-or-otherwise-using-python +.. _contributor form: http://www.python.org/psf/contrib/ +.. _Python Software Foundation: http://www.python.org/psf/ + + +Submitting +---------- + +If this is a patch in response to a pre-existing issue on the `issue tracker`_, +attach the patch to the issue; use the ``Choose File`` button on the tracker +web page for the issue to upload your patch file. Please provide any details +about your patch that +would be relevant to the discussion of the issue or your patch. + +If this is a patch for an unreported issue (assuming you already performed a +search on the issue tracker for a pre-existing issue), create a new issue and +attach your patch. Please fill in as much relevant detail as possible to +prevent patch reviewers from having to delay reviewing your patch because of +lack of information. + + +.. _issue tracker: http://bugs.python.org + + +Reviewing +--------- + +To begin with, please be patient! There are many more people submitting patches +than there are people capable of reviewing your patch. Getting your patch +reviewed requires a reviewer to have the spare time and motivation to +look at your patch (we cannot force anyone to review patches). If your patch has +not received any notice from reviewers (i.e., no comment made) after one +month, first "ping" the issue on the `issue tracker`_ to remind the nosy list +that the patch needs a review. If you don't get a response within a few days +after pinging the issue, then you can try emailing python-dev@python.org asking +for someone to review your patch. + +When someone does manage to find the time to look at your patch they will most +likely make comments about how it can be improved (don't worry, even core +developers of Python have their patches sent back to them for changes). It +is then expected that you post a new patch addressing these comments, and the +review process will thus iterate until a satisfactory solution has emerged. + + +Committing/Rejecting +-------------------- + +Once your patch has reached an acceptable state (and thus considered +"accepted"), it will either be committed or rejected. If it is rejected, please +do not take it personally! Your work is still appreciated regardless of whether +your patch is committed. Balancing what *does* and *does not* go into Python +is tricky and we simply cannot accept everyone's contributions. + +But if your patch is committed it will then go into Python's +:abbr:`VCS (version control system)` to be released +with the next major release of Python. It may also be backported to older +versions of Python as a bugfix if the core developer doing the commit believes +it is warranted. + + +Crediting +--------- + +Non-trivial contributions are credited in the ``Misc/ACKS`` file (and, most +often, in a contribution's ``Misc/NEWS`` entry as well). This is something +the core developer will do when committing your patch, you don't have to +propose the addition by yourself. diff -r 85f290e474e2 build/_sources/runtests.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/runtests.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,120 @@ +.. _runtests: + +Running & Writing Tests +======================= + +.. note:: + + This document assumes you are working from an + :ref:`in-development ` checkout of Python. If you + are not then some things presented here may not work as they may depend + on new features not available in earlier versions of Python. + +Running +------- + +The shortest, simplest way of running the test suite is the following command +from the root directory of your checkout (after you have built Python):: + + ./python -m test + +You may need to change this command as follows throughout this section. +On :ref:`most ` Mac OS X systems, replace :file:`./python` +with :file:`./python.exe`. On Windows, use :file:`PCbuild\\python_d.exe` or +check the detailed :ref:`Windows instructions `. If using +Python 2.7, replace ``test`` with ``test.regrtest``. + +If you don't have easy access to a command line, you can run the test suite from +a Python or IDLE shell:: + + >>> from test import autotest + +This will run the majority of tests, but exclude a small portion of them; these +excluded tests use special kinds of resources: for example, accessing the +Internet, or trying to play a sound or to display a graphical interface on +your desktop. They are disabled by default so that running the test suite +is not too intrusive. To enable some of these additional tests (and for +other flags which can help debug various issues such as reference leaks), read +the help text:: + + ./python -m test -h + +If you want to run a single test, simply specify the test name as an argument. +You also probably want to enable verbose mode (using ``-v``), so that individual +failures are detailed:: + + ./python -m test -v test_abc + +If you have a multi-core or multi-CPU machine, you can enable parallel testing +using several Python processes so as to speed up things:: + + ./python -m test -j0 + +If you are running a version of Python prior to 3.3 you must specify the number +of processes to run simultaneously (e.g. ``-j2``). + +.. _strenuous_testing: + +Finally, if you want to run tests under a more strenuous set of settings, you +can run ``test`` as:: + + ./python -bb -E -Wd -m test -r -w -uall + +The various extra flags passed to Python cause it to be much stricter about +various things (the ``-Wd`` flag should be ``-W error`` at some point, but the +test suite has not reached a point where all warnings have been dealt with and +so we cannot guarantee that a bug-free Python will properly complete a test run +with ``-W error``). The ``-r`` flag to the test runner causes it to run tests in +a more random order which helps to check that the various tests do not interfere +with each other. The ``-w`` flag causes failing tests to be run again to see +if the failures are transient or consistent. +The ``-uall`` flag allows the use of all available +resources so as to not skip tests requiring, e.g., Internet access. + +To check for reference leaks (only needed if you modified C code), use the +``-R`` flag. For example, ``-R 3:2`` will first run the test 3 times to settle +down the reference count, and then run it 2 more times to verify if there are +any leaks. + +You can also execute the ``Tools/scripts/run_tests.py`` script as found in a +CPython checkout. The script tries to balance speed with thoroughness. But if +you want the most thorough tests you should use the strenuous approach shown +above. + + +Unexpected Skips +^^^^^^^^^^^^^^^^ + +Sometimes when running the test suite, you will see "unexpected skips" +reported. These represent cases where an entire test module has been +skipped, but the test suite normally expects the tests in that module to +be executed on that platform. + +Often, the cause is that an optional module hasn't been built due to missing +build dependencies. In these cases, the missing module reported when the test +is skipped should match one of the modules reported as failing to build when +:ref:`compiling`. + +In other cases, the skip message should provide enough detail to help figure +out and resolve the cause of the problem (for example, the default security +settings on some platforms will disallow some tests) + + +Writing +------- + +Writing tests for Python is much like writing tests for your own code. Tests +need to be thorough, fast, isolated, consistently repeatable, and as simple as +possible. We try to have tests both for normal behaviour and for error +conditions. Tests live in the ``Lib/test`` directory, where every file that +includes tests has a ``test_`` prefix. + +One difference with ordinary testing is that you are encouraged to rely on the +:py:mod:`test.support` module. It contains various helpers that are tailored to +Python's test suite and help smooth out common problems such as platform +differences, resource consumption and cleanup, or warnings management. +That module is not suitable for use outside of the standard library. + +When you are adding tests to an existing test file, it is also recommended +that you study the other tests in that file; it will teach you which precautions +you have to take to make your tests robust and portable. diff -r 85f290e474e2 build/_sources/setup.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/setup.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,367 @@ +=============== +Getting Started +=============== + +These instructions cover how to get a working copy of the source code and a +compiled version of the CPython interpreter (CPython is the version of Python +available from http://www.python.org/). It also gives an overview of the +directory structure of the CPython source code. + +OpenHatch also has a great `setup guide`_ for Python for people who are +completely new to contributing to open source. + +.. _setup guide: https://openhatch.org/wiki/Contributing_to_Python + + +.. _setup: + +Getting Set Up +============== + +Version Control Setup +--------------------- + +CPython is developed using `Mercurial `_. The Mercurial +command line program is named ``hg``; this is also used to refer to Mercurial +itself. Mercurial is easily available for common Unix systems by way of the +standard package manager; under Windows, you might want to use the +`TortoiseHg `_ graphical client. + + +.. _checkout: + +Getting the Source Code +----------------------- + +One should always work from a working copy of the CPython source code. +While it may +be tempting to work from the copy of Python you already have installed on your +machine, it is very likely that you will be working from out-of-date code as +the Python core developers are constantly updating and fixing things in their +:abbr:`VCS (version control system)`. It also means you will have better tool +support through the VCS as it will provide a diff tool, etc. + +To get a working copy of the :ref:`in-development ` branch of +CPython (core developers use a different URL as outlined in :ref:`coredev`), +run:: + + hg clone http://hg.python.org/cpython + +If you want a working copy of an already-released version of Python, +i.e., a version in :ref:`maintenance mode `, you can update your +working copy. For instance, to update your working copy to Python 3.3, do:: + + hg update 3.3 + +You will need to re-compile CPython when you do such an update. + +Do note that CPython will notice that it is being run from a working copy. +This means that if you edit CPython's source code in your working copy, +changes to Python code will be picked up by the interpreter for immediate +use and testing. (If you change C code, you will need to recompile the +affected files as described below.) + +Patches for the documentation can be made from the same repository; see +:ref:`documenting`. + +.. _compiling: + +Compiling (for debugging) +------------------------- + +CPython provides several compilation flags which help with debugging various +things. While all of the known flags can be found in the +``Misc/SpecialBuilds.txt`` +file, the most critical one is the ``Py_DEBUG`` flag which creates what is +known as a "pydebug" build. This flag turns on +various extra sanity checks which help catch common issues. The use of the flag +is so common that turning on the flag is a basic compile option. + +You should always +develop under a pydebug build of CPython (the only instance of when you +shouldn't is if you are taking performance measurements). Even when working +only on pure Python code the pydebug build provides several useful checks that +one should not skip. + + +Build dependencies +'''''''''''''''''' + +The core CPython interpreter only needs a C compiler to be built; if +you get compile errors with a C89 or C99-compliant compiler, please `open a +bug report `_. +However, some of the extension modules will need development headers +for additional libraries (such as the ``zlib`` library for compression). +Depending on what you intend to work on, you might need to install these +additional requirements so that the compiled interpreter supports the +desired features. + +For UNIX based systems, we try to use system libraries whenever available. +This means optional components will only build if the relevant system headers +are available. The best way to obtain the appropriate headers will vary by +distribution, but the appropriate commands for some popular distributions +are below. + +Fedora, Red Hat Enterprise Linux and other ``yum`` based systems:: + + $ sudo yum install yum-utils + $ sudo yum-builddep python3 + +Debian, Ubuntu and other ``apt`` based systems:: + + $ sudo apt-get build-dep python3 + +For Mac OS X systems, it is generally easiest to use the C compiler and other +development utilities provided by Apple's Xcode Developer Tools. There are +specific versions supported by Apple for each major release of OS X. For +current releases, Xcode is available as a no-cost download from Apple's App +Store. Xcode versions for older releases are available through +`the Apple Developer web site `_. +Note that while the Xcode IDE application itself is not needed to build Python, +the development components packaged inside it may be. You should also install +the Xcode Command Line Tools component to ensure build tools and system header +files are installed in their conventional locations (``/usr/bin`` and +``/usr/include``). How the command line tools are installed varies by OS X +and Xcode release. In earlier releases, there may be a separate installer +download. For OS X 10.7 and 10.8, there is an option in the Xcode app +Preferences menu. For OS X 10.9 (Mavericks), run the following:: + + $ xcode-select --install + +Also note that OS X does not include several libraries used by the Python +standard library, including ``libzma``, so expect to see some extension module +build failures unless you install local copies of them. + +There will sometimes be optional modules added for a new release which +won't yet be identified in the OS level build dependencies. In those cases, +just ask for assistance on the core-mentorship list. If working on bug +fixes for Python 2.7, use ``python`` in place of ``python3`` in the above +commands. + +Explaining how to build optional dependencies on a UNIX based system without +root access is beyond the scope of this guide. + +.. _clang: http://clang.llvm.org/ + +.. note:: While you need a C compiler to build CPython, you don't need any + knowledge of the C language to contribute! Vast areas of CPython are + written completely in Python: as of this writing, CPython contains slightly + more Python code than C. + + +.. _unix-compiling: + +UNIX +'''' + +The basic steps for building Python for development is to configure it and +then compile it. + +Configuration is typically:: + + ./configure --with-pydebug + +More flags are available to ``configure``, but this is the minimum you should +do to get a pydebug build of CPython. + +Once ``configure`` is done, you can then compile CPython with:: + + make -s -j2 + +This will build CPython with only warnings and errors being printed to +stderr and utilize up to 2 CPU cores. If you are using a multi-core machine +with more than 2 cores (or a single-core machine), you can adjust the number +passed into the ``-j`` flag to match the number of cores you have. + +Do take note of what modules were **not** built as stated at the end of your +build. More than likely you are missing a dependency for the module(s) that +were not built, and so you can install the dependencies and re-run both +``configure`` and ``make`` (if available for your OS). +Otherwise the build failed and thus should be fixed (at least with a bug being +filed on the `issue tracker`_). + +.. _mac-python.exe: + +Once CPython is done building you will then have a working build +that can be run in-place; ``./python`` on most machines (and what is used in +all examples), ``./python.exe`` wherever a case-insensitive filesystem is used +(e.g. on OS X by default), in order to avoid conflicts with the ``Python`` +directory. There is normally no need to install your built copy +of Python! The interpreter will realize where it is being run from +and thus use the files found in the working copy. If you are worried +you might accidentally install your working copy build, you can add +``--prefix=/tmp/python`` to the configuration step. When running from your +working directory, it is best to avoid using the ``--enable-shared`` flag +to ``configure``; unless you are very careful, you may accidentally run +with code from an older, installed shared Python library rather than from +the interpreter you just built. + +.. _issue tracker: http://bugs.python.org + + +Clang +""""" + +If you are using clang_ to build CPython, some flags you might want to set to +quiet some standard warnings which are specifically superfluous to CPython are +``-Wno-unused-value -Wno-empty-body -Qunused-arguments``. You can set your +``CFLAGS`` environment variable to these flags when running ``configure``. + +If you are using LLVM 2.8, also use the ``-no-integrated-as`` flag in order to +build the :py:mod:`ctypes` module (without the flag the rest of CPython will +still build properly). + + +.. _windows-compiling: + +Windows +''''''' +The readme included in the solution has more details, especially on the +software needed to resolve the below mentioned build errors. + +**Python 3.3** and later use Microsoft Visual Studio 2010. You can +download Microsoft Visual C++ 2010 Express `from Microsoft's site +`_. +To use it for more than 28 days, one must register through a +Windows Live account. + +Most Python versions prior to 3.3 use Microsoft Visual Studio 2008. You can +download Microsoft Visual C++ 2008 Express Edition with SP1 +from a new location yet to be determined. + +Regardless of Visual Studio version, the ``PCbuild`` directory of a source +checkout contains the build files for the Python version you are building. +The full version of Visual Studio is not necessary for common tasks with +32-bit builds; the gratis C++ Express versions linked above are sufficient. +Their limitations are given `here (2008) +`_ +and `here (2010) +`_. + +To build from the Visual Studio GUI, open the ``pcbuild.sln`` solution file +with Visual Studio. If you are using C++ Express, you may get an error message +indicating solution files are not supported, you can ignore it. Choose the +:menuselection:`Build Solution` option under the :menuselection:`Build` or +:menuselection:`Debug` menu (depending on your version of Visual Studio). +Be sure that "Debug" was chosen as the active solution configuration +(e.g. under :menuselection:`Build --> Configuration Manager...`) + +When building you may see a number of build errors related to missing +files or directories. These do not necessarily mean that Python failed +to build. If you prefer, you can exclude the offending projects from +the build process by unchecking them inside the +:menuselection:`Build --> Configuration Manager...` settings. You can +also use the script :file:`Tools\\buildbot\\external.bat` or +:file:`Tools\\buildbot\\external-amd64.bat` (as applicable) to download and +compile missing dependencies. + +Once built you might want to set Python as a startup project. Pressing F5 in +Visual Studio, or choosing Start Debugging from the Debug menu, will launch +the interpreter. + +.. _win-python.exe: + +If you want to launch the compiled interpreter from the command-line, the +path varies according to the build. For a 32-bit build in debug mode, you +have to invoke ``PCBuild\python_d.exe``, for a 64-bit build in debug mode, +``PCBuild\amd64\python_d.exe``. If you are compiling in release mode (which +you shouldn't, in general), replace ``python_d.exe`` with ``python.exe``. + +For additional help for Windows see :ref:`windows-advanced` + +.. _build_troubleshooting: + +Troubleshooting the build +------------------------- + +This section lists some of the common problems that may arise during the +compilation of Python, with proposed solutions. + +Avoiding re-creating auto-generated files +''''''''''''''''''''''''''''''''''''''''' + +Under some circumstances you may encounter Python errors in scripts like +``Parser/asdl_c.py`` or ``Python/makeopcodetargets.py`` while running ``make``. +Python auto-generates some of its own code, and a full build from scratch needs +to run the auto-generation scripts. However, this makes the Python build require +an already installed Python interpreter; this can also cause version mismatches +when trying to build an old (2.x) Python with a new (3.x) Python installed, or +vice versa. + +To overcome this problem, auto-generated files are also checked into the +Mercurial repository. So if you don't touch the auto-generation scripts, there's +no real need to auto-generate anything. However, as Mercurial doesn't preserve +timestamps well, a special build target ``touch`` was added. Run:: + + make touch + +Before running the compilation ``make``. This will tweak the timestamps of the +auto-generated files in a way that makes it unnecessary to create them anew and +henceforth the compilation should not require an installed Python interpreter. + +Editors and Tools +================= + +Python is used widely enough that practically all code editors have some form +of support for writing Python code. Various coding tools also include Python +support. + +For editors and tools which the core developers have felt some special comment +is needed for coding *in* Python, see :ref:`resources`. + + +Directory Structure +=================== + +There are several top-level directories in the CPython source tree. Knowing what +each one is meant to hold will help you find where a certain piece of +functionality is implemented. Do realize, though, there are always exceptions to +every rule. + +``Doc`` + The official documentation. This is what http://docs.python.org/ uses. + See also :ref:`building-doc`. + +``Grammar`` + Contains the :abbr:`EBNF (Extended Backus-Naur Form)` grammar file for + Python. + +``Include`` + Contains all interpreter-wide header files. + +``Lib`` + The part of the standard library implemented in pure Python. + +``Mac`` + Mac-specific code (e.g., using IDLE as an OS X application). + +``Misc`` + Things that do not belong elsewhere. Typically this is varying kinds of + developer-specific documentation. + +``Modules`` + The part of the standard library (plus some other code) that is implemented + in C. + +``Objects`` + Code for all built-in types. + +``PC`` + Windows-specific code along with legacy build files for previously used + versions of MSVC. + +``PCbuild`` + Build files for the version of MSVC currently used for the Windows + installers provided on python.org. + +``Parser`` + Code related to the parser. The definition of the AST nodes is also kept + here. + +``Python`` + The code that makes up the CPython interpreter. This includes the compiler, + eval loop and various built-in modules. + +``Tools`` + Various tools that are (or have been) used to maintain Python. + diff -r 85f290e474e2 build/_sources/setupWindows.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/setupWindows.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,126 @@ +.. _windows-advanced: + +============================= +Setting Up Windows - Advanced +============================= + +The online directions for downloading the development version source are fine +and can be found at :ref:`Windows `. There is also +information in the readme file found in the source directory that is helpful. + +Mercurial must be installed on your machine. +Stable released version source is available on the download page. + +Subversion is necessary because some of the third party components for the +windows built are still in a subversion repository. + +Python building/rebuilding assumes the existence of subversion, perl, and a +version of Visual Studio on your system. If you have all three, skip to step +three. Otherwise download and install any of those that are missing. + +If it is necessary to have on hand multiple versions of python built from scratch, you +should isolate them from each other by putting them in a container directory +perhaps of the same name:: + + python331/python331, python32/python32 + +where the subdirectory is the source root directory. Use the upper directory +to isolate the external subprojects created by the buildbots described later. +The buildbots of one version can wipe out required subprojects of another +version of python which can cause confusion. + +------ +Step 0 +------ + +Download and install a subversion client and add the executable to your path. + +------ +Step 1 +------ + +Download and install perl and add the executable to your path. + +------ +Step 2 +------ + +Download and install Visual Studio 2010. Either Express C++ will work or +Visual Studio Professional. Express is free, however, when the solution file +is loaded, an error message is displayed. + +Visual Studio should be in your path. + +------ +Step 3 +------ + +Download and install `NASM `_ + +------ +Step 4 +------ + +Download and build the external subprojects with the buildbots using either:: + + Tools\buildbot\external.bat # for 32 bit processors + Tools\buildbot\external-amd64.bat # for 64 bit processors + +from the root directory or your python distribution. +This step will download the correct versions of the external projects for +this version of python. There are several projects + +------ +Step 5 +------ + + +openssl is used for python on windows +ssl rarely succeeds if you proceed to build using pcbuild.sln: + +The following steps will resolve many problems if you executing them +before building with the .sln file:: + + cd into the openssl directory created by the buildbots + perl util\mkdef.pl crypto ssl update + perl Configure VC-WIN32 --prefix=C:\opt\openssl-1.0.1d + ms\do_nasm + +Compilation errors may occur when you attempt to build the .sln file with +Visual Studio. The errors are typically a forced error contained within a +block of conditional code. Good results have been found by commenting out +the forced error. Most recently commenting out code blocks in +mdc2.h and idea.h produced good results. + +Historically, the openssl build has not had a "clean" function. Cleaning the +project by deleting and letting the buildbot download again gave good results. + + +------ +Step 6 +------ + +Finally Build python and its internal subprojects + + Open the solution "pcbuild.sln" in Visual Studio + If you have an express version, then ignore the warning + Select the configuration (Release or Debug) :: + + "Release" builds python.exe + "Debug" builds python_d.exe + Select the platform Win32 or x64 + Build the solution. + Right click "Solution 'pccuild'" and select + build - for fresh build + clean - to delete all files created for build , i.e. objects, + libraries, executable, etc. + rebuild - clean and build everything + +Note that you can clean and build individual subprojects by right clicking +on the subproject and selecting build, clean, or rebuild for that project + +Using Visual Studio +=================== + +There is `Python Tools for Visual Studio `_ an addon published +by Microsoft for many versions of Visual Studio except the Express editions. \ No newline at end of file diff -r 85f290e474e2 build/_sources/silencewarnings.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/silencewarnings.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,18 @@ +.. _silencewarnings: + +Silence Warnings From the Test Suite +==================================== + +When running Python's test suite, no warnings should result when you run it +under :ref:`strenuous testing conditions ` (you can ignore +the extra flags passed to ``test`` that cause randomness and parallel execution +if you want). Unfortunately new warnings are added to Python on occasion which +take some time to eliminate (e.g., ``ResourceWarning``). Typically the easy +warnings are dealt with quickly, but the more difficult ones that require some +thought and work do not get fixed immediately. + +If you decide to tackle a warning you have found, open an issue on the `issue +tracker`_ (if one has not already been opened) and say you are going to try and +tackle the issue, and then proceed to fix the issue. + +.. _issue tracker: http://bugs.python.org diff -r 85f290e474e2 build/_sources/stdlibchanges.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/stdlibchanges.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,151 @@ +.. _stdlibchanges: + +Adding to the Stdlib +==================== + +While the stdlib contains a great amount of useful code, sometimes you want +more than is provided. This document is meant to explain how you can get either +a new addition to a pre-existing module in the stdlib or add an entirely new +module. + +Changes to pre-existing code is not covered as that is considered a bugfix and +thus is treated as a bug that should be filed on the `issue tracker`_. + +.. _issue tracker: http://bugs.python.org/ + + +Adding to a pre-existing module +------------------------------- + +If you have found that a function, method, or class is useful and you believe +it would be useful to the general Python community, there are some steps to go +through in order to see it added to the stdlib. + +First is you should gauge the usefulness of the code. Typically this is done +by sharing the code publicly. You have a couple of options for this. One is to +post it online at the `Python Cookbook`_. Based on feedback or reviews of the +recipe you can see if others find the functionality as useful as you do. +A search of the issue tracker for previous suggestions related to the proposed +addition may turn up a rejected issue that explains why the suggestion will not +be accepted. +Another is to do a blog post about the code and see what kind of responses you +receive. Posting to python-list (see :ref:`communication` for where to find the +list and other mailing lists) to discuss your code also works. Finally, asking +on a specific :abbr:`SIG (special interest group)` from mail.python.org or +python-ideas is also acceptable. This is not a required step but it is +suggested. + +If you have found general acceptance and usefulness for your code from people, +you can open an issue on the `issue tracker`_ with the code attached as a +:ref:`patch `. If possible, also submit a +:ref:`contributor agreement `. + +If a core developer decides that your code would be useful to the general +Python community, they will then commit your code. If your code is not picked +up by a core developer and committed then please do not take this personally. +Through your public sharing of your code in order to gauge community support +for it you at least can know that others will come across it who may find it +useful. + +.. _Python Cookbook: http://code.activestate.com/recipes/langs/python/ + + +Adding a new module +------------------- +It must be stated upfront that getting a new module into the stdlib is very +difficult. Adding any significant amount of code to the stdlib increases the +burden placed upon core developers. It also means that the module somewhat +becomes "sanctioned" by the core developers as a good way to do something, +typically leading to the rest of the Python community to using the new module +over other available solutions. All of this means that additions to the stdlib +are not taken lightly. + + +Acceptable Types of Modules +''''''''''''''''''''''''''' +Typically two types of modules get added to the stdlib. One type is a module +which implements something that is difficult to get right. A good example of +this is the :py:mod:`multiprocessing` package. Working out the various OS +issues, working through concurrency issues, etc. are all very difficult to get +right. + +The second type of module is one that implements something that people +re-implement constantly. The :py:mod:`itertools` module is a good example of +this type as its constituent parts are not necessarily complex, but are used +regularly in a wide range of programs and can be a little tricky to get right. +Modules that parse widely used data formats also fall under this type of module +that the stdlib consists of. + +While a new stdlib module does not need to appeal to all users of Python, it +should be something that a large portion of the community will find useful. +This makes sure that the developer burden placed upon core developers is worth +it. + + +Requirements +'''''''''''''' +In order for a module to even be considered for inclusion into the stdlib, a +couple of requirements must be met. + +The most basic is that the code must meet +:ref:`standard patch requirements `. For code that has +been developed outside the stdlib typically this means making sure the coding +style guides are followed and that the proper tests have been written. + +The module needs to have been out in the community for at least a year. Because +of Python's conservative nature when it comes to backwards-compatibility, when +a module is added to the stdlib its API becomes frozen. This means that a module +should only enter the stdlib when it is mature and gone through its +"growing pains". + +The module needs to be considered best-of-breed. When something is included in +the stdlib it tends to be chosen first for products over other third-party +solutions. By virtue of having been available to the public for at least a +year, a module needs to have established itself as (one of) the top choices by +the community for solving the problem the module is intended for. + +The development of the module must move into Python's +infrastructure (i.e., the module is no longer directly maintained outside of +Python). This prevents a divergence between the code that is included in the +stdlib and that which is released outside the stdlib (typically done to provide +the module to older versions of Python). It also removes the burden of forcing +core developers to have to redirect bug reports or patches to an external issue +tracker and :abbr:`VCS (version control system)`. + +Someone involved with the development of the +module must promise to help maintain the module in the stdlib for two years. +This not only helps out other core developers by alleviating workload from bug +reports that arrive from the first Python release containing the module, but +also helps to make sure that the overall design of the module continues to be +uniform. + + +Proposal Process +'''''''''''''''' +If the module you want to propose adding to the stdlib meets the proper +requirements, you may propose its inclusion. To start, you should email +python-list or python-ideas to make sure the community in general would support +the inclusion of the module (see :ref:`communication`). + +If the feedback from the community is positive overall, you will need to write +a :abbr:`PEP (Python enhancement proposal)` for the module's inclusion. It +should outline what the module's overall goal is, why it should be included in +the stdlib, and specify the API of the module. See the `PEP index`_ for PEPs +that have been accepted before that proposed a module for inclusion. + +Once your PEP is written, send it to python-ideas for basic vetting. Be +prepared for extensive feedback and lots of discussion (not all of it +positive). This will help make the PEP be of good quality and properly +formatted. + +When you have listened to, responded, and integrated as appropriate the +feedback from python-ideas into your PEP, you may send it to python-dev. You +will once again receive a large amount of feedback and discussion. A PEP +dictator will be assigned who makes the final call on whether the PEP will be +accepted or not. If the PEP dictator agrees to accept your PEP (which typically +means that the core developers end up agreeing in general to accepting +your PEP) then the module +will be added to the stdlib once the creators of the module sign +:ref:`contributor agreements `. + +.. _PEP index: http://www.python.org/dev/peps/ diff -r 85f290e474e2 build/_sources/tracker.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/tracker.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,201 @@ +============== +Issue Tracking +============== + +.. _tracker: + +Using the Issue Tracker +======================= + +If you think you found a bug in Python, you can report it to the +`issue tracker`_. Documentation bugs can also be reported there. +Issues about the tracker should be reported to the `meta tracker`_. + + +Checking if a bug already exists +-------------------------------- + +The first step in filing a report is to determine whether the problem has +already been reported. The advantage in doing so, aside from saving the +developers time, is that you learn what has been done to fix it; it may be that +the problem has already been fixed for the next release, or additional +information is needed (in which case you are welcome to provide it if you can!). + +To do this, search the bug database using the search box on the top of the page. +An `advanced search`_ is also available by clicking on "Search" in +the sidebar. + + +Reporting an issue +------------------ + +If the problem you're reporting is not already in the `issue tracker`_, you +need to log in by entering your user and password in the form on the left. +If you don't already have a tracker account, select the "Register" link or, +if you use OpenID, one of the OpenID provider logos in the sidebar. + +It is not possible to submit a bug report anonymously. + +Being now logged in, you can submit a bug by clicking on the "Create New" link +in the sidebar. + +The submission form has a number of fields, and they are described in detail +in the :ref:`triaging` page. This is a short summary: + +* in the **Title** field, enter a *very* short description of the problem; + less than ten words is good; +* in the **Type** field, select the type of your problem (usually behavior); +* if you know which **Components** and **Versions** are affected by the issue, + you can select these too; +* if you have JavaScript enabled, you can use the **Nosy List** field to search + developers that can help with the issue by entering the name of the affected + module, operating system, or interest area. +* last but not least, you have to describe the problem in detail, including + what you expected to happen and what did happen, in the **Comment** field. + Be sure to include whether any extension modules were involved, and what + hardware and software platform you were using (including version information + as appropriate). + +The triaging team will take care of setting other fields, and possibly assign +the issue to a specific developer. You will automatically receive an update +each time an action is taken on the bug. + + +.. _helptriage: + +Helping Triage Issues +===================== + +Once you know your way around how Python's source files are +structured and you are comfortable working with patches, a great way to +participate is to help triage issues. Do realize, though, that experience +working on Python is needed in order to effectively help triage. + +Around the clock, new issues are being opened on the `issue tracker`_ and +existing issues are being updated. Every +issue needs to be triaged to make sure various things are in proper order. Even +without special privileges you can help with this process. + + +Classifying Reports +------------------- + +For bugs, an issue needs to: + +* clearly explain the bug so it can be reproduced +* include all relevant platform details +* state what version(s) of Python are affected by the bug. + +These are things you can help with once you have experience developing for +Python. For instance, if a bug is not clearly explained enough for you to +reproduce it then there is a good chance a core developer won't be able to +either. And it is always helpful to know if a bug not only affects the +in-development version of Python, but whether it also affects other versions in +maintenance mode. And if the bug lacks a unit test that should end up in +Python's test suite, having that written can be very helpful. + +This is all helpful as it allows triagers (i.e., +:ref:`people with the Developer role on the issue tracker `) to +properly classify an issue so it can be handled by the right core developers in +a timely fashion. + + +Reviewing Patches +----------------- + +If an issue has a patch attached that has not been reviewed, you can help by +making sure the patch: + +* follows the style guides +* applies cleanly to an up-to-date clone +* is a good solution to the problem it is trying to solve +* includes proper tests +* includes proper documentation changes +* submitter is listed in ``Misc/ACKS``, either already or the patch adds them + +Doing all of this allows core developers and :ref:`triagers ` to more +quickly look for subtle issues that only people with extensive experience +working on Python's code base will notice. + + +Finding an Issue You Can Help With +---------------------------------- + +If you want to help triaging issues, you might also want to search for issues +that you are knowledgeable about. An easy way to do it, is to search for +the name of a module you are familiar with. You can also use the +`advanced search`_ and search for specific components (e.g. "Windows" if you +are a Windows developer, "Extension Modules" if you are familiar with C, etc.). +Finally you can use the "Random issue" link in the sidebar to pick random +issues until you find an issue that you like. Is not so uncommon to find old +issues that can be closed, either because they are no longer valid, or +because they have a patch that is ready to be committed, but no one had +time to do it yet. + +In the sidebar you can also find links to summaries for easy issues and +issues with a patch. + + +.. _devrole: + +Gaining the "Developer" Role on the Issue Tracker +================================================= + +When you have consistently shown the ability to properly +help triage issues without guidance, you may request that you +be given the "Developer" role on the `issue tracker`_. You can make the request +of any person who already has the Developer role. If they decide you are ready +to gain the extra privileges on the tracker they will then act as a mentor to +you until you are ready to do things entirely on your own. There is no set rule +as to how many issues you need to have helped with before or how long you have +been participating. The key requirements are that you show the desire to +help, you are able to work well with others (especially those already with the +Developer role), and that have a firm grasp of how to do things on the issue +tracker properly on your own. + +Gaining the Developer role will allow you to set any value on any issue in the +tracker, releasing you from the burden of having to ask others to set values on +an issue for you in order to properly triage something. This will not only help +speed up and simplify your work in helping out, but also help lessen the +workload for everyone by gaining your help. + + +The Meta Tracker +================ + +If you find an issue with the `issue tracker`_, you can report it to the +`meta tracker`_. The meta tracker is where you file issues against anything +you come across when working with the issue tracker itself (e.g you can't +attach a file, the layout is broken on your browser, Rietveld gave you an +error, etc.). + +If you want to contribute to the tracker you can get a checkout of the source +and install a local instance where to experiment. You can find detailed +instructions on the `Tracker Development`_ page. + + +.. seealso:: + + `The Python issue tracker `_ + Where to report issues about Python. + + `The New-bugs-announce mailing list `_ + Where all the new issues created on the tracker are reported. + + `The Python-bugs-list mailing list `_ + Where all the changes to issues are reported. + + `The meta tracker `_ + Where to report issues about the tracker itself. + + `The Tracker development wiki page `_ + Instructions about setting up a local instance of the bug tracker. + + `The Tracker-discuss mailing list `_ + Discussions about the bug tracker. + + +.. _issue tracker: http://bugs.python.org/ +.. _meta tracker: http://psf.upfronthosting.co.za/roundup/meta/ +.. _advanced search: http://bugs.python.org/issue?@template=search +.. _Tracker Development: http://wiki.python.org/moin/TrackerDevelopment diff -r 85f290e474e2 build/_sources/triaging.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_sources/triaging.txt Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,326 @@ +.. _triaging: + +Triaging an Issue +================= + +When you have the Developer role on the `issue tracker`_ you are able to triage +issues directly without any assistance. + +Fields +------ + +Title +''''' +Should be properly descriptive of what the issue is about. Occasionally +people file an issue that either has too generic of a title or end up thinking +they filed about X but in fact it turns out to be about Y and thus the +title is now wrong. + +Type +'''' +Describes the type of issue. If something does not fit within any +specific type then simply do not set it. + +behavior + Wrong or unexpected behavior, result, or exception. This includes most of + the bugs. +crash + Hard crashes of the Python interpreter -- possibly with a core + dump or a Windows error box. +compile error + Errors reported by the compiler while compiling Python. +resource usage + Situations where too many resources (e.g. memory) are used. +security + Issues that might have security implications. If you think the issue + should not be made public, please report it to security@python.org instead. +performance + Situations where too much time is necessary to complete the task. +enhancement + Issues that propose the addition of new functionality, such as new + functions, classes, modules, or even new arguments for existing functions. + Also used for improvements in the documentation and test suite and for + other refactorings. + +Stage +''''' +What is needed next to advance the issue. The *stage* needn't be set until +it is clear that the issue warrants fixing. + +test needed + The bug reporter should post a script or instructions to let a triager or + developer reproduce the issue. +needs patch + The issue lacks a patch to solve the problem (i.e. fixing the bug, or + adding the requested improvement). +patch review + There is a patch, but it needs reviewing or is in the process of being + reviewed. This can be done by any triager as well as a core developer. +commit review + A triager performed a patch review and it looks good to them, but a core + developer needs to commit the patch (and do a quick once-over to make sure + nothing was overlooked). +committed/rejected + The issue is considered closed and dealt with. + +Components +'''''''''' +What part of Python is affected by the issue. This is a multi-select field. +Be aware that what component is chosen may cause the issue to be auto-assigned, +i.e. the issue tracker may automatically fill in the `Assigned To`_ field +after you press ``Submit changes``. + +The following component(s) should be selected if the issue applies to: + +2to3 (2.x to 3.0 conversion tool) + The 2to3 conversion tool in `Lib/lib2to3`_. +Benchmarks + The benchmarks in the benchmarks_ repo. +Build + The build process. +ctypes + The ctypes package in `Lib/ctypes`_. +Demos and Tools + The files in Tools_ and `Tools/demo`_. +Devguide + The `Developer's guide`_. +Distutils + The distutils package in `Lib/distutils`_. +Distutils2 + The packaging module in `Lib/packaging`_. +Documentation + The documentation in Doc_ (used to build the HTML doc at http://docs.python.org/). +email + The email package and related modules. +Extension Modules + C modules in Modules_. +IDLE + The `Lib/idlelib`_ package. +Installation + The installation process. +Interpreter Core + The interpreter core, the built-in objects in `Objects`_, the `Python`_, + `Grammar`_ and `Parser`_ dirs. +IO + The I/O system, `Lib/io.py`_ and `Modules/_io`_. +Library (Lib) + Python modules in Lib_. +Macintosh + The Mac OS X operating system. +Regular Expressions + The `Lib/re.py`_ and `Modules/_sre.c`_ modules. +Tests + The unittest and doctest frameworks in `Lib/unittest`_ and + `Lib/doctest.py`_. + + The CPython tests in `Lib/test`_, the test runner in `Lib/test/regrtest.py`_ + and the `Lib/test/support.py`_ module. +Tkinter + The `Lib/tkinter`_ package. +Unicode + Unicode, codecs, str vs bytes, `Objects/unicodeobject.c`_. +Windows + The Windows operating system. +XML + The `Lib/xml`_ package. + +Versions +'''''''' +The known versions of Python that the issue affects and should be fixed for. +Thus if an issue for a new feature is assigned for e.g., Python 3.3 but is not +applied before Python 3.3.0 is released, this field should be updated to say +Python 3.4 as the version and drop Python 3.3. + +Priority +'''''''' +How important is this issue? + +low + This is for low-impact bugs, or feature requests of little utility. +normal + The default value for most issues, which deserve fixing but without + any urgency to do so. +high + Make some effort to fix the issue before the next final release. +critical + This issue should definitely be fixed before the next final release. +deferred blocker + The issue will not hold up the next release, but will be promoted to a + release blocker for the following release, e.g., won't block the next + release of a1 but will block a2. +release blocker + The issue must be fixed before *any* release is made, e.g., will block the + next release even if it is an alpha release. + +As a guideline, *critical* and above are usually reserved for crashes, +serious regressions or breakage of very important APIs. Whether a bug +is a *release blocker* is a decision better left to the release manager so, +in any doubt, add him or her to the *nosy list*. + +Keywords +'''''''' +Various flags about the issue. Multiple values are possible. + +buildbot + A buildbot triggered the issue being reported. +easy + Fixing the issue should not take longer than a day for someone new to + contributing to Python to solve. +gsoc + The issue would fit as, or is related to, a GSoC_ project. +needs review + The patch attached to the issue is in need of a review. +patch + There is a patch attached to the issue. +3.3regression + The issue is a regression in 3.3. + +Nosy List +''''''''' +A list of people who may be interested in an issue. It is acceptable to add +someone to the nosy list if you think the issue should be brought to their +attention. Use the :ref:`experts` to know who wants to be added to the nosy +list for issues targeting specific areas. + + +If you are logged in and have JavaScript enabled, you can use the ``[+]`` +button to add yourself to the nosy list (remember to click on +"Submit Changes" afterwards). Note that you are added to the nosy +automatically when you submit a message. +The nosy list also has an autocomplete that lets you search from the lists of +developers and :ref:`experts`. The search is case-insensitive and +works for real names, modules, interest areas, etc., and only adds the +username(s) to the nosy once an entry is selected. + +Assigned To +''''''''''' +Who is expected to take the next step in resolving the issue. It is acceptable +to assign an issue to someone if the issue cannot move forward without their +help, e.g., they need to make a technical decision to allow the issue to move +forward. Also consult the :ref:`experts` as certain stdlib modules should +always be assigned to a specific person. + +Dependencies +'''''''''''' +The issue requires the listed issue(s) to be resolved first before it can move +forward. + +Superseder +'''''''''' +The issue is a duplicate of the listed issue(s). + +Status +'''''' +open + Issue is not resolved. +languishing + The issue has no clear solution , e.g., no agreement on a technical + solution or if it is even a problem worth fixing. +pending + The issue is blocked until someone (often the + :abbr:`OP (original poster)`) provides some critical information; + the issue will be closed after a set amount of time if no reply comes in. + Useful when someone opens an issue that lacks enough information to + reproduce the bug reported. Requesting additional information and setting + status to *pending* indicates that the issue should be closed if the + necessary information is never provided. +closed + The issue has been resolved (somehow). + +Resolution +'''''''''' +Why the issue is in its current state (not usually used for "open"). + +duplicate + Duplicate of another issue; should have the Superseder field filled out. +fixed + A fix for the issue was committed. +invalid + For some reason the issue is invalid (e.g. the perceived problem is not + a bug in Python). +later + Issue is to be worked on at a later date. +out of date + The issue has already been fixed, or the problem doesn't exist anymore + for other reasons. +postponed + Issue will not be worked on at the moment. +rejected + Issue was rejected (especially for feature requests). +remind + The issue is acting as a reminder for someone. +wont fix + Issue will not be fixed, typically because it would cause a + backwards-compatibility problem. +works for me + Bug cannot be reproduced. + +Mercurial Repository +'''''''''''''''''''' +HTTP link to a Mercurial repository that contains a patch for the issue. +A :guilabel:`Create Patch` button will appear that computes a diff for the +head revision of the remote branch and attaches it to the issue. The button +supports only CPython_ patches. + +If you don't indicate a remote branch, ``default`` is used. You can +indicate a remote branch by adding ``#BRANCH`` to the end of the URL. + +Generating Special Links in a Comment +------------------------------------- +Comments can automatically generate a link to various web pages if formatted +properly. + +* ``#``, ``issue``, or ``issue `` links to the + tracker issue ````. +* ``msg`` links to the tracker message ````. +* a 12-digit or 40-digit hex ```` is assumed to be a Mercurial + changeset identifier and generates a link to changeset ```` + in the official Python source code repositories. +* ``r``, ``rev``, or ``revision `` is assumed to be + a legacy Subversion revision number, a reference to a changeset that was + checked in prior to 2011-03-05 when the official Python source code + repositories were migrated from the :abbr:`svn (Subversion)` + :abbr:`VCS (version control system)` to Mercurial. + The issue tracker automatically translates the legacy svn revision + ```` to its corresponding Mercurial changeset identifier. +* ``Dir/file.ext`` and ``Dir/file.ext:NNN`` generate links to files in the + `Python source code repositories `_, + possibly linking to the line number specified after the ``:``. +* ``PEP `` and ``PEP`` link to the + :abbr:`PEP (Python Enhancement Proposal)` ````. +* ``devguide`` (lowercase), ``devguide/triaging``, and + ``devguide/triaging#generating-special-links-in-a-comment`` generate links to + the Devguide, this page, and this section respectively. + + +.. _CPython: http://hg.python.org/cpython/file/default/ +.. _Doc: http://hg.python.org/cpython/file/default/Doc/ +.. _Grammar: http://hg.python.org/cpython/file/default/Grammar/ +.. _Lib: http://hg.python.org/cpython/file/default/Lib/ +.. _Lib/lib2to3: http://hg.python.org/cpython/file/default/Lib/lib2to3/ +.. _Lib/ctypes: http://hg.python.org/cpython/file/default/Lib/ctypes/ +.. _Lib/distutils: http://hg.python.org/cpython/file/default/Lib/distutils/ +.. _Lib/doctest.py: http://hg.python.org/cpython/file/default/Lib/doctest.py +.. _Lib/idlelib: http://hg.python.org/cpython/file/default/Lib/idlelib/ +.. _Lib/io.py: http://hg.python.org/cpython/file/default/Lib/io.py +.. _Lib/packaging: http://hg.python.org/cpython/file/default/Lib/packaging/ +.. _Lib/re.py: http://hg.python.org/cpython/file/default/Lib/re.py +.. _Lib/test: http://hg.python.org/cpython/file/default/Lib/test/ +.. _Lib/test/regrtest.py: http://hg.python.org/cpython/file/default/Lib/test/regrtest.py +.. _Lib/test/support.py: http://hg.python.org/cpython/file/default/Lib/test/support.py +.. _Lib/tkinter: http://hg.python.org/cpython/file/default/Lib/tkinter/ +.. _Lib/unittest: http://hg.python.org/cpython/file/default/Lib/unittest/ +.. _Lib/xml: http://hg.python.org/cpython/file/default/Lib/xml/ +.. _Modules: http://hg.python.org/cpython/file/default/Modules/ +.. _Modules/_io: http://hg.python.org/cpython/file/default/Modules/_io/ +.. _Modules/_sre.c: http://hg.python.org/cpython/file/default/Modules/_sre.c +.. _Objects: http://hg.python.org/cpython/file/default/Objects/ +.. _Objects/unicodeobject.c: http://hg.python.org/cpython/file/default/Objects/unicodeobject.c +.. _Parser: http://hg.python.org/cpython/file/default/Parser/ +.. _Python: http://hg.python.org/cpython/file/default/Python/ +.. _Tools: http://hg.python.org/cpython/file/default/Tools/ +.. _Tools/demo: http://hg.python.org/cpython/file/default/Tools/demo/ +.. _benchmarks: http://hg.python.org/benchmarks/ +.. _Developer's guide: http://hg.python.org/devguide/ +.. _GSoC: http://code.google.com/soc/ +.. _issue tracker: http://bugs.python.org diff -r 85f290e474e2 build/_static/ajax-loader.gif Binary file build/_static/ajax-loader.gif has changed diff -r 85f290e474e2 build/_static/basic.css --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_static/basic.css Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,537 @@ +/* + * basic.css + * ~~~~~~~~~ + * + * Sphinx stylesheet -- basic theme. + * + * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.clearer { + clear: both; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar #searchbox input[type="text"] { + width: 170px; +} + +div.sphinxsidebar #searchbox input[type="submit"] { + width: 30px; +} + +img { + border: 0; + max-width: 100%; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable { + width: 100%; +} + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +div.modindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +div.genindex-jumpbox { + border-top: 1px solid #ddd; + border-bottom: 1px solid #ddd; + margin: 1em 0 1em 0; + padding: 0.4em; +} + +/* -- general body styles --------------------------------------------------- */ + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +img.align-left, .figure.align-left, object.align-left { + clear: left; + float: left; + margin-right: 1em; +} + +img.align-right, .figure.align-right, object.align-right { + clear: right; + float: right; + margin-left: 1em; +} + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left; +} + +.align-center { + text-align: center; +} + +.align-right { + text-align: right; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + border: 0; + border-collapse: collapse; +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 5px; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +table.citation { + border-left: solid 1px gray; + margin-left: 1px; +} + +table.citation td { + border-bottom: none; +} + +/* -- other body styles ----------------------------------------------------- */ + +ol.arabic { + list-style: decimal; +} + +ol.loweralpha { + list-style: lower-alpha; +} + +ol.upperalpha { + list-style: upper-alpha; +} + +ol.lowerroman { + list-style: lower-roman; +} + +ol.upperroman { + list-style: upper-roman; +} + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dt:target, .highlighted { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa; +} + +.line-block { + display: block; + margin-top: 1em; + margin-bottom: 1em; +} + +.line-block .line-block { + margin-top: 0; + margin-bottom: 0; + margin-left: 1.5em; +} + +.guilabel, .menuselection { + font-family: sans-serif; +} + +.accelerator { + text-decoration: underline; +} + +.classifier { + font-style: oblique; +} + +abbr, acronym { + border-bottom: dotted 1px; + cursor: help; +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; + overflow-y: hidden; /* fixes display issues on Chrome browsers */ +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +.viewcode-link { + float: right; +} + +.viewcode-back { + float: right; + font-family: sans-serif; +} + +div.viewcode-block:target { + margin: -1px -10px; + padding: 0 10px; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.body div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0 !important; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} \ No newline at end of file diff -r 85f290e474e2 build/_static/comment-bright.png Binary file build/_static/comment-bright.png has changed diff -r 85f290e474e2 build/_static/comment-close.png Binary file build/_static/comment-close.png has changed diff -r 85f290e474e2 build/_static/comment.png Binary file build/_static/comment.png has changed diff -r 85f290e474e2 build/_static/doctools.js --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_static/doctools.js Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,238 @@ +/* + * doctools.js + * ~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for all documentation. + * + * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +/** + * select a different prefix for underscore + */ +$u = _.noConflict(); + +/** + * make the code below compatible with browsers without + * an installed firebug like debugger +if (!window.console || !console.firebug) { + var names = ["log", "debug", "info", "warn", "error", "assert", "dir", + "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", + "profile", "profileEnd"]; + window.console = {}; + for (var i = 0; i < names.length; ++i) + window.console[names[i]] = function() {}; +} + */ + +/** + * small helper function to urldecode strings + */ +jQuery.urldecode = function(x) { + return decodeURIComponent(x).replace(/\+/g, ' '); +}; + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s == 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +}; + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node) { + if (node.nodeType == 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) { + var span = document.createElement("span"); + span.className = className; + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this); + }); + } + } + return this.each(function() { + highlight(this); + }); +}; + +/** + * Small JavaScript module for the documentation. + */ +var Documentation = { + + init : function() { + this.fixFirefoxAnchorBug(); + this.highlightSearchWords(); + this.initIndexTable(); + }, + + /** + * i18n support + */ + TRANSLATIONS : {}, + PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, + LOCALE : 'unknown', + + // gettext and ngettext don't access this so that the functions + // can safely bound to a different name (_ = Documentation.gettext) + gettext : function(string) { + var translated = Documentation.TRANSLATIONS[string]; + if (typeof translated == 'undefined') + return string; + return (typeof translated == 'string') ? translated : translated[0]; + }, + + ngettext : function(singular, plural, n) { + var translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated == 'undefined') + return (n == 1) ? singular : plural; + return translated[Documentation.PLURALEXPR(n)]; + }, + + addTranslations : function(catalog) { + for (var key in catalog.messages) + this.TRANSLATIONS[key] = catalog.messages[key]; + this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); + this.LOCALE = catalog.locale; + }, + + /** + * add context elements like header anchor links + */ + addContextElements : function() { + $('div[id] > :header:first').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this headline')). + appendTo(this); + }); + $('dt[id]').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this definition')). + appendTo(this); + }); + }, + + /** + * workaround a firefox stupidity + */ + fixFirefoxAnchorBug : function() { + if (document.location.hash && $.browser.mozilla) + window.setTimeout(function() { + document.location.href += ''; + }, 10); + }, + + /** + * highlight the search words provided in the url in the text + */ + highlightSearchWords : function() { + var params = $.getQueryParameters(); + var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; + if (terms.length) { + var body = $('div.body'); + if (!body.length) { + body = $('body'); + } + window.setTimeout(function() { + $.each(terms, function() { + body.highlightText(this.toLowerCase(), 'highlighted'); + }); + }, 10); + $('

' + _('Hide Search Matches') + '

') + .appendTo($('#searchbox')); + } + }, + + /** + * init the domain index toggle buttons + */ + initIndexTable : function() { + var togglers = $('img.toggler').click(function() { + var src = $(this).attr('src'); + var idnum = $(this).attr('id').substr(7); + $('tr.cg-' + idnum).toggle(); + if (src.substr(-9) == 'minus.png') + $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); + else + $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); + }).css('display', ''); + if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { + togglers.click(); + } + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords : function() { + $('#searchbox .highlight-link').fadeOut(300); + $('span.highlighted').removeClass('highlighted'); + }, + + /** + * make the url absolute + */ + makeURL : function(relativeURL) { + return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; + }, + + /** + * get the current relative url + */ + getCurrentURL : function() { + var path = document.location.pathname; + var parts = path.split(/\//); + $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { + if (this == '..') + parts.pop(); + }); + var url = parts.join('/'); + return path.substring(url.lastIndexOf('/') + 1, path.length - 1); + } +}; + +// quick alias for translations +_ = Documentation.gettext; + +$(document).ready(function() { + Documentation.init(); +}); diff -r 85f290e474e2 build/_static/down-pressed.png Binary file build/_static/down-pressed.png has changed diff -r 85f290e474e2 build/_static/down.png Binary file build/_static/down.png has changed diff -r 85f290e474e2 build/_static/file.png Binary file build/_static/file.png has changed diff -r 85f290e474e2 build/_static/jquery.js --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_static/jquery.js Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,2 @@ +/*! jQuery v1.8.3 jquery.com | jquery.org/license */ +(function(e,t){function _(e){var t=M[e]={};return v.each(e.split(y),function(e,n){t[n]=!0}),t}function H(e,n,r){if(r===t&&e.nodeType===1){var i="data-"+n.replace(P,"-$1").toLowerCase();r=e.getAttribute(i);if(typeof r=="string"){try{r=r==="true"?!0:r==="false"?!1:r==="null"?null:+r+""===r?+r:D.test(r)?v.parseJSON(r):r}catch(s){}v.data(e,n,r)}else r=t}return r}function B(e){var t;for(t in e){if(t==="data"&&v.isEmptyObject(e[t]))continue;if(t!=="toJSON")return!1}return!0}function et(){return!1}function tt(){return!0}function ut(e){return!e||!e.parentNode||e.parentNode.nodeType===11}function at(e,t){do e=e[t];while(e&&e.nodeType!==1);return e}function ft(e,t,n){t=t||0;if(v.isFunction(t))return v.grep(e,function(e,r){var i=!!t.call(e,r,e);return i===n});if(t.nodeType)return v.grep(e,function(e,r){return e===t===n});if(typeof t=="string"){var r=v.grep(e,function(e){return e.nodeType===1});if(it.test(t))return v.filter(t,r,!n);t=v.filter(t,r)}return v.grep(e,function(e,r){return v.inArray(e,t)>=0===n})}function lt(e){var t=ct.split("|"),n=e.createDocumentFragment();if(n.createElement)while(t.length)n.createElement(t.pop());return n}function Lt(e,t){return e.getElementsByTagName(t)[0]||e.appendChild(e.ownerDocument.createElement(t))}function At(e,t){if(t.nodeType!==1||!v.hasData(e))return;var n,r,i,s=v._data(e),o=v._data(t,s),u=s.events;if(u){delete o.handle,o.events={};for(n in u)for(r=0,i=u[n].length;r").appendTo(i.body),n=t.css("display");t.remove();if(n==="none"||n===""){Pt=i.body.appendChild(Pt||v.extend(i.createElement("iframe"),{frameBorder:0,width:0,height:0}));if(!Ht||!Pt.createElement)Ht=(Pt.contentWindow||Pt.contentDocument).document,Ht.write(""),Ht.close();t=Ht.body.appendChild(Ht.createElement(e)),n=Dt(t,"display"),i.body.removeChild(Pt)}return Wt[e]=n,n}function fn(e,t,n,r){var i;if(v.isArray(t))v.each(t,function(t,i){n||sn.test(e)?r(e,i):fn(e+"["+(typeof i=="object"?t:"")+"]",i,n,r)});else if(!n&&v.type(t)==="object")for(i in t)fn(e+"["+i+"]",t[i],n,r);else r(e,t)}function Cn(e){return function(t,n){typeof t!="string"&&(n=t,t="*");var r,i,s,o=t.toLowerCase().split(y),u=0,a=o.length;if(v.isFunction(n))for(;u)[^>]*$|#([\w\-]*)$)/,E=/^<(\w+)\s*\/?>(?:<\/\1>|)$/,S=/^[\],:{}\s]*$/,x=/(?:^|:|,)(?:\s*\[)+/g,T=/\\(?:["\\\/bfnrt]|u[\da-fA-F]{4})/g,N=/"[^"\\\r\n]*"|true|false|null|-?(?:\d\d*\.|)\d+(?:[eE][\-+]?\d+|)/g,C=/^-ms-/,k=/-([\da-z])/gi,L=function(e,t){return(t+"").toUpperCase()},A=function(){i.addEventListener?(i.removeEventListener("DOMContentLoaded",A,!1),v.ready()):i.readyState==="complete"&&(i.detachEvent("onreadystatechange",A),v.ready())},O={};v.fn=v.prototype={constructor:v,init:function(e,n,r){var s,o,u,a;if(!e)return this;if(e.nodeType)return this.context=this[0]=e,this.length=1,this;if(typeof e=="string"){e.charAt(0)==="<"&&e.charAt(e.length-1)===">"&&e.length>=3?s=[null,e,null]:s=w.exec(e);if(s&&(s[1]||!n)){if(s[1])return n=n instanceof v?n[0]:n,a=n&&n.nodeType?n.ownerDocument||n:i,e=v.parseHTML(s[1],a,!0),E.test(s[1])&&v.isPlainObject(n)&&this.attr.call(e,n,!0),v.merge(this,e);o=i.getElementById(s[2]);if(o&&o.parentNode){if(o.id!==s[2])return r.find(e);this.length=1,this[0]=o}return this.context=i,this.selector=e,this}return!n||n.jquery?(n||r).find(e):this.constructor(n).find(e)}return v.isFunction(e)?r.ready(e):(e.selector!==t&&(this.selector=e.selector,this.context=e.context),v.makeArray(e,this))},selector:"",jquery:"1.8.3",length:0,size:function(){return this.length},toArray:function(){return l.call(this)},get:function(e){return e==null?this.toArray():e<0?this[this.length+e]:this[e]},pushStack:function(e,t,n){var r=v.merge(this.constructor(),e);return r.prevObject=this,r.context=this.context,t==="find"?r.selector=this.selector+(this.selector?" ":"")+n:t&&(r.selector=this.selector+"."+t+"("+n+")"),r},each:function(e,t){return v.each(this,e,t)},ready:function(e){return v.ready.promise().done(e),this},eq:function(e){return e=+e,e===-1?this.slice(e):this.slice(e,e+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(l.apply(this,arguments),"slice",l.call(arguments).join(","))},map:function(e){return this.pushStack(v.map(this,function(t,n){return e.call(t,n,t)}))},end:function(){return this.prevObject||this.constructor(null)},push:f,sort:[].sort,splice:[].splice},v.fn.init.prototype=v.fn,v.extend=v.fn.extend=function(){var e,n,r,i,s,o,u=arguments[0]||{},a=1,f=arguments.length,l=!1;typeof u=="boolean"&&(l=u,u=arguments[1]||{},a=2),typeof u!="object"&&!v.isFunction(u)&&(u={}),f===a&&(u=this,--a);for(;a0)return;r.resolveWith(i,[v]),v.fn.trigger&&v(i).trigger("ready").off("ready")},isFunction:function(e){return v.type(e)==="function"},isArray:Array.isArray||function(e){return v.type(e)==="array"},isWindow:function(e){return e!=null&&e==e.window},isNumeric:function(e){return!isNaN(parseFloat(e))&&isFinite(e)},type:function(e){return e==null?String(e):O[h.call(e)]||"object"},isPlainObject:function(e){if(!e||v.type(e)!=="object"||e.nodeType||v.isWindow(e))return!1;try{if(e.constructor&&!p.call(e,"constructor")&&!p.call(e.constructor.prototype,"isPrototypeOf"))return!1}catch(n){return!1}var r;for(r in e);return r===t||p.call(e,r)},isEmptyObject:function(e){var t;for(t in e)return!1;return!0},error:function(e){throw new Error(e)},parseHTML:function(e,t,n){var r;return!e||typeof e!="string"?null:(typeof t=="boolean"&&(n=t,t=0),t=t||i,(r=E.exec(e))?[t.createElement(r[1])]:(r=v.buildFragment([e],t,n?null:[]),v.merge([],(r.cacheable?v.clone(r.fragment):r.fragment).childNodes)))},parseJSON:function(t){if(!t||typeof t!="string")return null;t=v.trim(t);if(e.JSON&&e.JSON.parse)return e.JSON.parse(t);if(S.test(t.replace(T,"@").replace(N,"]").replace(x,"")))return(new Function("return "+t))();v.error("Invalid JSON: "+t)},parseXML:function(n){var r,i;if(!n||typeof n!="string")return null;try{e.DOMParser?(i=new DOMParser,r=i.parseFromString(n,"text/xml")):(r=new ActiveXObject("Microsoft.XMLDOM"),r.async="false",r.loadXML(n))}catch(s){r=t}return(!r||!r.documentElement||r.getElementsByTagName("parsererror").length)&&v.error("Invalid XML: "+n),r},noop:function(){},globalEval:function(t){t&&g.test(t)&&(e.execScript||function(t){e.eval.call(e,t)})(t)},camelCase:function(e){return e.replace(C,"ms-").replace(k,L)},nodeName:function(e,t){return e.nodeName&&e.nodeName.toLowerCase()===t.toLowerCase()},each:function(e,n,r){var i,s=0,o=e.length,u=o===t||v.isFunction(e);if(r){if(u){for(i in e)if(n.apply(e[i],r)===!1)break}else for(;s0&&e[0]&&e[a-1]||a===0||v.isArray(e));if(f)for(;u-1)a.splice(n,1),i&&(n<=o&&o--,n<=u&&u--)}),this},has:function(e){return v.inArray(e,a)>-1},empty:function(){return a=[],this},disable:function(){return a=f=n=t,this},disabled:function(){return!a},lock:function(){return f=t,n||c.disable(),this},locked:function(){return!f},fireWith:function(e,t){return t=t||[],t=[e,t.slice?t.slice():t],a&&(!r||f)&&(i?f.push(t):l(t)),this},fire:function(){return c.fireWith(this,arguments),this},fired:function(){return!!r}};return c},v.extend({Deferred:function(e){var t=[["resolve","done",v.Callbacks("once memory"),"resolved"],["reject","fail",v.Callbacks("once memory"),"rejected"],["notify","progress",v.Callbacks("memory")]],n="pending",r={state:function(){return n},always:function(){return i.done(arguments).fail(arguments),this},then:function(){var e=arguments;return v.Deferred(function(n){v.each(t,function(t,r){var s=r[0],o=e[t];i[r[1]](v.isFunction(o)?function(){var e=o.apply(this,arguments);e&&v.isFunction(e.promise)?e.promise().done(n.resolve).fail(n.reject).progress(n.notify):n[s+"With"](this===i?n:this,[e])}:n[s])}),e=null}).promise()},promise:function(e){return e!=null?v.extend(e,r):r}},i={};return r.pipe=r.then,v.each(t,function(e,s){var o=s[2],u=s[3];r[s[1]]=o.add,u&&o.add(function(){n=u},t[e^1][2].disable,t[2][2].lock),i[s[0]]=o.fire,i[s[0]+"With"]=o.fireWith}),r.promise(i),e&&e.call(i,i),i},when:function(e){var t=0,n=l.call(arguments),r=n.length,i=r!==1||e&&v.isFunction(e.promise)?r:0,s=i===1?e:v.Deferred(),o=function(e,t,n){return function(r){t[e]=this,n[e]=arguments.length>1?l.call(arguments):r,n===u?s.notifyWith(t,n):--i||s.resolveWith(t,n)}},u,a,f;if(r>1){u=new Array(r),a=new Array(r),f=new Array(r);for(;t
a",n=p.getElementsByTagName("*"),r=p.getElementsByTagName("a")[0];if(!n||!r||!n.length)return{};s=i.createElement("select"),o=s.appendChild(i.createElement("option")),u=p.getElementsByTagName("input")[0],r.style.cssText="top:1px;float:left;opacity:.5",t={leadingWhitespace:p.firstChild.nodeType===3,tbody:!p.getElementsByTagName("tbody").length,htmlSerialize:!!p.getElementsByTagName("link").length,style:/top/.test(r.getAttribute("style")),hrefNormalized:r.getAttribute("href")==="/a",opacity:/^0.5/.test(r.style.opacity),cssFloat:!!r.style.cssFloat,checkOn:u.value==="on",optSelected:o.selected,getSetAttribute:p.className!=="t",enctype:!!i.createElement("form").enctype,html5Clone:i.createElement("nav").cloneNode(!0).outerHTML!=="<:nav>",boxModel:i.compatMode==="CSS1Compat",submitBubbles:!0,changeBubbles:!0,focusinBubbles:!1,deleteExpando:!0,noCloneEvent:!0,inlineBlockNeedsLayout:!1,shrinkWrapBlocks:!1,reliableMarginRight:!0,boxSizingReliable:!0,pixelPosition:!1},u.checked=!0,t.noCloneChecked=u.cloneNode(!0).checked,s.disabled=!0,t.optDisabled=!o.disabled;try{delete p.test}catch(d){t.deleteExpando=!1}!p.addEventListener&&p.attachEvent&&p.fireEvent&&(p.attachEvent("onclick",h=function(){t.noCloneEvent=!1}),p.cloneNode(!0).fireEvent("onclick"),p.detachEvent("onclick",h)),u=i.createElement("input"),u.value="t",u.setAttribute("type","radio"),t.radioValue=u.value==="t",u.setAttribute("checked","checked"),u.setAttribute("name","t"),p.appendChild(u),a=i.createDocumentFragment(),a.appendChild(p.lastChild),t.checkClone=a.cloneNode(!0).cloneNode(!0).lastChild.checked,t.appendChecked=u.checked,a.removeChild(u),a.appendChild(p);if(p.attachEvent)for(l in{submit:!0,change:!0,focusin:!0})f="on"+l,c=f in p,c||(p.setAttribute(f,"return;"),c=typeof p[f]=="function"),t[l+"Bubbles"]=c;return v(function(){var n,r,s,o,u="padding:0;margin:0;border:0;display:block;overflow:hidden;",a=i.getElementsByTagName("body")[0];if(!a)return;n=i.createElement("div"),n.style.cssText="visibility:hidden;border:0;width:0;height:0;position:static;top:0;margin-top:1px",a.insertBefore(n,a.firstChild),r=i.createElement("div"),n.appendChild(r),r.innerHTML="
t
",s=r.getElementsByTagName("td"),s[0].style.cssText="padding:0;margin:0;border:0;display:none",c=s[0].offsetHeight===0,s[0].style.display="",s[1].style.display="none",t.reliableHiddenOffsets=c&&s[0].offsetHeight===0,r.innerHTML="",r.style.cssText="box-sizing:border-box;-moz-box-sizing:border-box;-webkit-box-sizing:border-box;padding:1px;border:1px;display:block;width:4px;margin-top:1%;position:absolute;top:1%;",t.boxSizing=r.offsetWidth===4,t.doesNotIncludeMarginInBodyOffset=a.offsetTop!==1,e.getComputedStyle&&(t.pixelPosition=(e.getComputedStyle(r,null)||{}).top!=="1%",t.boxSizingReliable=(e.getComputedStyle(r,null)||{width:"4px"}).width==="4px",o=i.createElement("div"),o.style.cssText=r.style.cssText=u,o.style.marginRight=o.style.width="0",r.style.width="1px",r.appendChild(o),t.reliableMarginRight=!parseFloat((e.getComputedStyle(o,null)||{}).marginRight)),typeof r.style.zoom!="undefined"&&(r.innerHTML="",r.style.cssText=u+"width:1px;padding:1px;display:inline;zoom:1",t.inlineBlockNeedsLayout=r.offsetWidth===3,r.style.display="block",r.style.overflow="visible",r.innerHTML="
",r.firstChild.style.width="5px",t.shrinkWrapBlocks=r.offsetWidth!==3,n.style.zoom=1),a.removeChild(n),n=r=s=o=null}),a.removeChild(p),n=r=s=o=u=a=p=null,t}();var D=/(?:\{[\s\S]*\}|\[[\s\S]*\])$/,P=/([A-Z])/g;v.extend({cache:{},deletedIds:[],uuid:0,expando:"jQuery"+(v.fn.jquery+Math.random()).replace(/\D/g,""),noData:{embed:!0,object:"clsid:D27CDB6E-AE6D-11cf-96B8-444553540000",applet:!0},hasData:function(e){return e=e.nodeType?v.cache[e[v.expando]]:e[v.expando],!!e&&!B(e)},data:function(e,n,r,i){if(!v.acceptData(e))return;var s,o,u=v.expando,a=typeof n=="string",f=e.nodeType,l=f?v.cache:e,c=f?e[u]:e[u]&&u;if((!c||!l[c]||!i&&!l[c].data)&&a&&r===t)return;c||(f?e[u]=c=v.deletedIds.pop()||v.guid++:c=u),l[c]||(l[c]={},f||(l[c].toJSON=v.noop));if(typeof n=="object"||typeof n=="function")i?l[c]=v.extend(l[c],n):l[c].data=v.extend(l[c].data,n);return s=l[c],i||(s.data||(s.data={}),s=s.data),r!==t&&(s[v.camelCase(n)]=r),a?(o=s[n],o==null&&(o=s[v.camelCase(n)])):o=s,o},removeData:function(e,t,n){if(!v.acceptData(e))return;var r,i,s,o=e.nodeType,u=o?v.cache:e,a=o?e[v.expando]:v.expando;if(!u[a])return;if(t){r=n?u[a]:u[a].data;if(r){v.isArray(t)||(t in r?t=[t]:(t=v.camelCase(t),t in r?t=[t]:t=t.split(" ")));for(i=0,s=t.length;i1,null,!1))},removeData:function(e){return this.each(function(){v.removeData(this,e)})}}),v.extend({queue:function(e,t,n){var r;if(e)return t=(t||"fx")+"queue",r=v._data(e,t),n&&(!r||v.isArray(n)?r=v._data(e,t,v.makeArray(n)):r.push(n)),r||[]},dequeue:function(e,t){t=t||"fx";var n=v.queue(e,t),r=n.length,i=n.shift(),s=v._queueHooks(e,t),o=function(){v.dequeue(e,t)};i==="inprogress"&&(i=n.shift(),r--),i&&(t==="fx"&&n.unshift("inprogress"),delete s.stop,i.call(e,o,s)),!r&&s&&s.empty.fire()},_queueHooks:function(e,t){var n=t+"queueHooks";return v._data(e,n)||v._data(e,n,{empty:v.Callbacks("once memory").add(function(){v.removeData(e,t+"queue",!0),v.removeData(e,n,!0)})})}}),v.fn.extend({queue:function(e,n){var r=2;return typeof e!="string"&&(n=e,e="fx",r--),arguments.length1)},removeAttr:function(e){return this.each(function(){v.removeAttr(this,e)})},prop:function(e,t){return v.access(this,v.prop,e,t,arguments.length>1)},removeProp:function(e){return e=v.propFix[e]||e,this.each(function(){try{this[e]=t,delete this[e]}catch(n){}})},addClass:function(e){var t,n,r,i,s,o,u;if(v.isFunction(e))return this.each(function(t){v(this).addClass(e.call(this,t,this.className))});if(e&&typeof e=="string"){t=e.split(y);for(n=0,r=this.length;n=0)r=r.replace(" "+n[s]+" "," ");i.className=e?v.trim(r):""}}}return this},toggleClass:function(e,t){var n=typeof e,r=typeof t=="boolean";return v.isFunction(e)?this.each(function(n){v(this).toggleClass(e.call(this,n,this.className,t),t)}):this.each(function(){if(n==="string"){var i,s=0,o=v(this),u=t,a=e.split(y);while(i=a[s++])u=r?u:!o.hasClass(i),o[u?"addClass":"removeClass"](i)}else if(n==="undefined"||n==="boolean")this.className&&v._data(this,"__className__",this.className),this.className=this.className||e===!1?"":v._data(this,"__className__")||""})},hasClass:function(e){var t=" "+e+" ",n=0,r=this.length;for(;n=0)return!0;return!1},val:function(e){var n,r,i,s=this[0];if(!arguments.length){if(s)return n=v.valHooks[s.type]||v.valHooks[s.nodeName.toLowerCase()],n&&"get"in n&&(r=n.get(s,"value"))!==t?r:(r=s.value,typeof r=="string"?r.replace(R,""):r==null?"":r);return}return i=v.isFunction(e),this.each(function(r){var s,o=v(this);if(this.nodeType!==1)return;i?s=e.call(this,r,o.val()):s=e,s==null?s="":typeof s=="number"?s+="":v.isArray(s)&&(s=v.map(s,function(e){return e==null?"":e+""})),n=v.valHooks[this.type]||v.valHooks[this.nodeName.toLowerCase()];if(!n||!("set"in n)||n.set(this,s,"value")===t)this.value=s})}}),v.extend({valHooks:{option:{get:function(e){var t=e.attributes.value;return!t||t.specified?e.value:e.text}},select:{get:function(e){var t,n,r=e.options,i=e.selectedIndex,s=e.type==="select-one"||i<0,o=s?null:[],u=s?i+1:r.length,a=i<0?u:s?i:0;for(;a=0}),n.length||(e.selectedIndex=-1),n}}},attrFn:{},attr:function(e,n,r,i){var s,o,u,a=e.nodeType;if(!e||a===3||a===8||a===2)return;if(i&&v.isFunction(v.fn[n]))return v(e)[n](r);if(typeof e.getAttribute=="undefined")return v.prop(e,n,r);u=a!==1||!v.isXMLDoc(e),u&&(n=n.toLowerCase(),o=v.attrHooks[n]||(X.test(n)?F:j));if(r!==t){if(r===null){v.removeAttr(e,n);return}return o&&"set"in o&&u&&(s=o.set(e,r,n))!==t?s:(e.setAttribute(n,r+""),r)}return o&&"get"in o&&u&&(s=o.get(e,n))!==null?s:(s=e.getAttribute(n),s===null?t:s)},removeAttr:function(e,t){var n,r,i,s,o=0;if(t&&e.nodeType===1){r=t.split(y);for(;o=0}})});var $=/^(?:textarea|input|select)$/i,J=/^([^\.]*|)(?:\.(.+)|)$/,K=/(?:^|\s)hover(\.\S+|)\b/,Q=/^key/,G=/^(?:mouse|contextmenu)|click/,Y=/^(?:focusinfocus|focusoutblur)$/,Z=function(e){return v.event.special.hover?e:e.replace(K,"mouseenter$1 mouseleave$1")};v.event={add:function(e,n,r,i,s){var o,u,a,f,l,c,h,p,d,m,g;if(e.nodeType===3||e.nodeType===8||!n||!r||!(o=v._data(e)))return;r.handler&&(d=r,r=d.handler,s=d.selector),r.guid||(r.guid=v.guid++),a=o.events,a||(o.events=a={}),u=o.handle,u||(o.handle=u=function(e){return typeof v=="undefined"||!!e&&v.event.triggered===e.type?t:v.event.dispatch.apply(u.elem,arguments)},u.elem=e),n=v.trim(Z(n)).split(" ");for(f=0;f=0&&(y=y.slice(0,-1),a=!0),y.indexOf(".")>=0&&(b=y.split("."),y=b.shift(),b.sort());if((!s||v.event.customEvent[y])&&!v.event.global[y])return;n=typeof n=="object"?n[v.expando]?n:new v.Event(y,n):new v.Event(y),n.type=y,n.isTrigger=!0,n.exclusive=a,n.namespace=b.join("."),n.namespace_re=n.namespace?new RegExp("(^|\\.)"+b.join("\\.(?:.*\\.|)")+"(\\.|$)"):null,h=y.indexOf(":")<0?"on"+y:"";if(!s){u=v.cache;for(f in u)u[f].events&&u[f].events[y]&&v.event.trigger(n,r,u[f].handle.elem,!0);return}n.result=t,n.target||(n.target=s),r=r!=null?v.makeArray(r):[],r.unshift(n),p=v.event.special[y]||{};if(p.trigger&&p.trigger.apply(s,r)===!1)return;m=[[s,p.bindType||y]];if(!o&&!p.noBubble&&!v.isWindow(s)){g=p.delegateType||y,l=Y.test(g+y)?s:s.parentNode;for(c=s;l;l=l.parentNode)m.push([l,g]),c=l;c===(s.ownerDocument||i)&&m.push([c.defaultView||c.parentWindow||e,g])}for(f=0;f=0:v.find(h,this,null,[s]).length),u[h]&&f.push(c);f.length&&w.push({elem:s,matches:f})}d.length>m&&w.push({elem:this,matches:d.slice(m)});for(r=0;r0?this.on(t,null,e,n):this.trigger(t)},Q.test(t)&&(v.event.fixHooks[t]=v.event.keyHooks),G.test(t)&&(v.event.fixHooks[t]=v.event.mouseHooks)}),function(e,t){function nt(e,t,n,r){n=n||[],t=t||g;var i,s,a,f,l=t.nodeType;if(!e||typeof e!="string")return n;if(l!==1&&l!==9)return[];a=o(t);if(!a&&!r)if(i=R.exec(e))if(f=i[1]){if(l===9){s=t.getElementById(f);if(!s||!s.parentNode)return n;if(s.id===f)return n.push(s),n}else if(t.ownerDocument&&(s=t.ownerDocument.getElementById(f))&&u(t,s)&&s.id===f)return n.push(s),n}else{if(i[2])return S.apply(n,x.call(t.getElementsByTagName(e),0)),n;if((f=i[3])&&Z&&t.getElementsByClassName)return S.apply(n,x.call(t.getElementsByClassName(f),0)),n}return vt(e.replace(j,"$1"),t,n,r,a)}function rt(e){return function(t){var n=t.nodeName.toLowerCase();return n==="input"&&t.type===e}}function it(e){return function(t){var n=t.nodeName.toLowerCase();return(n==="input"||n==="button")&&t.type===e}}function st(e){return N(function(t){return t=+t,N(function(n,r){var i,s=e([],n.length,t),o=s.length;while(o--)n[i=s[o]]&&(n[i]=!(r[i]=n[i]))})})}function ot(e,t,n){if(e===t)return n;var r=e.nextSibling;while(r){if(r===t)return-1;r=r.nextSibling}return 1}function ut(e,t){var n,r,s,o,u,a,f,l=L[d][e+" "];if(l)return t?0:l.slice(0);u=e,a=[],f=i.preFilter;while(u){if(!n||(r=F.exec(u)))r&&(u=u.slice(r[0].length)||u),a.push(s=[]);n=!1;if(r=I.exec(u))s.push(n=new m(r.shift())),u=u.slice(n.length),n.type=r[0].replace(j," ");for(o in i.filter)(r=J[o].exec(u))&&(!f[o]||(r=f[o](r)))&&(s.push(n=new m(r.shift())),u=u.slice(n.length),n.type=o,n.matches=r);if(!n)break}return t?u.length:u?nt.error(e):L(e,a).slice(0)}function at(e,t,r){var i=t.dir,s=r&&t.dir==="parentNode",o=w++;return t.first?function(t,n,r){while(t=t[i])if(s||t.nodeType===1)return e(t,n,r)}:function(t,r,u){if(!u){var a,f=b+" "+o+" ",l=f+n;while(t=t[i])if(s||t.nodeType===1){if((a=t[d])===l)return t.sizset;if(typeof a=="string"&&a.indexOf(f)===0){if(t.sizset)return t}else{t[d]=l;if(e(t,r,u))return t.sizset=!0,t;t.sizset=!1}}}else while(t=t[i])if(s||t.nodeType===1)if(e(t,r,u))return t}}function ft(e){return e.length>1?function(t,n,r){var i=e.length;while(i--)if(!e[i](t,n,r))return!1;return!0}:e[0]}function lt(e,t,n,r,i){var s,o=[],u=0,a=e.length,f=t!=null;for(;u-1&&(s[f]=!(o[f]=c))}}else g=lt(g===o?g.splice(d,g.length):g),i?i(null,o,g,a):S.apply(o,g)})}function ht(e){var t,n,r,s=e.length,o=i.relative[e[0].type],u=o||i.relative[" "],a=o?1:0,f=at(function(e){return e===t},u,!0),l=at(function(e){return T.call(t,e)>-1},u,!0),h=[function(e,n,r){return!o&&(r||n!==c)||((t=n).nodeType?f(e,n,r):l(e,n,r))}];for(;a1&&ft(h),a>1&&e.slice(0,a-1).join("").replace(j,"$1"),n,a0,s=e.length>0,o=function(u,a,f,l,h){var p,d,v,m=[],y=0,w="0",x=u&&[],T=h!=null,N=c,C=u||s&&i.find.TAG("*",h&&a.parentNode||a),k=b+=N==null?1:Math.E;T&&(c=a!==g&&a,n=o.el);for(;(p=C[w])!=null;w++){if(s&&p){for(d=0;v=e[d];d++)if(v(p,a,f)){l.push(p);break}T&&(b=k,n=++o.el)}r&&((p=!v&&p)&&y--,u&&x.push(p))}y+=w;if(r&&w!==y){for(d=0;v=t[d];d++)v(x,m,a,f);if(u){if(y>0)while(w--)!x[w]&&!m[w]&&(m[w]=E.call(l));m=lt(m)}S.apply(l,m),T&&!u&&m.length>0&&y+t.length>1&&nt.uniqueSort(l)}return T&&(b=k,c=N),x};return o.el=0,r?N(o):o}function dt(e,t,n){var r=0,i=t.length;for(;r2&&(f=u[0]).type==="ID"&&t.nodeType===9&&!s&&i.relative[u[1].type]){t=i.find.ID(f.matches[0].replace($,""),t,s)[0];if(!t)return n;e=e.slice(u.shift().length)}for(o=J.POS.test(e)?-1:u.length-1;o>=0;o--){f=u[o];if(i.relative[l=f.type])break;if(c=i.find[l])if(r=c(f.matches[0].replace($,""),z.test(u[0].type)&&t.parentNode||t,s)){u.splice(o,1),e=r.length&&u.join("");if(!e)return S.apply(n,x.call(r,0)),n;break}}}return a(e,h)(r,t,s,n,z.test(e)),n}function mt(){}var n,r,i,s,o,u,a,f,l,c,h=!0,p="undefined",d=("sizcache"+Math.random()).replace(".",""),m=String,g=e.document,y=g.documentElement,b=0,w=0,E=[].pop,S=[].push,x=[].slice,T=[].indexOf||function(e){var t=0,n=this.length;for(;ti.cacheLength&&delete e[t.shift()],e[n+" "]=r},e)},k=C(),L=C(),A=C(),O="[\\x20\\t\\r\\n\\f]",M="(?:\\\\.|[-\\w]|[^\\x00-\\xa0])+",_=M.replace("w","w#"),D="([*^$|!~]?=)",P="\\["+O+"*("+M+")"+O+"*(?:"+D+O+"*(?:(['\"])((?:\\\\.|[^\\\\])*?)\\3|("+_+")|)|)"+O+"*\\]",H=":("+M+")(?:\\((?:(['\"])((?:\\\\.|[^\\\\])*?)\\2|([^()[\\]]*|(?:(?:"+P+")|[^:]|\\\\.)*|.*))\\)|)",B=":(even|odd|eq|gt|lt|nth|first|last)(?:\\("+O+"*((?:-\\d)?\\d*)"+O+"*\\)|)(?=[^-]|$)",j=new RegExp("^"+O+"+|((?:^|[^\\\\])(?:\\\\.)*)"+O+"+$","g"),F=new RegExp("^"+O+"*,"+O+"*"),I=new RegExp("^"+O+"*([\\x20\\t\\r\\n\\f>+~])"+O+"*"),q=new RegExp(H),R=/^(?:#([\w\-]+)|(\w+)|\.([\w\-]+))$/,U=/^:not/,z=/[\x20\t\r\n\f]*[+~]/,W=/:not\($/,X=/h\d/i,V=/input|select|textarea|button/i,$=/\\(?!\\)/g,J={ID:new RegExp("^#("+M+")"),CLASS:new RegExp("^\\.("+M+")"),NAME:new RegExp("^\\[name=['\"]?("+M+")['\"]?\\]"),TAG:new RegExp("^("+M.replace("w","w*")+")"),ATTR:new RegExp("^"+P),PSEUDO:new RegExp("^"+H),POS:new RegExp(B,"i"),CHILD:new RegExp("^:(only|nth|first|last)-child(?:\\("+O+"*(even|odd|(([+-]|)(\\d*)n|)"+O+"*(?:([+-]|)"+O+"*(\\d+)|))"+O+"*\\)|)","i"),needsContext:new RegExp("^"+O+"*[>+~]|"+B,"i")},K=function(e){var t=g.createElement("div");try{return e(t)}catch(n){return!1}finally{t=null}},Q=K(function(e){return e.appendChild(g.createComment("")),!e.getElementsByTagName("*").length}),G=K(function(e){return e.innerHTML="",e.firstChild&&typeof e.firstChild.getAttribute!==p&&e.firstChild.getAttribute("href")==="#"}),Y=K(function(e){e.innerHTML="";var t=typeof e.lastChild.getAttribute("multiple");return t!=="boolean"&&t!=="string"}),Z=K(function(e){return e.innerHTML="",!e.getElementsByClassName||!e.getElementsByClassName("e").length?!1:(e.lastChild.className="e",e.getElementsByClassName("e").length===2)}),et=K(function(e){e.id=d+0,e.innerHTML="
",y.insertBefore(e,y.firstChild);var t=g.getElementsByName&&g.getElementsByName(d).length===2+g.getElementsByName(d+0).length;return r=!g.getElementById(d),y.removeChild(e),t});try{x.call(y.childNodes,0)[0].nodeType}catch(tt){x=function(e){var t,n=[];for(;t=this[e];e++)n.push(t);return n}}nt.matches=function(e,t){return nt(e,null,null,t)},nt.matchesSelector=function(e,t){return nt(t,null,null,[e]).length>0},s=nt.getText=function(e){var t,n="",r=0,i=e.nodeType;if(i){if(i===1||i===9||i===11){if(typeof e.textContent=="string")return e.textContent;for(e=e.firstChild;e;e=e.nextSibling)n+=s(e)}else if(i===3||i===4)return e.nodeValue}else for(;t=e[r];r++)n+=s(t);return n},o=nt.isXML=function(e){var t=e&&(e.ownerDocument||e).documentElement;return t?t.nodeName!=="HTML":!1},u=nt.contains=y.contains?function(e,t){var n=e.nodeType===9?e.documentElement:e,r=t&&t.parentNode;return e===r||!!(r&&r.nodeType===1&&n.contains&&n.contains(r))}:y.compareDocumentPosition?function(e,t){return t&&!!(e.compareDocumentPosition(t)&16)}:function(e,t){while(t=t.parentNode)if(t===e)return!0;return!1},nt.attr=function(e,t){var n,r=o(e);return r||(t=t.toLowerCase()),(n=i.attrHandle[t])?n(e):r||Y?e.getAttribute(t):(n=e.getAttributeNode(t),n?typeof e[t]=="boolean"?e[t]?t:null:n.specified?n.value:null:null)},i=nt.selectors={cacheLength:50,createPseudo:N,match:J,attrHandle:G?{}:{href:function(e){return e.getAttribute("href",2)},type:function(e){return e.getAttribute("type")}},find:{ID:r?function(e,t,n){if(typeof t.getElementById!==p&&!n){var r=t.getElementById(e);return r&&r.parentNode?[r]:[]}}:function(e,n,r){if(typeof n.getElementById!==p&&!r){var i=n.getElementById(e);return i?i.id===e||typeof i.getAttributeNode!==p&&i.getAttributeNode("id").value===e?[i]:t:[]}},TAG:Q?function(e,t){if(typeof t.getElementsByTagName!==p)return t.getElementsByTagName(e)}:function(e,t){var n=t.getElementsByTagName(e);if(e==="*"){var r,i=[],s=0;for(;r=n[s];s++)r.nodeType===1&&i.push(r);return i}return n},NAME:et&&function(e,t){if(typeof t.getElementsByName!==p)return t.getElementsByName(name)},CLASS:Z&&function(e,t,n){if(typeof t.getElementsByClassName!==p&&!n)return t.getElementsByClassName(e)}},relative:{">":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace($,""),e[3]=(e[4]||e[5]||"").replace($,""),e[2]==="~="&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),e[1]==="nth"?(e[2]||nt.error(e[0]),e[3]=+(e[3]?e[4]+(e[5]||1):2*(e[2]==="even"||e[2]==="odd")),e[4]=+(e[6]+e[7]||e[2]==="odd")):e[2]&&nt.error(e[0]),e},PSEUDO:function(e){var t,n;if(J.CHILD.test(e[0]))return null;if(e[3])e[2]=e[3];else if(t=e[4])q.test(t)&&(n=ut(t,!0))&&(n=t.indexOf(")",t.length-n)-t.length)&&(t=t.slice(0,n),e[0]=e[0].slice(0,n)),e[2]=t;return e.slice(0,3)}},filter:{ID:r?function(e){return e=e.replace($,""),function(t){return t.getAttribute("id")===e}}:function(e){return e=e.replace($,""),function(t){var n=typeof t.getAttributeNode!==p&&t.getAttributeNode("id");return n&&n.value===e}},TAG:function(e){return e==="*"?function(){return!0}:(e=e.replace($,"").toLowerCase(),function(t){return t.nodeName&&t.nodeName.toLowerCase()===e})},CLASS:function(e){var t=k[d][e+" "];return t||(t=new RegExp("(^|"+O+")"+e+"("+O+"|$)"))&&k(e,function(e){return t.test(e.className||typeof e.getAttribute!==p&&e.getAttribute("class")||"")})},ATTR:function(e,t,n){return function(r,i){var s=nt.attr(r,e);return s==null?t==="!=":t?(s+="",t==="="?s===n:t==="!="?s!==n:t==="^="?n&&s.indexOf(n)===0:t==="*="?n&&s.indexOf(n)>-1:t==="$="?n&&s.substr(s.length-n.length)===n:t==="~="?(" "+s+" ").indexOf(n)>-1:t==="|="?s===n||s.substr(0,n.length+1)===n+"-":!1):!0}},CHILD:function(e,t,n,r){return e==="nth"?function(e){var t,i,s=e.parentNode;if(n===1&&r===0)return!0;if(s){i=0;for(t=s.firstChild;t;t=t.nextSibling)if(t.nodeType===1){i++;if(e===t)break}}return i-=r,i===n||i%n===0&&i/n>=0}:function(t){var n=t;switch(e){case"only":case"first":while(n=n.previousSibling)if(n.nodeType===1)return!1;if(e==="first")return!0;n=t;case"last":while(n=n.nextSibling)if(n.nodeType===1)return!1;return!0}}},PSEUDO:function(e,t){var n,r=i.pseudos[e]||i.setFilters[e.toLowerCase()]||nt.error("unsupported pseudo: "+e);return r[d]?r(t):r.length>1?(n=[e,e,"",t],i.setFilters.hasOwnProperty(e.toLowerCase())?N(function(e,n){var i,s=r(e,t),o=s.length;while(o--)i=T.call(e,s[o]),e[i]=!(n[i]=s[o])}):function(e){return r(e,0,n)}):r}},pseudos:{not:N(function(e){var t=[],n=[],r=a(e.replace(j,"$1"));return r[d]?N(function(e,t,n,i){var s,o=r(e,null,i,[]),u=e.length;while(u--)if(s=o[u])e[u]=!(t[u]=s)}):function(e,i,s){return t[0]=e,r(t,null,s,n),!n.pop()}}),has:N(function(e){return function(t){return nt(e,t).length>0}}),contains:N(function(e){return function(t){return(t.textContent||t.innerText||s(t)).indexOf(e)>-1}}),enabled:function(e){return e.disabled===!1},disabled:function(e){return e.disabled===!0},checked:function(e){var t=e.nodeName.toLowerCase();return t==="input"&&!!e.checked||t==="option"&&!!e.selected},selected:function(e){return e.parentNode&&e.parentNode.selectedIndex,e.selected===!0},parent:function(e){return!i.pseudos.empty(e)},empty:function(e){var t;e=e.firstChild;while(e){if(e.nodeName>"@"||(t=e.nodeType)===3||t===4)return!1;e=e.nextSibling}return!0},header:function(e){return X.test(e.nodeName)},text:function(e){var t,n;return e.nodeName.toLowerCase()==="input"&&(t=e.type)==="text"&&((n=e.getAttribute("type"))==null||n.toLowerCase()===t)},radio:rt("radio"),checkbox:rt("checkbox"),file:rt("file"),password:rt("password"),image:rt("image"),submit:it("submit"),reset:it("reset"),button:function(e){var t=e.nodeName.toLowerCase();return t==="input"&&e.type==="button"||t==="button"},input:function(e){return V.test(e.nodeName)},focus:function(e){var t=e.ownerDocument;return e===t.activeElement&&(!t.hasFocus||t.hasFocus())&&!!(e.type||e.href||~e.tabIndex)},active:function(e){return e===e.ownerDocument.activeElement},first:st(function(){return[0]}),last:st(function(e,t){return[t-1]}),eq:st(function(e,t,n){return[n<0?n+t:n]}),even:st(function(e,t){for(var n=0;n=0;)e.push(r);return e}),gt:st(function(e,t,n){for(var r=n<0?n+t:n;++r",e.querySelectorAll("[selected]").length||i.push("\\["+O+"*(?:checked|disabled|ismap|multiple|readonly|selected|value)"),e.querySelectorAll(":checked").length||i.push(":checked")}),K(function(e){e.innerHTML="

",e.querySelectorAll("[test^='']").length&&i.push("[*^$]="+O+"*(?:\"\"|'')"),e.innerHTML="",e.querySelectorAll(":enabled").length||i.push(":enabled",":disabled")}),i=new RegExp(i.join("|")),vt=function(e,r,s,o,u){if(!o&&!u&&!i.test(e)){var a,f,l=!0,c=d,h=r,p=r.nodeType===9&&e;if(r.nodeType===1&&r.nodeName.toLowerCase()!=="object"){a=ut(e),(l=r.getAttribute("id"))?c=l.replace(n,"\\$&"):r.setAttribute("id",c),c="[id='"+c+"'] ",f=a.length;while(f--)a[f]=c+a[f].join("");h=z.test(e)&&r.parentNode||r,p=a.join(",")}if(p)try{return S.apply(s,x.call(h.querySelectorAll(p),0)),s}catch(v){}finally{l||r.removeAttribute("id")}}return t(e,r,s,o,u)},u&&(K(function(t){e=u.call(t,"div");try{u.call(t,"[test!='']:sizzle"),s.push("!=",H)}catch(n){}}),s=new RegExp(s.join("|")),nt.matchesSelector=function(t,n){n=n.replace(r,"='$1']");if(!o(t)&&!s.test(n)&&!i.test(n))try{var a=u.call(t,n);if(a||e||t.document&&t.document.nodeType!==11)return a}catch(f){}return nt(n,null,null,[t]).length>0})}(),i.pseudos.nth=i.pseudos.eq,i.filters=mt.prototype=i.pseudos,i.setFilters=new mt,nt.attr=v.attr,v.find=nt,v.expr=nt.selectors,v.expr[":"]=v.expr.pseudos,v.unique=nt.uniqueSort,v.text=nt.getText,v.isXMLDoc=nt.isXML,v.contains=nt.contains}(e);var nt=/Until$/,rt=/^(?:parents|prev(?:Until|All))/,it=/^.[^:#\[\.,]*$/,st=v.expr.match.needsContext,ot={children:!0,contents:!0,next:!0,prev:!0};v.fn.extend({find:function(e){var t,n,r,i,s,o,u=this;if(typeof e!="string")return v(e).filter(function(){for(t=0,n=u.length;t0)for(i=r;i=0:v.filter(e,this).length>0:this.filter(e).length>0)},closest:function(e,t){var n,r=0,i=this.length,s=[],o=st.test(e)||typeof e!="string"?v(e,t||this.context):0;for(;r-1:v.find.matchesSelector(n,e)){s.push(n);break}n=n.parentNode}}return s=s.length>1?v.unique(s):s,this.pushStack(s,"closest",e)},index:function(e){return e?typeof e=="string"?v.inArray(this[0],v(e)):v.inArray(e.jquery?e[0]:e,this):this[0]&&this[0].parentNode?this.prevAll().length:-1},add:function(e,t){var n=typeof e=="string"?v(e,t):v.makeArray(e&&e.nodeType?[e]:e),r=v.merge(this.get(),n);return this.pushStack(ut(n[0])||ut(r[0])?r:v.unique(r))},addBack:function(e){return this.add(e==null?this.prevObject:this.prevObject.filter(e))}}),v.fn.andSelf=v.fn.addBack,v.each({parent:function(e){var t=e.parentNode;return t&&t.nodeType!==11?t:null},parents:function(e){return v.dir(e,"parentNode")},parentsUntil:function(e,t,n){return v.dir(e,"parentNode",n)},next:function(e){return at(e,"nextSibling")},prev:function(e){return at(e,"previousSibling")},nextAll:function(e){return v.dir(e,"nextSibling")},prevAll:function(e){return v.dir(e,"previousSibling")},nextUntil:function(e,t,n){return v.dir(e,"nextSibling",n)},prevUntil:function(e,t,n){return v.dir(e,"previousSibling",n)},siblings:function(e){return v.sibling((e.parentNode||{}).firstChild,e)},children:function(e){return v.sibling(e.firstChild)},contents:function(e){return v.nodeName(e,"iframe")?e.contentDocument||e.contentWindow.document:v.merge([],e.childNodes)}},function(e,t){v.fn[e]=function(n,r){var i=v.map(this,t,n);return nt.test(e)||(r=n),r&&typeof r=="string"&&(i=v.filter(r,i)),i=this.length>1&&!ot[e]?v.unique(i):i,this.length>1&&rt.test(e)&&(i=i.reverse()),this.pushStack(i,e,l.call(arguments).join(","))}}),v.extend({filter:function(e,t,n){return n&&(e=":not("+e+")"),t.length===1?v.find.matchesSelector(t[0],e)?[t[0]]:[]:v.find.matches(e,t)},dir:function(e,n,r){var i=[],s=e[n];while(s&&s.nodeType!==9&&(r===t||s.nodeType!==1||!v(s).is(r)))s.nodeType===1&&i.push(s),s=s[n];return i},sibling:function(e,t){var n=[];for(;e;e=e.nextSibling)e.nodeType===1&&e!==t&&n.push(e);return n}});var ct="abbr|article|aside|audio|bdi|canvas|data|datalist|details|figcaption|figure|footer|header|hgroup|mark|meter|nav|output|progress|section|summary|time|video",ht=/ jQuery\d+="(?:null|\d+)"/g,pt=/^\s+/,dt=/<(?!area|br|col|embed|hr|img|input|link|meta|param)(([\w:]+)[^>]*)\/>/gi,vt=/<([\w:]+)/,mt=/]","i"),Et=/^(?:checkbox|radio)$/,St=/checked\s*(?:[^=]|=\s*.checked.)/i,xt=/\/(java|ecma)script/i,Tt=/^\s*\s*$/g,Nt={option:[1,""],legend:[1,"
","
"],thead:[1,"","
"],tr:[2,"","
"],td:[3,"","
"],col:[2,"","
"],area:[1,"",""],_default:[0,"",""]},Ct=lt(i),kt=Ct.appendChild(i.createElement("div"));Nt.optgroup=Nt.option,Nt.tbody=Nt.tfoot=Nt.colgroup=Nt.caption=Nt.thead,Nt.th=Nt.td,v.support.htmlSerialize||(Nt._default=[1,"X
","
"]),v.fn.extend({text:function(e){return v.access(this,function(e){return e===t?v.text(this):this.empty().append((this[0]&&this[0].ownerDocument||i).createTextNode(e))},null,e,arguments.length)},wrapAll:function(e){if(v.isFunction(e))return this.each(function(t){v(this).wrapAll(e.call(this,t))});if(this[0]){var t=v(e,this[0].ownerDocument).eq(0).clone(!0);this[0].parentNode&&t.insertBefore(this[0]),t.map(function(){var e=this;while(e.firstChild&&e.firstChild.nodeType===1)e=e.firstChild;return e}).append(this)}return this},wrapInner:function(e){return v.isFunction(e)?this.each(function(t){v(this).wrapInner(e.call(this,t))}):this.each(function(){var t=v(this),n=t.contents();n.length?n.wrapAll(e):t.append(e)})},wrap:function(e){var t=v.isFunction(e);return this.each(function(n){v(this).wrapAll(t?e.call(this,n):e)})},unwrap:function(){return this.parent().each(function(){v.nodeName(this,"body")||v(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,!0,function(e){(this.nodeType===1||this.nodeType===11)&&this.appendChild(e)})},prepend:function(){return this.domManip(arguments,!0,function(e){(this.nodeType===1||this.nodeType===11)&&this.insertBefore(e,this.firstChild)})},before:function(){if(!ut(this[0]))return this.domManip(arguments,!1,function(e){this.parentNode.insertBefore(e,this)});if(arguments.length){var e=v.clean(arguments);return this.pushStack(v.merge(e,this),"before",this.selector)}},after:function(){if(!ut(this[0]))return this.domManip(arguments,!1,function(e){this.parentNode.insertBefore(e,this.nextSibling)});if(arguments.length){var e=v.clean(arguments);return this.pushStack(v.merge(this,e),"after",this.selector)}},remove:function(e,t){var n,r=0;for(;(n=this[r])!=null;r++)if(!e||v.filter(e,[n]).length)!t&&n.nodeType===1&&(v.cleanData(n.getElementsByTagName("*")),v.cleanData([n])),n.parentNode&&n.parentNode.removeChild(n);return this},empty:function(){var e,t=0;for(;(e=this[t])!=null;t++){e.nodeType===1&&v.cleanData(e.getElementsByTagName("*"));while(e.firstChild)e.removeChild(e.firstChild)}return this},clone:function(e,t){return e=e==null?!1:e,t=t==null?e:t,this.map(function(){return v.clone(this,e,t)})},html:function(e){return v.access(this,function(e){var n=this[0]||{},r=0,i=this.length;if(e===t)return n.nodeType===1?n.innerHTML.replace(ht,""):t;if(typeof e=="string"&&!yt.test(e)&&(v.support.htmlSerialize||!wt.test(e))&&(v.support.leadingWhitespace||!pt.test(e))&&!Nt[(vt.exec(e)||["",""])[1].toLowerCase()]){e=e.replace(dt,"<$1>");try{for(;r1&&typeof f=="string"&&St.test(f))return this.each(function(){v(this).domManip(e,n,r)});if(v.isFunction(f))return this.each(function(i){var s=v(this);e[0]=f.call(this,i,n?s.html():t),s.domManip(e,n,r)});if(this[0]){i=v.buildFragment(e,this,l),o=i.fragment,s=o.firstChild,o.childNodes.length===1&&(o=s);if(s){n=n&&v.nodeName(s,"tr");for(u=i.cacheable||c-1;a0?this.clone(!0):this).get(),v(o[i])[t](r),s=s.concat(r);return this.pushStack(s,e,o.selector)}}),v.extend({clone:function(e,t,n){var r,i,s,o;v.support.html5Clone||v.isXMLDoc(e)||!wt.test("<"+e.nodeName+">")?o=e.cloneNode(!0):(kt.innerHTML=e.outerHTML,kt.removeChild(o=kt.firstChild));if((!v.support.noCloneEvent||!v.support.noCloneChecked)&&(e.nodeType===1||e.nodeType===11)&&!v.isXMLDoc(e)){Ot(e,o),r=Mt(e),i=Mt(o);for(s=0;r[s];++s)i[s]&&Ot(r[s],i[s])}if(t){At(e,o);if(n){r=Mt(e),i=Mt(o);for(s=0;r[s];++s)At(r[s],i[s])}}return r=i=null,o},clean:function(e,t,n,r){var s,o,u,a,f,l,c,h,p,d,m,g,y=t===i&&Ct,b=[];if(!t||typeof t.createDocumentFragment=="undefined")t=i;for(s=0;(u=e[s])!=null;s++){typeof u=="number"&&(u+="");if(!u)continue;if(typeof u=="string")if(!gt.test(u))u=t.createTextNode(u);else{y=y||lt(t),c=t.createElement("div"),y.appendChild(c),u=u.replace(dt,"<$1>"),a=(vt.exec(u)||["",""])[1].toLowerCase(),f=Nt[a]||Nt._default,l=f[0],c.innerHTML=f[1]+u+f[2];while(l--)c=c.lastChild;if(!v.support.tbody){h=mt.test(u),p=a==="table"&&!h?c.firstChild&&c.firstChild.childNodes:f[1]===""&&!h?c.childNodes:[];for(o=p.length-1;o>=0;--o)v.nodeName(p[o],"tbody")&&!p[o].childNodes.length&&p[o].parentNode.removeChild(p[o])}!v.support.leadingWhitespace&&pt.test(u)&&c.insertBefore(t.createTextNode(pt.exec(u)[0]),c.firstChild),u=c.childNodes,c.parentNode.removeChild(c)}u.nodeType?b.push(u):v.merge(b,u)}c&&(u=c=y=null);if(!v.support.appendChecked)for(s=0;(u=b[s])!=null;s++)v.nodeName(u,"input")?_t(u):typeof u.getElementsByTagName!="undefined"&&v.grep(u.getElementsByTagName("input"),_t);if(n){m=function(e){if(!e.type||xt.test(e.type))return r?r.push(e.parentNode?e.parentNode.removeChild(e):e):n.appendChild(e)};for(s=0;(u=b[s])!=null;s++)if(!v.nodeName(u,"script")||!m(u))n.appendChild(u),typeof u.getElementsByTagName!="undefined"&&(g=v.grep(v.merge([],u.getElementsByTagName("script")),m),b.splice.apply(b,[s+1,0].concat(g)),s+=g.length)}return b},cleanData:function(e,t){var n,r,i,s,o=0,u=v.expando,a=v.cache,f=v.support.deleteExpando,l=v.event.special;for(;(i=e[o])!=null;o++)if(t||v.acceptData(i)){r=i[u],n=r&&a[r];if(n){if(n.events)for(s in n.events)l[s]?v.event.remove(i,s):v.removeEvent(i,s,n.handle);a[r]&&(delete a[r],f?delete i[u]:i.removeAttribute?i.removeAttribute(u):i[u]=null,v.deletedIds.push(r))}}}}),function(){var e,t;v.uaMatch=function(e){e=e.toLowerCase();var t=/(chrome)[ \/]([\w.]+)/.exec(e)||/(webkit)[ \/]([\w.]+)/.exec(e)||/(opera)(?:.*version|)[ \/]([\w.]+)/.exec(e)||/(msie) ([\w.]+)/.exec(e)||e.indexOf("compatible")<0&&/(mozilla)(?:.*? rv:([\w.]+)|)/.exec(e)||[];return{browser:t[1]||"",version:t[2]||"0"}},e=v.uaMatch(o.userAgent),t={},e.browser&&(t[e.browser]=!0,t.version=e.version),t.chrome?t.webkit=!0:t.webkit&&(t.safari=!0),v.browser=t,v.sub=function(){function e(t,n){return new e.fn.init(t,n)}v.extend(!0,e,this),e.superclass=this,e.fn=e.prototype=this(),e.fn.constructor=e,e.sub=this.sub,e.fn.init=function(r,i){return i&&i instanceof v&&!(i instanceof e)&&(i=e(i)),v.fn.init.call(this,r,i,t)},e.fn.init.prototype=e.fn;var t=e(i);return e}}();var Dt,Pt,Ht,Bt=/alpha\([^)]*\)/i,jt=/opacity=([^)]*)/,Ft=/^(top|right|bottom|left)$/,It=/^(none|table(?!-c[ea]).+)/,qt=/^margin/,Rt=new RegExp("^("+m+")(.*)$","i"),Ut=new RegExp("^("+m+")(?!px)[a-z%]+$","i"),zt=new RegExp("^([-+])=("+m+")","i"),Wt={BODY:"block"},Xt={position:"absolute",visibility:"hidden",display:"block"},Vt={letterSpacing:0,fontWeight:400},$t=["Top","Right","Bottom","Left"],Jt=["Webkit","O","Moz","ms"],Kt=v.fn.toggle;v.fn.extend({css:function(e,n){return v.access(this,function(e,n,r){return r!==t?v.style(e,n,r):v.css(e,n)},e,n,arguments.length>1)},show:function(){return Yt(this,!0)},hide:function(){return Yt(this)},toggle:function(e,t){var n=typeof e=="boolean";return v.isFunction(e)&&v.isFunction(t)?Kt.apply(this,arguments):this.each(function(){(n?e:Gt(this))?v(this).show():v(this).hide()})}}),v.extend({cssHooks:{opacity:{get:function(e,t){if(t){var n=Dt(e,"opacity");return n===""?"1":n}}}},cssNumber:{fillOpacity:!0,fontWeight:!0,lineHeight:!0,opacity:!0,orphans:!0,widows:!0,zIndex:!0,zoom:!0},cssProps:{"float":v.support.cssFloat?"cssFloat":"styleFloat"},style:function(e,n,r,i){if(!e||e.nodeType===3||e.nodeType===8||!e.style)return;var s,o,u,a=v.camelCase(n),f=e.style;n=v.cssProps[a]||(v.cssProps[a]=Qt(f,a)),u=v.cssHooks[n]||v.cssHooks[a];if(r===t)return u&&"get"in u&&(s=u.get(e,!1,i))!==t?s:f[n];o=typeof r,o==="string"&&(s=zt.exec(r))&&(r=(s[1]+1)*s[2]+parseFloat(v.css(e,n)),o="number");if(r==null||o==="number"&&isNaN(r))return;o==="number"&&!v.cssNumber[a]&&(r+="px");if(!u||!("set"in u)||(r=u.set(e,r,i))!==t)try{f[n]=r}catch(l){}},css:function(e,n,r,i){var s,o,u,a=v.camelCase(n);return n=v.cssProps[a]||(v.cssProps[a]=Qt(e.style,a)),u=v.cssHooks[n]||v.cssHooks[a],u&&"get"in u&&(s=u.get(e,!0,i)),s===t&&(s=Dt(e,n)),s==="normal"&&n in Vt&&(s=Vt[n]),r||i!==t?(o=parseFloat(s),r||v.isNumeric(o)?o||0:s):s},swap:function(e,t,n){var r,i,s={};for(i in t)s[i]=e.style[i],e.style[i]=t[i];r=n.call(e);for(i in t)e.style[i]=s[i];return r}}),e.getComputedStyle?Dt=function(t,n){var r,i,s,o,u=e.getComputedStyle(t,null),a=t.style;return u&&(r=u.getPropertyValue(n)||u[n],r===""&&!v.contains(t.ownerDocument,t)&&(r=v.style(t,n)),Ut.test(r)&&qt.test(n)&&(i=a.width,s=a.minWidth,o=a.maxWidth,a.minWidth=a.maxWidth=a.width=r,r=u.width,a.width=i,a.minWidth=s,a.maxWidth=o)),r}:i.documentElement.currentStyle&&(Dt=function(e,t){var n,r,i=e.currentStyle&&e.currentStyle[t],s=e.style;return i==null&&s&&s[t]&&(i=s[t]),Ut.test(i)&&!Ft.test(t)&&(n=s.left,r=e.runtimeStyle&&e.runtimeStyle.left,r&&(e.runtimeStyle.left=e.currentStyle.left),s.left=t==="fontSize"?"1em":i,i=s.pixelLeft+"px",s.left=n,r&&(e.runtimeStyle.left=r)),i===""?"auto":i}),v.each(["height","width"],function(e,t){v.cssHooks[t]={get:function(e,n,r){if(n)return e.offsetWidth===0&&It.test(Dt(e,"display"))?v.swap(e,Xt,function(){return tn(e,t,r)}):tn(e,t,r)},set:function(e,n,r){return Zt(e,n,r?en(e,t,r,v.support.boxSizing&&v.css(e,"boxSizing")==="border-box"):0)}}}),v.support.opacity||(v.cssHooks.opacity={get:function(e,t){return jt.test((t&&e.currentStyle?e.currentStyle.filter:e.style.filter)||"")?.01*parseFloat(RegExp.$1)+"":t?"1":""},set:function(e,t){var n=e.style,r=e.currentStyle,i=v.isNumeric(t)?"alpha(opacity="+t*100+")":"",s=r&&r.filter||n.filter||"";n.zoom=1;if(t>=1&&v.trim(s.replace(Bt,""))===""&&n.removeAttribute){n.removeAttribute("filter");if(r&&!r.filter)return}n.filter=Bt.test(s)?s.replace(Bt,i):s+" "+i}}),v(function(){v.support.reliableMarginRight||(v.cssHooks.marginRight={get:function(e,t){return v.swap(e,{display:"inline-block"},function(){if(t)return Dt(e,"marginRight")})}}),!v.support.pixelPosition&&v.fn.position&&v.each(["top","left"],function(e,t){v.cssHooks[t]={get:function(e,n){if(n){var r=Dt(e,t);return Ut.test(r)?v(e).position()[t]+"px":r}}}})}),v.expr&&v.expr.filters&&(v.expr.filters.hidden=function(e){return e.offsetWidth===0&&e.offsetHeight===0||!v.support.reliableHiddenOffsets&&(e.style&&e.style.display||Dt(e,"display"))==="none"},v.expr.filters.visible=function(e){return!v.expr.filters.hidden(e)}),v.each({margin:"",padding:"",border:"Width"},function(e,t){v.cssHooks[e+t]={expand:function(n){var r,i=typeof n=="string"?n.split(" "):[n],s={};for(r=0;r<4;r++)s[e+$t[r]+t]=i[r]||i[r-2]||i[0];return s}},qt.test(e)||(v.cssHooks[e+t].set=Zt)});var rn=/%20/g,sn=/\[\]$/,on=/\r?\n/g,un=/^(?:color|date|datetime|datetime-local|email|hidden|month|number|password|range|search|tel|text|time|url|week)$/i,an=/^(?:select|textarea)/i;v.fn.extend({serialize:function(){return v.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?v.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&&(this.checked||an.test(this.nodeName)||un.test(this.type))}).map(function(e,t){var n=v(this).val();return n==null?null:v.isArray(n)?v.map(n,function(e,n){return{name:t.name,value:e.replace(on,"\r\n")}}):{name:t.name,value:n.replace(on,"\r\n")}}).get()}}),v.param=function(e,n){var r,i=[],s=function(e,t){t=v.isFunction(t)?t():t==null?"":t,i[i.length]=encodeURIComponent(e)+"="+encodeURIComponent(t)};n===t&&(n=v.ajaxSettings&&v.ajaxSettings.traditional);if(v.isArray(e)||e.jquery&&!v.isPlainObject(e))v.each(e,function(){s(this.name,this.value)});else for(r in e)fn(r,e[r],n,s);return i.join("&").replace(rn,"+")};var ln,cn,hn=/#.*$/,pn=/^(.*?):[ \t]*([^\r\n]*)\r?$/mg,dn=/^(?:about|app|app\-storage|.+\-extension|file|res|widget):$/,vn=/^(?:GET|HEAD)$/,mn=/^\/\//,gn=/\?/,yn=/)<[^<]*)*<\/script>/gi,bn=/([?&])_=[^&]*/,wn=/^([\w\+\.\-]+:)(?:\/\/([^\/?#:]*)(?::(\d+)|)|)/,En=v.fn.load,Sn={},xn={},Tn=["*/"]+["*"];try{cn=s.href}catch(Nn){cn=i.createElement("a"),cn.href="",cn=cn.href}ln=wn.exec(cn.toLowerCase())||[],v.fn.load=function(e,n,r){if(typeof e!="string"&&En)return En.apply(this,arguments);if(!this.length)return this;var i,s,o,u=this,a=e.indexOf(" ");return a>=0&&(i=e.slice(a,e.length),e=e.slice(0,a)),v.isFunction(n)?(r=n,n=t):n&&typeof n=="object"&&(s="POST"),v.ajax({url:e,type:s,dataType:"html",data:n,complete:function(e,t){r&&u.each(r,o||[e.responseText,t,e])}}).done(function(e){o=arguments,u.html(i?v("
").append(e.replace(yn,"")).find(i):e)}),this},v.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "),function(e,t){v.fn[t]=function(e){return this.on(t,e)}}),v.each(["get","post"],function(e,n){v[n]=function(e,r,i,s){return v.isFunction(r)&&(s=s||i,i=r,r=t),v.ajax({type:n,url:e,data:r,success:i,dataType:s})}}),v.extend({getScript:function(e,n){return v.get(e,t,n,"script")},getJSON:function(e,t,n){return v.get(e,t,n,"json")},ajaxSetup:function(e,t){return t?Ln(e,v.ajaxSettings):(t=e,e=v.ajaxSettings),Ln(e,t),e},ajaxSettings:{url:cn,isLocal:dn.test(ln[1]),global:!0,type:"GET",contentType:"application/x-www-form-urlencoded; charset=UTF-8",processData:!0,async:!0,accepts:{xml:"application/xml, text/xml",html:"text/html",text:"text/plain",json:"application/json, text/javascript","*":Tn},contents:{xml:/xml/,html:/html/,json:/json/},responseFields:{xml:"responseXML",text:"responseText"},converters:{"* text":e.String,"text html":!0,"text json":v.parseJSON,"text xml":v.parseXML},flatOptions:{context:!0,url:!0}},ajaxPrefilter:Cn(Sn),ajaxTransport:Cn(xn),ajax:function(e,n){function T(e,n,s,a){var l,y,b,w,S,T=n;if(E===2)return;E=2,u&&clearTimeout(u),o=t,i=a||"",x.readyState=e>0?4:0,s&&(w=An(c,x,s));if(e>=200&&e<300||e===304)c.ifModified&&(S=x.getResponseHeader("Last-Modified"),S&&(v.lastModified[r]=S),S=x.getResponseHeader("Etag"),S&&(v.etag[r]=S)),e===304?(T="notmodified",l=!0):(l=On(c,w),T=l.state,y=l.data,b=l.error,l=!b);else{b=T;if(!T||e)T="error",e<0&&(e=0)}x.status=e,x.statusText=(n||T)+"",l?d.resolveWith(h,[y,T,x]):d.rejectWith(h,[x,T,b]),x.statusCode(g),g=t,f&&p.trigger("ajax"+(l?"Success":"Error"),[x,c,l?y:b]),m.fireWith(h,[x,T]),f&&(p.trigger("ajaxComplete",[x,c]),--v.active||v.event.trigger("ajaxStop"))}typeof e=="object"&&(n=e,e=t),n=n||{};var r,i,s,o,u,a,f,l,c=v.ajaxSetup({},n),h=c.context||c,p=h!==c&&(h.nodeType||h instanceof v)?v(h):v.event,d=v.Deferred(),m=v.Callbacks("once memory"),g=c.statusCode||{},b={},w={},E=0,S="canceled",x={readyState:0,setRequestHeader:function(e,t){if(!E){var n=e.toLowerCase();e=w[n]=w[n]||e,b[e]=t}return this},getAllResponseHeaders:function(){return E===2?i:null},getResponseHeader:function(e){var n;if(E===2){if(!s){s={};while(n=pn.exec(i))s[n[1].toLowerCase()]=n[2]}n=s[e.toLowerCase()]}return n===t?null:n},overrideMimeType:function(e){return E||(c.mimeType=e),this},abort:function(e){return e=e||S,o&&o.abort(e),T(0,e),this}};d.promise(x),x.success=x.done,x.error=x.fail,x.complete=m.add,x.statusCode=function(e){if(e){var t;if(E<2)for(t in e)g[t]=[g[t],e[t]];else t=e[x.status],x.always(t)}return this},c.url=((e||c.url)+"").replace(hn,"").replace(mn,ln[1]+"//"),c.dataTypes=v.trim(c.dataType||"*").toLowerCase().split(y),c.crossDomain==null&&(a=wn.exec(c.url.toLowerCase()),c.crossDomain=!(!a||a[1]===ln[1]&&a[2]===ln[2]&&(a[3]||(a[1]==="http:"?80:443))==(ln[3]||(ln[1]==="http:"?80:443)))),c.data&&c.processData&&typeof c.data!="string"&&(c.data=v.param(c.data,c.traditional)),kn(Sn,c,n,x);if(E===2)return x;f=c.global,c.type=c.type.toUpperCase(),c.hasContent=!vn.test(c.type),f&&v.active++===0&&v.event.trigger("ajaxStart");if(!c.hasContent){c.data&&(c.url+=(gn.test(c.url)?"&":"?")+c.data,delete c.data),r=c.url;if(c.cache===!1){var N=v.now(),C=c.url.replace(bn,"$1_="+N);c.url=C+(C===c.url?(gn.test(c.url)?"&":"?")+"_="+N:"")}}(c.data&&c.hasContent&&c.contentType!==!1||n.contentType)&&x.setRequestHeader("Content-Type",c.contentType),c.ifModified&&(r=r||c.url,v.lastModified[r]&&x.setRequestHeader("If-Modified-Since",v.lastModified[r]),v.etag[r]&&x.setRequestHeader("If-None-Match",v.etag[r])),x.setRequestHeader("Accept",c.dataTypes[0]&&c.accepts[c.dataTypes[0]]?c.accepts[c.dataTypes[0]]+(c.dataTypes[0]!=="*"?", "+Tn+"; q=0.01":""):c.accepts["*"]);for(l in c.headers)x.setRequestHeader(l,c.headers[l]);if(!c.beforeSend||c.beforeSend.call(h,x,c)!==!1&&E!==2){S="abort";for(l in{success:1,error:1,complete:1})x[l](c[l]);o=kn(xn,c,n,x);if(!o)T(-1,"No Transport");else{x.readyState=1,f&&p.trigger("ajaxSend",[x,c]),c.async&&c.timeout>0&&(u=setTimeout(function(){x.abort("timeout")},c.timeout));try{E=1,o.send(b,T)}catch(k){if(!(E<2))throw k;T(-1,k)}}return x}return x.abort()},active:0,lastModified:{},etag:{}});var Mn=[],_n=/\?/,Dn=/(=)\?(?=&|$)|\?\?/,Pn=v.now();v.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=Mn.pop()||v.expando+"_"+Pn++;return this[e]=!0,e}}),v.ajaxPrefilter("json jsonp",function(n,r,i){var s,o,u,a=n.data,f=n.url,l=n.jsonp!==!1,c=l&&Dn.test(f),h=l&&!c&&typeof a=="string"&&!(n.contentType||"").indexOf("application/x-www-form-urlencoded")&&Dn.test(a);if(n.dataTypes[0]==="jsonp"||c||h)return s=n.jsonpCallback=v.isFunction(n.jsonpCallback)?n.jsonpCallback():n.jsonpCallback,o=e[s],c?n.url=f.replace(Dn,"$1"+s):h?n.data=a.replace(Dn,"$1"+s):l&&(n.url+=(_n.test(f)?"&":"?")+n.jsonp+"="+s),n.converters["script json"]=function(){return u||v.error(s+" was not called"),u[0]},n.dataTypes[0]="json",e[s]=function(){u=arguments},i.always(function(){e[s]=o,n[s]&&(n.jsonpCallback=r.jsonpCallback,Mn.push(s)),u&&v.isFunction(o)&&o(u[0]),u=o=t}),"script"}),v.ajaxSetup({accepts:{script:"text/javascript, application/javascript, application/ecmascript, application/x-ecmascript"},contents:{script:/javascript|ecmascript/},converters:{"text script":function(e){return v.globalEval(e),e}}}),v.ajaxPrefilter("script",function(e){e.cache===t&&(e.cache=!1),e.crossDomain&&(e.type="GET",e.global=!1)}),v.ajaxTransport("script",function(e){if(e.crossDomain){var n,r=i.head||i.getElementsByTagName("head")[0]||i.documentElement;return{send:function(s,o){n=i.createElement("script"),n.async="async",e.scriptCharset&&(n.charset=e.scriptCharset),n.src=e.url,n.onload=n.onreadystatechange=function(e,i){if(i||!n.readyState||/loaded|complete/.test(n.readyState))n.onload=n.onreadystatechange=null,r&&n.parentNode&&r.removeChild(n),n=t,i||o(200,"success")},r.insertBefore(n,r.firstChild)},abort:function(){n&&n.onload(0,1)}}}});var Hn,Bn=e.ActiveXObject?function(){for(var e in Hn)Hn[e](0,1)}:!1,jn=0;v.ajaxSettings.xhr=e.ActiveXObject?function(){return!this.isLocal&&Fn()||In()}:Fn,function(e){v.extend(v.support,{ajax:!!e,cors:!!e&&"withCredentials"in e})}(v.ajaxSettings.xhr()),v.support.ajax&&v.ajaxTransport(function(n){if(!n.crossDomain||v.support.cors){var r;return{send:function(i,s){var o,u,a=n.xhr();n.username?a.open(n.type,n.url,n.async,n.username,n.password):a.open(n.type,n.url,n.async);if(n.xhrFields)for(u in n.xhrFields)a[u]=n.xhrFields[u];n.mimeType&&a.overrideMimeType&&a.overrideMimeType(n.mimeType),!n.crossDomain&&!i["X-Requested-With"]&&(i["X-Requested-With"]="XMLHttpRequest");try{for(u in i)a.setRequestHeader(u,i[u])}catch(f){}a.send(n.hasContent&&n.data||null),r=function(e,i){var u,f,l,c,h;try{if(r&&(i||a.readyState===4)){r=t,o&&(a.onreadystatechange=v.noop,Bn&&delete Hn[o]);if(i)a.readyState!==4&&a.abort();else{u=a.status,l=a.getAllResponseHeaders(),c={},h=a.responseXML,h&&h.documentElement&&(c.xml=h);try{c.text=a.responseText}catch(p){}try{f=a.statusText}catch(p){f=""}!u&&n.isLocal&&!n.crossDomain?u=c.text?200:404:u===1223&&(u=204)}}}catch(d){i||s(-1,d)}c&&s(u,f,c,l)},n.async?a.readyState===4?setTimeout(r,0):(o=++jn,Bn&&(Hn||(Hn={},v(e).unload(Bn)),Hn[o]=r),a.onreadystatechange=r):r()},abort:function(){r&&r(0,1)}}}});var qn,Rn,Un=/^(?:toggle|show|hide)$/,zn=new RegExp("^(?:([-+])=|)("+m+")([a-z%]*)$","i"),Wn=/queueHooks$/,Xn=[Gn],Vn={"*":[function(e,t){var n,r,i=this.createTween(e,t),s=zn.exec(t),o=i.cur(),u=+o||0,a=1,f=20;if(s){n=+s[2],r=s[3]||(v.cssNumber[e]?"":"px");if(r!=="px"&&u){u=v.css(i.elem,e,!0)||n||1;do a=a||".5",u/=a,v.style(i.elem,e,u+r);while(a!==(a=i.cur()/o)&&a!==1&&--f)}i.unit=r,i.start=u,i.end=s[1]?u+(s[1]+1)*n:n}return i}]};v.Animation=v.extend(Kn,{tweener:function(e,t){v.isFunction(e)?(t=e,e=["*"]):e=e.split(" ");var n,r=0,i=e.length;for(;r-1,f={},l={},c,h;a?(l=i.position(),c=l.top,h=l.left):(c=parseFloat(o)||0,h=parseFloat(u)||0),v.isFunction(t)&&(t=t.call(e,n,s)),t.top!=null&&(f.top=t.top-s.top+c),t.left!=null&&(f.left=t.left-s.left+h),"using"in t?t.using.call(e,f):i.css(f)}},v.fn.extend({position:function(){if(!this[0])return;var e=this[0],t=this.offsetParent(),n=this.offset(),r=er.test(t[0].nodeName)?{top:0,left:0}:t.offset();return n.top-=parseFloat(v.css(e,"marginTop"))||0,n.left-=parseFloat(v.css(e,"marginLeft"))||0,r.top+=parseFloat(v.css(t[0],"borderTopWidth"))||0,r.left+=parseFloat(v.css(t[0],"borderLeftWidth"))||0,{top:n.top-r.top,left:n.left-r.left}},offsetParent:function(){return this.map(function(){var e=this.offsetParent||i.body;while(e&&!er.test(e.nodeName)&&v.css(e,"position")==="static")e=e.offsetParent;return e||i.body})}}),v.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(e,n){var r=/Y/.test(n);v.fn[e]=function(i){return v.access(this,function(e,i,s){var o=tr(e);if(s===t)return o?n in o?o[n]:o.document.documentElement[i]:e[i];o?o.scrollTo(r?v(o).scrollLeft():s,r?s:v(o).scrollTop()):e[i]=s},e,i,arguments.length,null)}}),v.each({Height:"height",Width:"width"},function(e,n){v.each({padding:"inner"+e,content:n,"":"outer"+e},function(r,i){v.fn[i]=function(i,s){var o=arguments.length&&(r||typeof i!="boolean"),u=r||(i===!0||s===!0?"margin":"border");return v.access(this,function(n,r,i){var s;return v.isWindow(n)?n.document.documentElement["client"+e]:n.nodeType===9?(s=n.documentElement,Math.max(n.body["scroll"+e],s["scroll"+e],n.body["offset"+e],s["offset"+e],s["client"+e])):i===t?v.css(n,r,i,u):v.style(n,r,i,u)},n,o?i:t,o,null)}})}),e.jQuery=e.$=v,typeof define=="function"&&define.amd&&define.amd.jQuery&&define("jquery",[],function(){return v})})(window); \ No newline at end of file diff -r 85f290e474e2 build/_static/minus.png Binary file build/_static/minus.png has changed diff -r 85f290e474e2 build/_static/nature.css --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_static/nature.css Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,245 @@ +/* + * nature.css_t + * ~~~~~~~~~~~~ + * + * Sphinx stylesheet -- nature theme. + * + * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: Arial, sans-serif; + font-size: 100%; + background-color: #111; + color: #555; + margin: 0; + padding: 0; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +hr { + border: 1px solid #B1B4B6; +} + +div.document { + background-color: #eee; +} + +div.body { + background-color: #ffffff; + color: #3E4349; + padding: 0 30px 30px 30px; + font-size: 0.9em; +} + +div.footer { + color: #555; + width: 100%; + padding: 13px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #444; + text-decoration: underline; +} + +div.related { + background-color: #6BA81E; + line-height: 32px; + color: #fff; + text-shadow: 0px 1px 0 #444; + font-size: 0.9em; +} + +div.related a { + color: #E2F3CC; +} + +div.sphinxsidebar { + font-size: 0.75em; + line-height: 1.5em; +} + +div.sphinxsidebarwrapper{ + padding: 20px 0; +} + +div.sphinxsidebar h3, +div.sphinxsidebar h4 { + font-family: Arial, sans-serif; + color: #222; + font-size: 1.2em; + font-weight: normal; + margin: 0; + padding: 5px 10px; + background-color: #ddd; + text-shadow: 1px 1px 0 white +} + +div.sphinxsidebar h4{ + font-size: 1.1em; +} + +div.sphinxsidebar h3 a { + color: #444; +} + + +div.sphinxsidebar p { + color: #888; + padding: 5px 20px; +} + +div.sphinxsidebar p.topless { +} + +div.sphinxsidebar ul { + margin: 10px 20px; + padding: 0; + color: #000; +} + +div.sphinxsidebar a { + color: #444; +} + +div.sphinxsidebar input { + border: 1px solid #ccc; + font-family: sans-serif; + font-size: 1em; +} + +div.sphinxsidebar input[type=text]{ + margin-left: 20px; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: #005B81; + text-decoration: none; +} + +a:hover { + color: #E32E00; + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: Arial, sans-serif; + background-color: #BED4EB; + font-weight: normal; + color: #212224; + margin: 30px 0px 10px 0px; + padding: 5px 0 5px 10px; + text-shadow: 0px 1px 0 white +} + +div.body h1 { border-top: 20px solid white; margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 150%; background-color: #C8D5E3; } +div.body h3 { font-size: 120%; background-color: #D8DEE3; } +div.body h4 { font-size: 110%; background-color: #D8DEE3; } +div.body h5 { font-size: 100%; background-color: #D8DEE3; } +div.body h6 { font-size: 100%; background-color: #D8DEE3; } + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + line-height: 1.5em; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.highlight{ + background-color: white; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + padding: 10px; + background-color: White; + color: #222; + line-height: 1.2em; + border: 1px solid #C6C9CB; + font-size: 1.1em; + margin: 1.5em 0 1.5em 0; + -webkit-box-shadow: 1px 1px 1px #d8d8d8; + -moz-box-shadow: 1px 1px 1px #d8d8d8; +} + +tt { + background-color: #ecf0f3; + color: #222; + /* padding: 1px 2px; */ + font-size: 1.1em; + font-family: monospace; +} + +.viewcode-back { + font-family: Arial, sans-serif; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #ac9; + border-bottom: 1px solid #ac9; +} \ No newline at end of file diff -r 85f290e474e2 build/_static/plus.png Binary file build/_static/plus.png has changed diff -r 85f290e474e2 build/_static/pygments.css --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_static/pygments.css Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,62 @@ +.highlight .hll { background-color: #ffffcc } +.highlight { background: #eeffcc; } +.highlight .c { color: #408090; font-style: italic } /* Comment */ +.highlight .err { border: 1px solid #FF0000 } /* Error */ +.highlight .k { color: #007020; font-weight: bold } /* Keyword */ +.highlight .o { color: #666666 } /* Operator */ +.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */ +.highlight .cp { color: #007020 } /* Comment.Preproc */ +.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */ +.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ +.highlight .gd { color: #A00000 } /* Generic.Deleted */ +.highlight .ge { font-style: italic } /* Generic.Emph */ +.highlight .gr { color: #FF0000 } /* Generic.Error */ +.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ +.highlight .gi { color: #00A000 } /* Generic.Inserted */ +.highlight .go { color: #333333 } /* Generic.Output */ +.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ +.highlight .gs { font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ +.highlight .gt { color: #0044DD } /* Generic.Traceback */ +.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ +.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ +.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ +.highlight .kp { color: #007020 } /* Keyword.Pseudo */ +.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ +.highlight .kt { color: #902000 } /* Keyword.Type */ +.highlight .m { color: #208050 } /* Literal.Number */ +.highlight .s { color: #4070a0 } /* Literal.String */ +.highlight .na { color: #4070a0 } /* Name.Attribute */ +.highlight .nb { color: #007020 } /* Name.Builtin */ +.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ +.highlight .no { color: #60add5 } /* Name.Constant */ +.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ +.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ +.highlight .ne { color: #007020 } /* Name.Exception */ +.highlight .nf { color: #06287e } /* Name.Function */ +.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ +.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ +.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ +.highlight .nv { color: #bb60d5 } /* Name.Variable */ +.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ +.highlight .w { color: #bbbbbb } /* Text.Whitespace */ +.highlight .mf { color: #208050 } /* Literal.Number.Float */ +.highlight .mh { color: #208050 } /* Literal.Number.Hex */ +.highlight .mi { color: #208050 } /* Literal.Number.Integer */ +.highlight .mo { color: #208050 } /* Literal.Number.Oct */ +.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ +.highlight .sc { color: #4070a0 } /* Literal.String.Char */ +.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ +.highlight .s2 { color: #4070a0 } /* Literal.String.Double */ +.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ +.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ +.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ +.highlight .sx { color: #c65d09 } /* Literal.String.Other */ +.highlight .sr { color: #235388 } /* Literal.String.Regex */ +.highlight .s1 { color: #4070a0 } /* Literal.String.Single */ +.highlight .ss { color: #517918 } /* Literal.String.Symbol */ +.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ +.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ +.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ +.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ +.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */ \ No newline at end of file diff -r 85f290e474e2 build/_static/searchtools.js --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/_static/searchtools.js Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,622 @@ +/* + * searchtools.js_t + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilties for the full-text search. + * + * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + + +/** + * Porter Stemmer + */ +var Stemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + + + +/** + * Simple result scoring code. + */ +var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [filename, title, anchor, descr, score] + // and returns the new score. + /* + score: function(result) { + return result[4]; + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: {0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5}, // used to be unimportantResults + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + // query found in terms + term: 5 +}; + + +/** + * Search Module + */ +var Search = { + + _index : null, + _queued_query : null, + _pulse_status : -1, + + init : function() { + var params = $.getQueryParameters(); + if (params.q) { + var query = params.q[0]; + $('input[name="q"]')[0].value = query; + this.performSearch(query); + } + }, + + loadIndex : function(url) { + $.ajax({type: "GET", url: url, data: null, + dataType: "script", cache: true, + complete: function(jqxhr, textstatus) { + if (textstatus != "success") { + document.getElementById("searchindexloader").src = url; + } + }}); + }, + + setIndex : function(index) { + var q; + this._index = index; + if ((q = this._queued_query) !== null) { + this._queued_query = null; + Search.query(q); + } + }, + + hasIndex : function() { + return this._index !== null; + }, + + deferQuery : function(query) { + this._queued_query = query; + }, + + stopPulse : function() { + this._pulse_status = 0; + }, + + startPulse : function() { + if (this._pulse_status >= 0) + return; + function pulse() { + var i; + Search._pulse_status = (Search._pulse_status + 1) % 4; + var dotString = ''; + for (i = 0; i < Search._pulse_status; i++) + dotString += '.'; + Search.dots.text(dotString); + if (Search._pulse_status > -1) + window.setTimeout(pulse, 500); + } + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch : function(query) { + // create the required interface elements + this.out = $('#search-results'); + this.title = $('

' + _('Searching') + '

').appendTo(this.out); + this.dots = $('').appendTo(this.title); + this.status = $('

').appendTo(this.out); + this.output = $('
'); + } + // Prettify the comment rating. + comment.pretty_rating = comment.rating + ' point' + + (comment.rating == 1 ? '' : 's'); + // Make a class (for displaying not yet moderated comments differently) + comment.css_class = comment.displayed ? '' : ' moderate'; + // Create a div for this comment. + var context = $.extend({}, opts, comment); + var div = $(renderTemplate(commentTemplate, context)); + + // If the user has voted on this comment, highlight the correct arrow. + if (comment.vote) { + var direction = (comment.vote == 1) ? 'u' : 'd'; + div.find('#' + direction + 'v' + comment.id).hide(); + div.find('#' + direction + 'u' + comment.id).show(); + } + + if (opts.moderator || comment.text != '[deleted]') { + div.find('a.reply').show(); + if (comment.proposal_diff) + div.find('#sp' + comment.id).show(); + if (opts.moderator && !comment.displayed) + div.find('#cm' + comment.id).show(); + if (opts.moderator || (opts.username == comment.username)) + div.find('#dc' + comment.id).show(); + } + return div; + } + + /** + * A simple template renderer. Placeholders such as <%id%> are replaced + * by context['id'] with items being escaped. Placeholders such as <#id#> + * are not escaped. + */ + function renderTemplate(template, context) { + var esc = $(document.createElement('div')); + + function handle(ph, escape) { + var cur = context; + $.each(ph.split('.'), function() { + cur = cur[this]; + }); + return escape ? esc.text(cur || "").html() : cur; + } + + return template.replace(/<([%#])([\w\.]*)\1>/g, function() { + return handle(arguments[2], arguments[1] == '%' ? true : false); + }); + } + + /** Flash an error message briefly. */ + function showError(message) { + $(document.createElement('div')).attr({'class': 'popup-error'}) + .append($(document.createElement('div')) + .attr({'class': 'error-message'}).text(message)) + .appendTo('body') + .fadeIn("slow") + .delay(2000) + .fadeOut("slow"); + } + + /** Add a link the user uses to open the comments popup. */ + $.fn.comment = function() { + return this.each(function() { + var id = $(this).attr('id').substring(1); + var count = COMMENT_METADATA[id]; + var title = count + ' comment' + (count == 1 ? '' : 's'); + var image = count > 0 ? opts.commentBrightImage : opts.commentImage; + var addcls = count == 0 ? ' nocomment' : ''; + $(this) + .append( + $(document.createElement('a')).attr({ + href: '#', + 'class': 'sphinx-comment-open' + addcls, + id: 'ao' + id + }) + .append($(document.createElement('img')).attr({ + src: image, + alt: 'comment', + title: title + })) + .click(function(event) { + event.preventDefault(); + show($(this).attr('id').substring(2)); + }) + ) + .append( + $(document.createElement('a')).attr({ + href: '#', + 'class': 'sphinx-comment-close hidden', + id: 'ah' + id + }) + .append($(document.createElement('img')).attr({ + src: opts.closeCommentImage, + alt: 'close', + title: 'close' + })) + .click(function(event) { + event.preventDefault(); + hide($(this).attr('id').substring(2)); + }) + ); + }); + }; + + var opts = { + processVoteURL: '/_process_vote', + addCommentURL: '/_add_comment', + getCommentsURL: '/_get_comments', + acceptCommentURL: '/_accept_comment', + deleteCommentURL: '/_delete_comment', + commentImage: '/static/_static/comment.png', + closeCommentImage: '/static/_static/comment-close.png', + loadingImage: '/static/_static/ajax-loader.gif', + commentBrightImage: '/static/_static/comment-bright.png', + upArrow: '/static/_static/up.png', + downArrow: '/static/_static/down.png', + upArrowPressed: '/static/_static/up-pressed.png', + downArrowPressed: '/static/_static/down-pressed.png', + voting: false, + moderator: false + }; + + if (typeof COMMENT_OPTIONS != "undefined") { + opts = jQuery.extend(opts, COMMENT_OPTIONS); + } + + var popupTemplate = '\ +
\ +

\ + Sort by:\ + best rated\ + newest\ + oldest\ +

\ +
Comments
\ +
\ + loading comments...
\ +
    \ +
    \ +

    Add a comment\ + (markup):

    \ +
    \ + reStructured text markup: *emph*, **strong**, \ + ``code``, \ + code blocks: :: and an indented block after blank line
    \ +
    \ + \ +

    \ + \ + Propose a change ▹\ + \ + \ + Propose a change ▿\ + \ +

    \ + \ + \ + \ + \ + \ +
    \ +
    '; + + var commentTemplate = '\ +
    \ +
    \ +
    \ + \ + \ + \ + \ + \ + \ +
    \ +
    \ + \ + \ + \ + \ + \ + \ +
    \ +
    \ +
    \ +

    \ + <%username%>\ + <%pretty_rating%>\ + <%time.delta%>\ +

    \ +
    <#text#>
    \ +

    \ + \ + reply ▿\ + proposal ▹\ + proposal ▿\ + \ + \ +

    \ + 
    \
+<#proposal_diff#>\
+
    \ +
      \ +
      \ +
      \ +
      \ + '; + + var replyTemplate = '\ +
    • \ +
      \ +
      \ + \ + \ + \ + \ + \ + \ +
      \ +
      • '; + + $(document).ready(function() { + init(); + }); +})(jQuery); + +$(document).ready(function() { + // add comment anchors for all paragraphs that are commentable + $('.sphinx-has-comment').comment(); + + // highlight search words in search results + $("div.context").each(function() { + var params = $.getQueryParameters(); + var terms = (params.q) ? params.q[0].split(/\s+/) : []; + var result = $(this); + $.each(terms, function() { + result.highlightText(this.toLowerCase(), 'highlighted'); + }); + }); + + // directly open comment window if requested + var anchor = document.location.hash; + if (anchor.substring(0, 9) == '#comment-') { + $('#ao' + anchor.substring(9)).click(); + document.location.hash = '#s' + anchor.substring(9); + } +}); diff -r 85f290e474e2 build/buildbots.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/buildbots.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,315 @@ + + + + + + + + 19. Continuous Integration — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      19. Continuous Integration

      +

      To assert that there are no regressions in the development and maintenance +branches, Python has a set of dedicated machines (called buildbots or +build slaves) used for continuous integration. They span a number of +hardware/operating system combinations. Furthermore, each machine hosts +several builders, one per active branch: when a new change is pushed +to this branch on the public Mercurial repository, all corresponding builders +will schedule a new build to be run as soon as possible.

      +

      The build steps run by the buildbots are the following:

      +
        +
      • Checkout of the source tree for the changeset which triggered the build
        • +
      • Compiling Python
        • +
      • Running the test suite using strenuous settings
        • +
      • Cleaning up the build tree
        • +
      +

      It is your responsibility, as a core developer, to check the automatic +build results after you push a change to the repository. It is therefore +important that you get acquainted with the way these results are presented, +and how various kinds of failures can be explained and diagnosed.

      +
      +

      19.1. Checking results of automatic builds

      +

      There are two ways of visualizing recent build results:

      +
        +

      • The Web interface for each branch at http://python.org/dev/buildbot/, +where the so-called “waterfall” view presents a vertical rundown of recent +builds for each builder. When interested in one build, you’ll have to +click on it to know which changesets it corresponds to.

        +
        • +

      • The command-line bbreport.py client, which you can get from +http://code.google.com/p/bbreport/. Installing it is trivial: just add +the directory containing bbreport.py to your system path so that +you can run it from any filesystem location. For example, if you want +to display the latest build results on the development (“default”) branch, +type:

        +
        bbreport.py -q 3.x
+
        +
        +
        • +
      +

      Some buildbots are much faster than others. Over time, you will learn which +ones produce the quickest results after a build, and which ones take the +longest time.

      +

      Also, when several changesets are pushed in a quick succession in the same +branch, it often happens that a single build is scheduled for all these +changesets.

      +
      +
      +

      19.2. Stability

      +

      A subset of the buildbots are marked “stable”. They are taken into account +when making a new release. The rule is that all stable builders must be free of +persistent failures when the release is cut. It is absolutely vital +that core developers fix any issue they introduce on the stable buildbots, +as soon as possible.

      +

      This does not mean that other builders’ test results can be taken lightly, +either. Some of them are known for having platform-specific issues that +prevent some tests from succeeding (or even terminating at all), but +introducing additional failures should generally not be an option.

      +
      +
      +

      19.3. Flags-dependent failures

      +

      Sometimes, while you have run the whole test suite before +committing, you may witness unexpected failures on the buildbots. One source +of such discrepancies is if different flags have been passed to the test runner +or to Python itself. To reproduce, make sure you use the same flags as the +buildbots: they can be found out simply by clicking the stdio link for +the failing build’s tests. For example:

      +
      ./python.exe -Wd -E -bb  ./Lib/test/regrtest.py -uall -rwW
+
      +
      +
      +

      Note

      +

      Running Lib/test/regrtest.py is exactly equivalent to running +-m test.

      +
      +
      +
      +

      19.4. Ordering-dependent failures

      +

      Sometimes even the failure is subtler, as it relies on the order in which +the tests are run. The buildbots randomize test order (by using the -r +option to the test runner) to maximize the probability that potential +interferences between library modules are exercised; the downside is that it +can make for seemingly sporadic failures.

      +

      The --randseed option makes it easy to reproduce the exact randomization +used in a given build. Again, open the stdio link for the failing test +run, and check the beginning of the test output proper.

      +

      Let’s assume, for the sake of example, that the output starts with:

      +
      ./python -Wd -E -bb Lib/test/regrtest.py -uall -rwW
+== CPython 3.3a0 (default:22ae2b002865, Mar 30 2011, 13:58:40) [GCC 4.4.5]
+==   Linux-2.6.36-gentoo-r5-x86_64-AMD_Athlon-tm-_64_X2_Dual_Core_Processor_4400+-with-gentoo-1.12.14 little-endian
+==   /home/buildbot/buildarea/3.x.ochtman-gentoo-amd64/build/build/test_python_29628
+Testing with flags: sys.flags(debug=0, inspect=0, interactive=0, optimize=0, dont_write_bytecode=0, no_user_site=0, no_site=0, ignore_environment=1, verbose=0, bytes_warning=2, quiet=0)
+Using random seed 2613169
+[  1/353] test_augassign
+[  2/353] test_functools
+
      +
      +

      You can reproduce the exact same order using:

      +
      ./python -Wd -E -bb -m test -uall -rwW --randseed 2613169
+
      +
      +

      It will run the following sequence (trimmed for brevity):

      +
      [  1/353] test_augassign
+[  2/353] test_functools
+[  3/353] test_bool
+[  4/353] test_contains
+[  5/353] test_compileall
+[  6/353] test_unicode
+
      +
      +

      If this is enough to reproduce the failure on your setup, you can then +bisect the test sequence to look for the specific interference causing the +failure. Copy and paste the test sequence in a text file, then use the +--fromfile (or -f) option of the test runner to run the exact +sequence recorded in that text file:

      +
      ./python -Wd -E -bb -m test -uall -rwW --fromfile mytestsequence.txt
+
      +
      +

      In the example sequence above, if test_unicode had failed, you would +first test the following sequence:

      +
      [  1/353] test_augassign
+[  2/353] test_functools
+[  3/353] test_bool
+[  6/353] test_unicode
+
      +
      +

      And, if it succeeds, the following one instead (which, hopefully, shall +fail):

      +
      [  4/353] test_contains
+[  5/353] test_compileall
+[  6/353] test_unicode
+
      +
      +

      Then, recursively, narrow down the search until you get a single pair of +tests which triggers the failure. It is very rare that such an interference +involves more than two tests. If this is the case, we can only wish you +good luck!

      +
      +

      Note

      +

      You cannot use the -j option (for parallel testing) when diagnosing +ordering-dependent failures. Using -j isolates each test in a +pristine subprocess and, therefore, prevents you from reproducing any +interference between tests.

      +
      +
      +
      +

      19.5. Transient failures

      +

      While we try to make the test suite as reliable as possible, some tests do +not reach a perfect level of reproducibility. Some of them will sometimes +display spurious failures, depending on various conditions. Here are common +offenders:

      +
        +
      • Network-related tests, such as test_poplib, test_urllibnet, etc. +Their failures can stem from adverse network conditions, or imperfect +thread synchronization in the test code, which often has to run a +server in a separate thread.
        • +
      • Tests dealing with delicate issues such as inter-thread or inter-process +synchronization, or Unix signals: test_multiprocessing, +test_threading, test_subprocess, test_threadsignals.
        • +
      +

      When you think a failure might be transient, it is recommended you confirm by +waiting for the next build. Still, even if the failure does turn out sporadic +and unpredictable, the issue should be reported on the bug tracker; even +better if it can be diagnosed and suppressed by fixing the test’s implementation, +or by making its parameters - such as a timeout - more robust.

      +
      +
      +

      19.6. Custom builders

      +

      When working on a long-lived feature branch, or on a bugfix branch which +enables issue-specific debugging, you will probably want to test your +work on one or several buildbots. Since your work is hosted in a distinct +repository, you can’t trigger builds on the regular builders. Instead, +you have to use one of the custom builders.

      +

      When creating (“forcing”) a build on a custom builder, you have to provide +at least two parameters:

      +
        +
      • The repository path, relative to http://hg.python.org. For example, +sandbox/myfixes if http://hg.python.org/sandbox/myfixes is the +full path to the repository.
        • +
      • The Mercurial id of the changeset you want to build. To make things less +tedious, we suggest you do your changes in a separate named branch: you can +then supply the branch name instead of a specific changeset id.
        • +
      +

      If you are interested in the results of a specific test file only, we +recommend you change (temporarily, of course) the contents of the +buildbottest clause in Makefile.pre.in; or, for Windows builders, +the Tools/buildbot/test.bat and Tools/buildbot/test-amd64.bat +scripts.

      +
      +

      Note

      +

      For security reasons, it is impossible to build repositories from outside +the http://hg.python.org realm.

      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      18. Development Cycle

      +

      Next topic

      +

      20. Adding to the Stdlib

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/clang.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/clang.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,444 @@ + + + + + + + + 28. Dynamic Analysis with Clang — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      28. Dynamic Analysis with Clang

      +

      This document describes how to use Clang to perform analysis on Python and its +libraries. In addition to performing the analysis, the document will cover +downloading, building and installing the the latest Clang/LLVM combination +(which is currently 3.4).

      +

      This document does not cover interpreting the findings. For a discussion of +interpreting results, see Marshall Clow’s Testing libc++ with +-fsanitize=undefined. The +blog posting is a detailed examinations of issues uncovered by Clang in +libc++.

      +
      +

      28.1. What is Clang?

      +

      Clang is the C, C++ and Objective C front-end for the LLVM compiler. The +front-end provides access to LLVM’s optimizer and code generator. The +sanitizers - or checkers - are hooks into the code generation phase to +instrument compiled code so suspicious behavior is flagged.

      +
      +
      +

      28.2. What are Sanitizers?

      +

      Clang sanitizers are runtime checkers used to identify suspicious and undefined +behavior. The checking occurs at runtime with actual runtime parameters so false +positives are kept to a minimum.

      +

      There are a number of sanitizers available, but two that should be used on a +regular basis are the Address Sanitizer (or ASan) and the Undefined Behavior +Sanitizer (or UBSan). ASan is invoked with the compiler option +-fsanitize=address, and UBSan is invoked with -fsanitize=undefined. The +flags are passed through CFLAGS and CXXFLAGS, and sometimes through +CC and CXX (in addition to the compiler).

      +

      A complete list of sanitizers can be found at Controlling Code Generation.

      +
      +

      Note

      +

      Because sanitizers operate at runtime on real program parameters, its +important to provide a complete set of positive and negative self tests.

      +
      +

      Clang and its sanitizers have strengths (and weaknesses). Its just one tool in +the war chest to uncovering bugs and improving code quality. Clang should be +used to compliment other methods, including Code Reviews, Valgrind, Coverity, +etc.

      +
      +
      +

      28.3. Clang/LLVM Setup

      +

      This portion of the document covers downloading, building and installing Clang +and LLVM. There are three components to download and build. They are the LLVM +compiler, the compiler front end and the compiler runtime library.

      +

      In preparation you should create a scratch directory. Also ensure you are using +Python 2 and not Python 3. Python 3 will cause the build to fail.

      +
      +

      28.3.1. Download, Build and Install

      +

      Perform the following to download, build and install the Clang/LLVM 3.4.

      +
      # Download
+wget http://llvm.org/releases/3.4/llvm-3.4.src.tar.gz
+wget http://llvm.org/releases/3.4/clang-3.4.src.tar.gz
+wget http://llvm.org/releases/3.4/compiler-rt-3.4.src.tar.gz
+
+# LLVM
+tar xvf llvm-3.4.src.tar.gz
+cd llvm-3.4/tools
+
+# Clang Front End
+tar xvf ../../clang-3.4.src.tar.gz
+mv clang-3.4 clang
+
+# Compiler RT
+cd ../projects
+tar xvf ../../compiler-rt-3.4.src.tar.gz
+mv compiler-rt-3.4/ compiler-rt
+
+# Build
+cd ..
+./configure --enable-optimized --prefix=/usr/local
+make -j4
+sudo make install
+
      +
      +
      +

      Note

      +

      If you receive an error 'LibraryDependencies.inc' file not found, then +ensure you are utilizing Python 2 and not Python 3. If you encounter the +error after switching to Python 2, then delete everything and start over.

      +
      +

      After make install executes, the compilers will be installed in +/usr/local/bin and the various libraries will be installed in +/usr/local/lib/clang/3.4/lib/linux/:

      +
      $ ls /usr/local/lib/clang/3.4/lib/linux/
+libclang_rt.asan-x86_64.a   libclang_rt.profile-x86_64.a
+libclang_rt.dfsan-x86_64.a  libclang_rt.san-x86_64.a
+libclang_rt.full-x86_64.a   libclang_rt.tsan-x86_64.a
+libclang_rt.lsan-x86_64.a   libclang_rt.ubsan_cxx-x86_64.a
+libclang_rt.msan-x86_64.a   libclang_rt.ubsan-x86_64.a
+
      +
      +

      On Mac OS X, the libraries are installed in +/usr/local/lib/clang/3.3/lib/darwin/:

      +
      $ ls /usr/local/lib/clang/3.3/lib/darwin/
+libclang_rt.10.4.a                    libclang_rt.ios.a
+libclang_rt.asan_osx.a                libclang_rt.osx.a
+libclang_rt.asan_osx_dynamic.dylib    libclang_rt.profile_ios.a
+libclang_rt.cc_kext.a                 libclang_rt.profile_osx.a
+libclang_rt.cc_kext_ios5.a            libclang_rt.ubsan_osx.a
+libclang_rt.eprintf.a
+
      +
      +
      +

      Note

      +

      You should never have to add the libraries to a project. Clang will handle +it for you. If you find you cannot pass the -fsanitize=XXX flag through +make‘s implicit variables (CFLAGS, CXXFLAGS, CC, +CXXFLAGS, LDFLAGS) during configure, then you should modify the +makefile after configuring to ensure the flag is passed through the +compiler.

      +
      +

      The installer does not install all the components needed on occasion. For +example, you might want to run a scan-build or examine the results with +scan-veiw. You can copy the components by hand with:

      +
      sudo mkdir /usr/local/bin/scan-build
+sudo cp -r llvm-3.4/tools/clang/tools/scan-build /usr/local/bin
+sudo mkdir /usr/local/bin/scan-view
+sudo cp -r llvm-3.4/tools/clang/tools/scan-view /usr/local/bin
+
      +
      +
      +

      Note

      +

      Because the installer does not install all the components needed on +occasion, you should not delete the scratch directory until you are sure +things work as expected. If a library is missing, then you should search for +it in the Clang/LLVM build directory.

      +
      +
      +
      +
      +

      28.4. Python Build Setup

      +

      This portion of the document covers invoking Clang and LLVM with the options +required so the sanitizers analyze Python with under its test suite. Two +checkers are used - ASan and UBSan.

      +

      Because the sanitizers are runtime checkers, its best to have as many positive +and negative self tests as possible. You can never have enough self tests.

      +

      The general idea is to compile and link with the sanitizer flags. At link time, +Clang will include the needed runtime libraries. However, you can’t use +CFLAGS and CXXFLAGS to pass the options through the compiler to the +linker because the makefile rules for BUILDPYTHON, _testembed and +_freeze_importlib don’t use the implicit variables.

      +

      As a workaround to the absence of flags to the linker, you can pass the +sanitizer options by way of the compilers - CC and CXX. Passing the +flags though the compiler is used below, but passing them through LDFLAGS is +also reported to work.

      +
      +

      28.4.1. Building Python

      +

      To begin, export the variables of interest with the desired sanitizers. Its OK +to specify both sanitizers:

      +
      # ASan
+export CC="/usr/local/bin/clang -fsanitize=address"
+export CXX="/usr/local/bin/clang++ -fsanitize=address -fno-sanitize=vptr"
+
      +
      +

      Or:

      +
      # UBSan
+export CC="/usr/local/bin/clang -fsanitize=undefined"
+export CXX="/usr/local/bin/clang++ -fsanitize=undefined -fno-sanitize=vptr"
+
      +
      +

      The -fno-sanitize=vptr removes vtable checks that are part of UBSan from C++ +projects due to noise. Its not needed with Python, but you will likely need it +for other C++ projects.

      +

      After exporting CC and CXX, configure as normal:

      +
      $ ./configure
+checking build system type... x86_64-unknown-linux-gnu
+checking host system type... x86_64-unknown-linux-gnu
+checking for --enable-universalsdk... no
+checking for --with-universal-archs... 32-bit
+checking MACHDEP... linux
+checking for --without-gcc... no
+checking for gcc... /usr/local/bin/clang -fsanitize=undefined
+checking whether the C compiler works... yes
+...
+
      +
      +

      Next is a standard make (formatting added for clarity):

      +
      $ make
+/usr/local/bin/clang -fsanitize=undefined -c -Wno-unused-result
+    -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes -I.
+    -IInclude -I./Include -DPy_BUILD_CORE -o Modules/python.o
+    ./Modules/python.c
+/usr/local/bin/clang -fsanitize=undefined -c -Wno-unused-result
+    -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes -I.
+    -IInclude -I./Include -DPy_BUILD_CORE -o Parser/acceler.o
+    Parser/acceler.c
+...
+
      +
      +

      Finally is make test (formatting added for clarity):

      +
      Objects/longobject.c:39:42: runtime error: index -1 out of bounds
+    for type 'PyLongObject [262]'
+Objects/tupleobject.c:188:13: runtime error: member access within
+    misaligned address 0x2b76be018078 for type 'PyGC_Head' (aka
+    'union _gc_head'), which requires 16 byte alignment
+    0x2b76be018078: note: pointer points here
+    00 00 00 00  40 53 5a b6 76 2b 00 00  60 52 5a b6 ...
+                 ^
+...
+
      +
      +

      If you are using the address sanitizer, its important to pipe the output through +asan_symbolize.py to get a good trace. For example, from Issue 20953 during +compile (formatting added for clarity):

      +
      $ make test 2>&1 | asan_symbolize.py
+...
+
+/usr/local/bin/clang -fsanitize=address -Xlinker -export-dynamic
+    -o python Modules/python.o libpython3.3m.a -ldl -lutil
+    /usr/local/ssl/lib/libssl.a /usr/local/ssl/lib/libcrypto.a -lm
+./python -E -S -m sysconfig --generate-posix-vars
+=================================================================
+==24064==ERROR: AddressSanitizer: heap-buffer-overflow on address
+0x619000004020 at pc 0x4ed4b2 bp 0x7fff80fff010 sp 0x7fff80fff008
+READ of size 4 at 0x619000004020 thread T0
+  #0 0x4ed4b1 in PyObject_Free Python-3.3.5/./Objects/obmalloc.c:987
+  #1 0x7a2141 in code_dealloc Python-3.3.5/./Objects/codeobject.c:359
+  #2 0x620c00 in PyImport_ImportFrozenModuleObject
+       Python-3.3.5/./Python/import.c:1098
+  #3 0x620d5c in PyImport_ImportFrozenModule
+       Python-3.3.5/./Python/import.c:1114
+  #4 0x63fd07 in import_init Python-3.3.5/./Python/pythonrun.c:206
+  #5 0x63f636 in _Py_InitializeEx_Private
+       Python-3.3.5/./Python/pythonrun.c:369
+  #6 0x681d77 in Py_Main Python-3.3.5/./Modules/main.c:648
+  #7 0x4e6894 in main Python-3.3.5/././Modules/python.c:62
+  #8 0x2abf9a525eac in __libc_start_main
+       /home/aurel32/eglibc/eglibc-2.13/csu/libc-start.c:244
+  #9 0x4e664c in _start (Python-3.3.5/./python+0x4e664c)
+
+AddressSanitizer can not describe address in more detail (wild
+memory access suspected).
+SUMMARY: AddressSanitizer: heap-buffer-overflow
+  Python-3.3.5/./Objects/obmalloc.c:987 PyObject_Free
+Shadow bytes around the buggy address:
+  0x0c327fff87b0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
+  0x0c327fff87c0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
+  0x0c327fff87d0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
+  0x0c327fff87e0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
+  0x0c327fff87f0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
+=>0x0c327fff8800: fa fa fa fa[fa]fa fa fa fa fa fa fa fa fa fa fa
+  0x0c327fff8810: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
+  0x0c327fff8820: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
+  0x0c327fff8830: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
+  0x0c327fff8840: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
+  0x0c327fff8850: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
+Shadow byte legend (one shadow byte represents 8 application bytes):
+  Addressable:           00
+  Partially addressable: 01 02 03 04 05 06 07
+  Heap left redzone:     fa
+  Heap right redzone:    fb
+  Freed heap region:     fd
+  Stack left redzone:    f1
+  Stack mid redzone:     f2
+  Stack right redzone:   f3
+  Stack partial redzone: f4
+  Stack after return:    f5
+  Stack use after scope: f8
+  Global redzone:        f9
+  Global init order:     f6
+  Poisoned by user:      f7
+  ASan internal:         fe
+==24064==ABORTING
+make: *** [pybuilddir.txt] Error 1
+
      +
      +
      +

      Note

      +

      asan_symbolize.py is supposed to be installed during make install. +If its not installed, then look in the Clang/LLVM build directory for it and +copy it to /usr/local/bin.

      +
      +
      +
      +

      28.4.2. Blacklisting (Ignoring) Findings

      +

      Clang allows you to alter the behavior of sanitizer tools for certain +source-level by providing a special blacklist file at compile-time. The +blacklist is needed because it reports every instance of an issue, even if the +issue is reported 10’s of thousands of time in un-managed library code.

      +

      You specify the blacklist with -fsanitize-blacklist=XXX. For example:

      +
      -fsanitize-blacklist=my_blacklist.txt
+
      +
      +

      my_blacklist.txt would then contain entries such as the following. The entry +will ignore a bug in libc++‘s ios formatting functions:

      +
      fun:_Ios_Fmtflags
+
      +
      +

      As an example with Python 3.4.0, audioop.c will produce a number of +findings:

      +
      ./Modules/audioop.c:422:11: runtime error: left shift of negative value -1
+./Modules/audioop.c:446:19: runtime error: left shift of negative value -1
+./Modules/audioop.c:476:19: runtime error: left shift of negative value -1
+./Modules/audioop.c:504:16: runtime error: left shift of negative value -1
+./Modules/audioop.c:533:22: runtime error: left shift of negative value -128
+./Modules/audioop.c:775:19: runtime error: left shift of negative value -70
+./Modules/audioop.c:831:19: runtime error: left shift of negative value -70
+./Modules/audioop.c:881:19: runtime error: left shift of negative value -1
+./Modules/audioop.c:920:22: runtime error: left shift of negative value -70
+./Modules/audioop.c:967:23: runtime error: left shift of negative value -70
+./Modules/audioop.c:968:23: runtime error: left shift of negative value -70
+...
+
      +
      +

      One of the function of interest is audioop_getsample_impl (flagged at line +422), and the blacklist entry would include:

      +
      fun:audioop_getsample_imp
+
      +
      +

      Or, you could ignore the entire file with:

      +
      src:Modules/audioop.c
+
      +
      +

      Unfortunately, you won’t know what to blacklist until you run the sanitizer.

      +

      The documentation is available at Sanitizer special case list.

      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      27. Coverity Scan

      +

      Next topic

      +

      29. Python Developer FAQ

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/committing.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/committing.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,615 @@ + + + + + + + + 16. Committing and Pushing Changes — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      16. Committing and Pushing Changes

      +
      +

      16.1. Is the change ready for committing?

      +

      Before a change is committed, you must make sure it is ready to enter the +public source tree. Draft commits are prohibited. Therefore, you must +ensure your changes fulfill several mandatory criteria.

      +
      +

      Note

      +

      If you want to share your work-in-progress code on a feature or bugfix, +either publish patches or create a public fork of the repository.

      +
      +
      +

      16.1.1. Does the test suite still pass?

      +

      You must run the whole test suite to ensure that it +passes before pushing any code changes.

      +
      +

      Note

      +

      You really need to run the entire test suite. Running a single test +is not enough as your changes may have unforeseen effects on other tests +or library modules.

      +

      Running the entire test suite doesn’t guarantee that your changes +will pass the continuous integration tests, as those +will exercise more possibilities still (such as different platforms or +build options). But it will at least catch non-build specific, +non-platform specific errors, therefore minimizing the chance for +breakage.

      +
      +
      +
      +

      16.1.2. Patch checklist

      +

      Apart from running the tests, there’s a simple patch checklist that +make patchcheck (or ./python.exe Tools/scripts/patchcheck.py on +Windows) will run through:

      +
        +
      • Are there any whitespace problems in Python files? +(using Tools/scripts/reindent.py)
        • +
      • Are there any whitespace problems in C files?
        • +
      • Are there any whitespace problems in the documentation? +(using Tools/scripts/reindent-rst.py)
        • +
      • Has the documentation been updated?
        • +
      • Has the test suite been updated?
        • +
      • Has Misc/NEWS been updated?
        • +
      • Has Misc/ACKS been updated?
        • +
      • Has configure been regenerated, if necessary?
        • +
      • Has pyconfig.h.in been regenerated, if necessary?
        • +
      +

      Note that the automated patch check can’t actually answer all of these +questions, and even if it could, it still wouldn’t know whether or not +those answers were appropriate. Aside from the whitespace checks, it is just +a memory aid to help with remembering the various elements that can go into +making a complete patch.

      +
      +
      +
      +

      16.2. Commit Style

      +

      Once a change patch is ready and tested, it can be committed to the repository. +We usually prefer to put a whole feature or bugfix into a single commit, but no +more. In particular:

      +
        +
      • Do not fix more than one issue in the same commit (except, of course, if +one code change fixes all of them).
        • +
      • Do not do cosmetic changes to unrelated code in the same commit as some +feature/bugfix.
        • +
      +

      It is of course okay to pile up several commits to one branch and merge them +into another in one merge commit.

      +
      +
      +

      16.3. Handling Others’ Code

      +

      As a core developer you will occasionally want to commit a patch created by +someone else. When doing so you will want to make sure of some things.

      +

      First, make sure the patch is in a good state. Both Lifecycle of a Patch and +Helping Triage Issues +explain what is to be expected of a patch. Typically patches that get cleared by +triagers are good to go except maybe lacking Misc/ACKS and Misc/NEWS +entries.

      +

      Second, make sure the patch does not break backwards-compatibility without a +good reason. This means running the entire test suite to +make sure everything still passes. It also means that if semantics do change +there must be a good reason for the breakage of code the change will cause +(and it will break someone’s code). If you are unsure if the breakage +is worth it, ask on python-dev.

      +

      Third, ensure the patch is attributed correctly by adding the contributor’s +name to Misc/ACKS if they aren’t already there (and didn’t add themselves +in their patch) and by mentioning “Patch by <x>” in the Misc/NEWS entry +and the checkin message. If the patch has been heavily modified then “Initial +patch by <x>” is an appropriate alternate wording.

      +

      If you omit correct attribution in the initial checkin, then update ACKS +and NEWS in a subsequent checkin (don’t worry about trying to fix the +original checkin message in that case).

      +

      Finally, especially for larger patches, check if the submitter of the +patch has a CLA in place (indicated by an asterisk following their username +in the issue tracker). If the asterisk is missing and the patch is +non-trivial, direct them to the electronic Contributor Licensing Agreement +to ensure the PSF has the appropriate authorizations in place to relicense +and redistribute their code.

      +
      +
      +

      16.4. Contributor Licensing Agreements

      +

      It’s unlikely bug fixes will require a Contributor Licensing Agreement +unless they touch a lot of code. For new features, it is preferable to +ask that the contributor submit a signed CLA to the PSF as the associated +comments, docstrings and documentation are far more likely to reach a +copyrightable standard.

      +

      These days, the CLA can be signed electronically through the form linked +above, and this process is strongly preferred to the old mechanism that +involved sending a scanned copy of the signed paper form.

      +

      As discussed on the PSF Contribution page, it is the CLA itself that gives +the PSF the necessary relicensing rights to redistribute contributions under +the Python license stack. This is an additional permission granted above and +beyond the normal permissions provided by the chosen open source license.

      +

      Some developers may object to the relicensing permissions granted to the PSF +by the CLA. They’re entirely within their rights to refuse to sign the CLA +on that basis, but that refusal does mean we can’t accept their patches +for inclusion.

      +
      +
      +

      16.5. NEWS Entries

      +

      Almost all changes made to the code base deserve an entry in Misc/NEWS. +If the change is particularly interesting for end users (e.g. new features, +significant improvements, or backwards-incompatible changes), an entry in +the What's New in Python document (in Doc/whatsnew/) should be added +as well. There are two notable exceptions to this general principle, and they +both relate to changes that already have a NEWS entry, and have not yet +been included in any formal release (including alpha and beta releases). +These exceptions are:

      +
        +
      • If a change is reverted prior to release, then the corresponding entry +is simply removed. Otherwise, a new entry must be added noting that the +change has been reverted (e.g. when a feature is released in an alpha and +then cut prior to the first beta).
        • +
      • If a change is a fix (or other adjustment) to an earlier unreleased change +and the original NEWS entry remains valid, then no additional entry is +needed.
        • +
      +

      New NEWS entries are customarily added at or near the top of their +respective sections, so that entries within a section appear in approximate +order from newest to oldest. However, this is customary and not a +requirement.

      +

      The NEWS file is now read by Sphinx to produce the “Changelog” page; accordingly +it should be valid reStructuredText. The “default role” (single backticks) can +be used to refer to objects in the documentation. Example NEWS entry:

      +
      - Issue #15304: Fix warning message when `os.chdir()` fails inside
+  `test.support.temp_cwd()`.  Patch by Chris Jerdonek.
+
      +
      +

      (In all other .rst files, the single backticks should not be used. They are +allowed here because NEWS is meant to be as readable as possible unprocessed.)

      +

      A nice trick to make Mercurial’s automatic file merge work more smoothly is to +put a new entry after the first or first two entries rather than at the very +top. This way if you commit, pull new changesets and merge, the merge will +succeed automatically.

      +
      +
      +

      16.6. Commit Messages

      +

      Every commit has a commit message to document why a change was made and to +communicate that reason to other core developers. Python core developers have +developed a standard way of formatting commit messages that everyone is +expected to follow.

      +

      Our usual convention mimics that used in the Misc/NEWS file. Actually, +it is common to simply paste the NEWS entry into the commit message. Here +is an example:

      +
      Issue #42: the spam module is now more spammy.
+The spam module sporadically came up short on spam. This change
+raises the amount of spam in the module by making it more spammy.
+Thanks to Monty Python for the patch.
+
      +
      +

      The first line or sentence is meant to be a dense, to-the-point explanation +of what the purpose of the commit is. If this is not enough detail for a commit, +a new paragraph(s) can be added to explain in proper depth what has happened +(detail should be good enough that a core developer reading the commit message +understands the justification for the change). Also, if a non-core developer +contributed to the resolution, it is good practice to credit them.

      +
      +

      16.6.1. Mercurial hooks

      +

      Special hooks have been added to the Mercurial repository to enable notifying +the issue tracker of a commit related to an issue.

      +

      A commit message can mention one or several issues in one of the following +ways:

      +
      #12345
+issue12345
+issue 12345
+bug12345
+bug 12345
+
      +
      +

      where 12345 is the number of the issue. The commit details (including its +changeset, branch and commit message) will then be posted as a message to the +issue’s page in the tracker, for each mentioned issue.

      +

      If “closes” (or “closed”, or “closing”) is prepended, the issue is +automatically closed as “fixed”.

      +
      +
      +
      +
      +

      17. Working with Mercurial

      +

      As a core developer, the ability to push changes to the official Python +repositories means you have to be more careful with your workflow:

      +
        +
      • You should not push new named branches to the main repository. You can +still use them in clones that you use for development of patches; you can +also push these branches to a separate public repository that will be +dedicated to maintenance of the work before the work gets integrated in the +main repository.
        • +
      • You should collapse changesets of a single feature or bugfix before pushing +the result to the main repository. The reason is that we don’t want the +history to be full of intermediate commits recording the private history +of the person working on a patch. If you are using the rebase extension, +consider adding the --collapse option to hg rebase. The collapse +extension is another choice.
        • +
      +

      Because of these constraints, it can be practical to use other approaches +such as mq (Mercurial Queues), in order to maintain patches in a single +local repository and to push them seamlessly when they are ready.

      +

      It can also be useful to keep a pristine clone of the main repository around, +as it allows simple reversion of all local changes (even “committed” ones) if +your local clone gets into a state you aren’t happy with.

      +
      +

      17.1. Minimal Configuration

      +

      To use Mercurial as a committer (both of your and others’ patches), you should +set up some basic options in your configuration file. Under Windows, +TortoiseHg has a graphical settings dialog for most options, meaning you +don’t need to edit the file directly (it is still available in +%USERPROFILE%\Mercurial.ini). Under other platforms, you must edit +~/.hgrc.

      +

      Here are the minimal options you need to activate:

      +
        +

      • your username: this setting defines the name that will be used when you +commit changes. The usual convention is to also include +an e-mail contact address in there:

        +
        [ui]
+username = Your Name <email@example.org>
+
        +
        +
        • +

      • extended diffing: this setting enables an extended diff format +which is more useful than the standard unified diff format as it includes +metadata about file copies, permission bits, and is able to represent +binary files:

        +
        [diff]
+git = on
+
        +
        +
        • +
      +

      Under Windows, you should also enable the eol extension, which will +fix any Windows-specific line endings your text editor might insert when you +create or modify versioned files. The public repository has a hook which +will reject all changesets having the wrong line endings, so enabling this +extension on your local computer is in your best interest.

      +
      +
      +

      17.2. Clones Setup

      +

      There are several possible ways to set up your Mercurial clone(s). If you are +a core developer, you often need to work on the different branches, so the best +approach is to have a separate clone/directory for each active branch. If you +are a contributor, having a single clone might be enough.

      +
      +

      17.2.1. Single Clone Approach

      +

      This approach has the advantage of being simpler because it requires a single +clone/directory, but, on the other hand, it requires you to recompile Python +every time you need to switch branch. For this reason, this approach is not +suggested to core developers, but it’s usually suitable for contributors.

      +

      See Getting the Source Code to find information about cloning and switching branches.

      +
      +
      +

      17.2.2. Multiple Clones Approach

      +

      This approach requires you to keep a separate clone/directory for each active +branch, but, on the other hand, it doesn’t require you to switch branches and +recompile Python, so it saves times while merging and testing a patch on the +different branches. For this reason, this approach is suggested to core +developers.

      +

      The easiest way to do this is by using the share extension, that can be +enabled by adding the following lines to your ~/.hgrc:

      +
      [extensions]
+share =
+
      +
      +

      Once you have cloned the hg.python.org/cpython repository +you can create the other shared clones using:

      +
      $ hg share cpython 2.7  # create a new shared clone
+$ cd 2.7                # enter the directory
+$ hg up 2.7             # switch to the 2.7 branch
+
      +
      +

      You can then repeat the same operation for the other active branches. +This will create different clones/directories that share the same history. +This means that once you commit or pull new changesets in one of the clones, +they will be immediately available in all the other clones (note however that +while you only need to use hg pull once, you still need to use hg up +in each clone to update its working copy).

      +

      If you don’t want to specify ssh://hg@hg.python.org/cpython every time you pull +or push, you should add to the .hg/hgrc files of the clones:

      +
      [paths]
+default = ssh://hg@hg.python.org/cpython
+
      +
      +

      In order to apply a patch, commit, and merge it on all the branches, you can do +as follow:

      +
      $ cd 2.7
+$ hg pull
+$ hg up
+$ hg import --no-c http://bugs.python.org/url/to/the/patch.diff
+$ # review, run tests, run `make patchcheck`
+$ hg ci -m '#12345: fix some issue.'
+$ # switch to 3.4 and port the changeset using `hg graft`
+$ cd ../3.4
+$ hg up
+$ hg graft 2.7
+$ # switch to 3.x, merge, commit, and push everything
+$ cd ../3.x
+$ hg up
+$ hg merge 3.4
+$ hg ci -m '#12345: merge with 3.4.'
+$ hg push
+
      +
      +

      Unless noted otherwise, the rest of the page will assume you are using the +multiple clone approach, and explain in more detail these basic steps.

      +

      For more advanced explanations about null merges, +heads merges, merge conflicts, etc., see the FAQs for core developers.

      +
      +
      +
      +

      17.3. Active branches

      +

      If you do hg branches you will see a list of branches. +default is the in-development branch, and is the only branch that receives +new features. The other branches only receive bug fixes or security fixes. +Depending on what you are committing (feature, bug fix, or security fix), you +should commit to the oldest branch applicable, and then forward-port until the +in-development branch.

      +
      +
      +

      17.4. Merging order

      +

      There are two separate lines of development: one for Python 2 (the 2.x +branches) and one for Python 3 (the 3.x branches and default). +You should never merge between the two major versions (2.x and 3.x) — +only between minor versions (e.g. 3.x->3.y). The merge always happens from +the oldest applicable branch to the newest branch within the same major +Python version.

      +
      +
      +

      17.5. Merging between different branches (within the same major version)

      +

      Assume that Python 3.5 is the current in-development version of Python and that +you have a patch that should also be applied to Python 3.4. To properly port +the patch to both versions of Python, you should first apply the patch to +Python 3.4:

      +
      cd 3.4
+hg import --no-commit patch.diff
+# Compile; run the test suite
+hg ci -m '#12345: fix some issue.'
+
      +
      +

      Then you can switch to the 3.5 clone, merge, run the tests and commit:

      +
      cd ../3.5
+hg merge 3.4
+# Fix any conflicts (e.g. ``hg revert -r default Misc/NEWS``); compile; run the test suite
+hg ci -m '#12345: merge with 3.4.'
+
      +
      +

      If you are not using the share extension, you will need to use +hg pull ../3.4 before being able to merge.

      +
      +

      Note

      +

      Even when porting an already committed patch, you should still check the +test suite runs successfully before committing the patch to another branch. +Subtle differences between two branches sometimes make a patch bogus if +ported without any modifications.

      +
      +
      +
      +

      17.6. Porting changesets between the two major Python versions (2.x and 3.x)

      +

      Assume you just committed something on 2.7, and want to port it to 3.4. +You can use hg graft as follow:

      +
      cd ../3.4
+hg graft 2.7
+
      +
      +

      This will port the latest changeset committed in the 2.7 clone to the 3.4 clone. +hg graft always commits automatically, except in case of conflicts, when +you have to resolve them and run hg graft --continue afterwards. +Instead of the branch name you can also specify a changeset id, and you can +also graft changesets from 3.x to 2.7.

      +

      On older version of Mercurial where hg graft is not available, you can use:

      +
      cd ../3.4
+hg export 2.7 | hg import -
+
      +
      +

      The result will be the same, but in case of conflict this will create .rej +files rather than using Mercurial merge capabilities.

      +

      A third option is to apply manually the patch on 3.4. This is convenient +when there are too many differences with 2.7 or when there is already a +specific patch for 3.4.

      +
      +

      Warning

      +

      Never use hg merge to port changes between 2.x and 3.x (or vice versa).

      +
      +
      +
      +

      17.7. Long-term development of features

      +

      If you want to work on a feature long-term (perhaps you’re implementing a +PEP), you will probably want to publish your work in a dedicated repository. +The following instructions will help you do so on hg.python.org‘s infrastructure without requiring a lot of upload +bandwidth.

      +

      Go to the main repository’s Web page (http://hg.python.org/cpython/); there +you find a button labelled “server-side clone”, which you can click on to +display a Web form. Enter the relative path of the repository you want to +create on the server, for example features/mywork; and press the button. +A new repository gets created on the server with all the changesets of the +original repository (it will seem very fast; this is normal).

      +

      You can now do a local clone of this repository on your disk:

      +
      $ hg clone ssh://hg@hg.python.org/features/mywork
+$ cd mywork
+
      +
      +

      It is recommended that you create a new named branch for your work, so as +to easily track changes. That named branch will exist in your feature +repository, but not in the main repository:

      +
      $ hg branch mywork
+$ hg commit -m "Creating branch mywork"
+$ hg push --new-branch
+
      +
      +

      You can now work on your feature, commit changes as you will, and push them +when desired:

      +
      $ hg push
+
      +
      +

      When you push them, they will land in the public repository at +ssh://hg@hg.python.org/features/mywork (or +http://hg.python.org/features/mywork for the read-only URL). Other +people can clone the public repository and work on the code too.

      +

      When you want to synchronize with CPython’s upstream changes, you can pull +from the main repository, either from its remote URL:

      +
      $ hg pull http://hg.python.org/cpython
+
      +
      +

      or from a local clone that you may have on your disk (which is of course +faster):

      +
      $ hg pull ../cpython
+
      +
      +

      and merge all new changes from branch default to branch mywork:

      +
      $ hg branch
+mywork
+$ hg merge default
+
      +
      +

      Rather than using a clone on python.org (which isn’t particularly useful +for collaboration with folks that don’t already have CPython commit rights), +Bitbucket also maintain an up to date clone of the main cpython +repository that can be used as the basis for a new clone or patch queue.

      +
      +

      17.7.1. Uploading a patch for review

      +

      In this scheme, your work will probably consist of many commits (some of +them merges). If you want to upload a patch for review somewhere, you need +a single aggregate patch. This is where having a dedicated named branch +mywork gets handy.

      +

      First ensure that you have pulled and merged all changes from the main +repository, as explained above. Then, assuming your currently checked +out branch is still mywork, simply do:

      +
      $ hg diff -r default > mywork.patch
+
      +
      +

      This will write to mywork.patch all the changes between default and +mywork.

      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      15. Developer Log

      +

      Next topic

      +

      18. Development Cycle

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/communication.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/communication.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,173 @@ + + + + + + + + 13. Following Python’s Development — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      13. Following Python’s Development

      +

      Python’s development is communicated through a myriad of ways, mostly through +mailing lists, but also other forms.

      +
      +

      13.1. Mailing Lists

      +

      The primary mailing list where discussions about Python’s development occur is +python-dev. The list is open to the public and is subscribed to by all core +developers plus many people simply interested in following Python’s +development. Discussion is focused on issues related to Python’s development, +such as how to handle a specific issue, a PEP, etc. Ideas about new +functionality should not start here and instead should be sent to +python-ideas. Technical support questions should also not be asked here and +instead should go to python-list or python-help.

      +

      The python-committers mailing list is a private mailing list for core +developers (the archives are publicly available). +If something only affects core developers (e.g., the +tree is frozen for commits, etc.), it is discussed here instead of python-dev +to keep traffic down on the latter.

      +

      Python-ideas is a mailing list open to the public to discuss ideas on changing +Python. If a new idea does not start here (or python-list, discussed below), +it will get redirected here.

      +

      Python-checkins sends out an email for every commit to Python’s various +repositories from http://hg.python.org. All core developers +subscribe to this list and are known to reply to these emails to make comments +about various issues they catch in the commit. Replies get redirected to +python-dev.

      +

      There are two mailing lists related to issues on the issue tracker. If you +only want an email for when a new issue is open, subscribe to +new-bugs-announce. If you would rather receive an email for all changes made +to any issue, subscribe to python-bugs-list.

      +

      Sometimes people post new ideas to python-list to gather community opinion before +heading to python-ideas. The list is also sometimes known as comp.lang.python, +the name of the newsgroup is mirrors (it is also known by the abbreviation +c.l.py).

      +

      A complete list of Python mailing lists can be found at http://mail.python.org. +Most lists are also mirrored at http://news.gmane.org/ and can be read and +posted to in various ways, including via web browsers, NNTP newsreaders, and +RSS feed readers.

      +
      +
      +

      13.2. IRC

      +

      Some core developers enjoy spending time on IRC discussing various issues +regarding Python’s development in the #python-dev channel on +irc.freenode.net. This is not a place to ask for help with Python, but to +discuss issues related to Python’s own development. You can use freenode’s +Web interface if you don’t have an IRC +client.

      +
      +
      +

      13.3. Blogs

      +

      Several core developers are active bloggers and discuss Python’s development +that way. You can find their blogs (and various other developers who use Python) +at http://planet.python.org/.

      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      12. Triaging an Issue

      +

      Next topic

      +

      14. How to Become a Core Developer

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/compiler.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/compiler.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,664 @@ + + + + + + + + 26. Design of CPython’s Compiler — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      26. Design of CPython’s Compiler

      +
      +

      26.1. Abstract

      +

      Historically (through 2.4), compilation from source code to bytecode +involved two steps:

      +
        +
      1. Parse the source code into a parse tree (Parser/pgen.c)
        2. +
      2. Emit bytecode based on the parse tree (Python/compile.c)
        3. +
      +

      Historically, this is not how a standard compiler works. The usual +steps for compilation are:

      +
        +
      1. Parse source code into a parse tree (Parser/pgen.c)
        2. +
      2. Transform parse tree into an Abstract Syntax Tree (Python/ast.c)
        3. +
      3. Transform AST into a Control Flow Graph (Python/compile.c)
        4. +
      4. Emit bytecode based on the Control Flow Graph (Python/compile.c)
        5. +
      +

      Starting with Python 2.5, the above steps are now used. This change +was done to simplify compilation by breaking it into three steps. +The purpose of this document is to outline how the latter three steps +of the process work.

      +

      This document does not touch on how parsing works beyond what is needed +to explain what is needed for compilation. It is also not exhaustive +in terms of the how the entire system works. You will most likely need +to read some source to have an exact understanding of all details.

      +
      +
      +

      26.2. Parse Trees

      +

      Python’s parser is an LL(1) parser mostly based off of the +implementation laid out in the Dragon Book [Aho86].

      +

      The grammar file for Python can be found in Grammar/Grammar with the +numeric value of grammar rules are stored in Include/graminit.h. The +numeric values for types of tokens (literal tokens, such as :, +numbers, etc.) are kept in Include/token.h). The parse tree made up of +node * structs (as defined in Include/node.h).

      +

      Querying data from the node structs can be done with the following +macros (which are all defined in Include/node.h):

      +
      +
      CHILD(node *, int)
      +
      Returns the nth child of the node using zero-offset indexing
      +
      RCHILD(node *, int)
      +
      Returns the nth child of the node from the right side; use +negative numbers!
      +
      NCH(node *)
      +
      Number of children the node has
      +
      STR(node *)
      +
      String representation of the node; e.g., will return : for a +COLON token
      +
      TYPE(node *)
      +
      The type of node as specified in Include/graminit.h
      +
      REQ(node *, TYPE)
      +
      Assert that the node is the type that is expected
      +
      LINENO(node *)
      +
      retrieve the line number of the source code that led to the +creation of the parse rule; defined in Python/ast.c
      +
      +

      To tie all of this example, consider the rule for ‘while’:

      +
      while_stmt: 'while' test ':' suite ['else' ':' suite]
+
      +
      +

      The node representing this will have TYPE(node) == while_stmt and +the number of children can be 4 or 7 depending on if there is an ‘else’ +statement. To access what should be the first ‘:’ and require it be an +actual ‘:’ token, (REQ(CHILD(node, 2), COLON)`.

      +
      +
      +

      26.3. Abstract Syntax Trees (AST)

      +

      The abstract syntax tree (AST) is a high-level representation of the +program structure without the necessity of containing the source code; +it can be thought of as an abstract representation of the source code. The +specification of the AST nodes is specified using the Zephyr Abstract +Syntax Definition Language (ASDL) [Wang97].

      +

      The definition of the AST nodes for Python is found in the file +Parser/Python.asdl .

      +

      Each AST node (representing statements, expressions, and several +specialized types, like list comprehensions and exception handlers) is +defined by the ASDL. Most definitions in the AST correspond to a +particular source construct, such as an ‘if’ statement or an attribute +lookup. The definition is independent of its realization in any +particular programming language.

      +

      The following fragment of the Python ASDL construct demonstrates the +approach and syntax:

      +
      module Python
+{
+      stmt = FunctionDef(identifier name, arguments args, stmt* body,
+                          expr* decorators)
+            | Return(expr? value) | Yield(expr value)
+            attributes (int lineno)
+}
+
      +
      +

      The preceding example describes three different kinds of statements; +function definitions, return statements, and yield statements. All +three kinds are considered of type stmt as shown by ‘|’ separating the +various kinds. They all take arguments of various kinds and amounts.

      +

      Modifiers on the argument type specify the number of values needed; ‘?’ +means it is optional, ‘*’ means 0 or more, no modifier means only one +value for the argument and it is required. FunctionDef, for instance, +takes an identifier for the name, ‘arguments’ for args, zero or more +stmt arguments for ‘body’, and zero or more expr arguments for +‘decorators’.

      +

      Do notice that something like ‘arguments’, which is a node type, is +represented as a single AST node and not as a sequence of nodes as with +stmt as one might expect.

      +

      All three kinds also have an ‘attributes’ argument; this is shown by the +fact that ‘attributes’ lacks a ‘|’ before it.

      +

      The statement definitions above generate the following C structure type:

      +
      typedef struct _stmt *stmt_ty;
+
+struct _stmt {
+      enum { FunctionDef_kind=1, Return_kind=2, Yield_kind=3 } kind;
+      union {
+              struct {
+                      identifier name;
+                      arguments_ty args;
+                      asdl_seq *body;
+              } FunctionDef;
+
+              struct {
+                      expr_ty value;
+              } Return;
+
+              struct {
+                      expr_ty value;
+              } Yield;
+      } v;
+      int lineno;
+ }
+
      +
      +

      Also generated are a series of constructor functions that allocate (in +this case) a stmt_ty struct with the appropriate initialization. The +‘kind’ field specifies which component of the union is initialized. The +FunctionDef() constructor function sets ‘kind’ to FunctionDef_kind and +initializes the ‘name’, ‘args’, ‘body’, and ‘attributes’ fields.

      +
      +
      +

      26.4. Memory Management

      +

      Before discussing the actual implementation of the compiler, a discussion of +how memory is handled is in order. To make memory management simple, an arena +is used. This means that a memory is pooled in a single location for easy +allocation and removal. What this gives us is the removal of explicit memory +deallocation. Because memory allocation for all needed memory in the compiler +registers that memory with the arena, a single call to free the arena is all +that is needed to completely free all memory used by the compiler.

      +

      In general, unless you are working on the critical core of the compiler, memory +management can be completely ignored. But if you are working at either the +very beginning of the compiler or the end, you need to care about how the arena +works. All code relating to the arena is in either Include/pyarena.h or +Python/pyarena.c .

      +

      PyArena_New() will create a new arena. The returned PyArena structure will +store pointers to all memory given to it. This does the bookkeeping of what +memory needs to be freed when the compiler is finished with the memory it used. +That freeing is done with PyArena_Free(). This needs to only be called in +strategic areas where the compiler exits.

      +

      As stated above, in general you should not have to worry about memory +management when working on the compiler. The technical details have been +designed to be hidden from you for most cases.

      +

      The only exception comes about when managing a PyObject. Since the rest +of Python uses reference counting, there is extra support added +to the arena to cleanup each PyObject that was allocated. These cases +are very rare. However, if you’ve allocated a PyObject, you must tell +the arena about it by calling PyArena_AddPyObject().

      +
      +
      +

      26.5. Parse Tree to AST

      +

      The AST is generated from the parse tree (see Python/ast.c) using the +function PyAST_FromNode().

      +

      The function begins a tree walk of the parse tree, creating various AST +nodes as it goes along. It does this by allocating all new nodes it +needs, calling the proper AST node creation functions for any required +supporting functions, and connecting them as needed.

      +

      Do realize that there is no automated nor symbolic connection between +the grammar specification and the nodes in the parse tree. No help is +directly provided by the parse tree as in yacc.

      +

      For instance, one must keep track of which node in the parse tree +one is working with (e.g., if you are working with an ‘if’ statement +you need to watch out for the ‘:’ token to find the end of the conditional).

      +

      The functions called to generate AST nodes from the parse tree all have +the name ast_for_xx where xx is what the grammar rule that the function +handles (alias_for_import_name is the exception to this). These in turn +call the constructor functions as defined by the ASDL grammar and +contained in Python/Python-ast.c (which was generated by +Parser/asdl_c.py) to create the nodes of the AST. This all leads to a +sequence of AST nodes stored in asdl_seq structs.

      +

      Function and macros for creating and using asdl_seq * types as found +in Python/asdl.c and Include/asdl.h:

      +
      +
      asdl_seq_new()
      +
      Allocate memory for an asdl_seq for the specified length
      +
      asdl_seq_GET()
      +
      Get item held at a specific position in an asdl_seq
      +
      asdl_seq_SET()
      +
      Set a specific index in an asdl_seq to the specified value
      +
      asdl_seq_LEN(asdl_seq *)
      +
      Return the length of an asdl_seq
      +
      +

      If you are working with statements, you must also worry about keeping +track of what line number generated the statement. Currently the line +number is passed as the last parameter to each stmt_ty function.

      +
      +
      +

      26.6. Control Flow Graphs

      +

      A control flow graph (often referenced by its acronym, CFG) is a +directed graph that models the flow of a program using basic blocks that +contain the intermediate representation (abbreviated “IR”, and in this +case is Python bytecode) within the blocks. Basic blocks themselves are +a block of IR that has a single entry point but possibly multiple exit +points. The single entry point is the key to basic blocks; it all has +to do with jumps. An entry point is the target of something that +changes control flow (such as a function call or a jump) while exit +points are instructions that would change the flow of the program (such +as jumps and ‘return’ statements). What this means is that a basic +block is a chunk of code that starts at the entry point and runs to an +exit point or the end of the block.

      +

      As an example, consider an ‘if’ statement with an ‘else’ block. The +guard on the ‘if’ is a basic block which is pointed to by the basic +block containing the code leading to the ‘if’ statement. The ‘if’ +statement block contains jumps (which are exit points) to the true body +of the ‘if’ and the ‘else’ body (which may be NULL), each of which are +their own basic blocks. Both of those blocks in turn point to the +basic block representing the code following the entire ‘if’ statement.

      +

      CFGs are usually one step away from final code output. Code is directly +generated from the basic blocks (with jump targets adjusted based on the +output order) by doing a post-order depth-first search on the CFG +following the edges.

      +
      +
      +

      26.7. AST to CFG to Bytecode

      +

      With the AST created, the next step is to create the CFG. The first step +is to convert the AST to Python bytecode without having jump targets +resolved to specific offsets (this is calculated when the CFG goes to +final bytecode). Essentially, this transforms the AST into Python +bytecode with control flow represented by the edges of the CFG.

      +

      Conversion is done in two passes. The first creates the namespace +(variables can be classified as local, free/cell for closures, or +global). With that done, the second pass essentially flattens the CFG +into a list and calculates jump offsets for final output of bytecode.

      +

      The conversion process is initiated by a call to the function +PyAST_Compile() in Python/compile.c . This function does both the +conversion of the AST to a CFG and +outputting final bytecode from the CFG. The AST to CFG step is handled +mostly by two functions called by PyAST_Compile(); PySymtable_Build() and +compiler_mod() . The former is in Python/symtable.c while the latter is in +Python/compile.c .

      +

      PySymtable_Build() begins by entering the starting code block for the +AST (passed-in) and then calling the proper symtable_visit_xx function +(with xx being the AST node type). Next, the AST tree is walked with +the various code blocks that delineate the reach of a local variable +as blocks are entered and exited using symtable_enter_block() and +symtable_exit_block(), respectively.

      +

      Once the symbol table is created, it is time for CFG creation, whose +code is in Python/compile.c . This is handled by several functions +that break the task down by various AST node types. The functions are +all named compiler_visit_xx where xx is the name of the node type (such +as stmt, expr, etc.). Each function receives a struct compiler * +and xx_ty where xx is the AST node type. Typically these functions +consist of a large ‘switch’ statement, branching based on the kind of +node type passed to it. Simple things are handled inline in the +‘switch’ statement with more complex transformations farmed out to other +functions named compiler_xx with xx being a descriptive name of what is +being handled.

      +

      When transforming an arbitrary AST node, use the VISIT() macro. +The appropriate compiler_visit_xx function is called, based on the value +passed in for <node type> (so VISIT(c, expr, node) calls +compiler_visit_expr(c, node)). The VISIT_SEQ macro is very similar, +but is called on AST node sequences (those values that were created as +arguments to a node that used the ‘*’ modifier). There is also +VISIT_SLICE() just for handling slices.

      +

      Emission of bytecode is handled by the following macros:

      +
      +
      ADDOP()
      +
      add a specified opcode
      +
      ADDOP_I()
      +
      add an opcode that takes an argument
      +
      ADDOP_O(struct compiler *c, int op, PyObject *type, PyObject *obj)
      +
      add an opcode with the proper argument based on the position of the +specified PyObject in PyObject sequence object, but with no handling of +mangled names; used for when you +need to do named lookups of objects such as globals, consts, or +parameters where name mangling is not possible and the scope of the +name is known
      +
      ADDOP_NAME()
      +
      just like ADDOP_O, but name mangling is also handled; used for +attribute loading or importing based on name
      +
      ADDOP_JABS()
      +
      create an absolute jump to a basic block
      +
      ADDOP_JREL()
      +
      create a relative jump to a basic block
      +
      +

      Several helper functions that will emit bytecode and are named +compiler_xx() where xx is what the function helps with (list, boolop, +etc.). A rather useful one is compiler_nameop(). +This function looks up the scope of a variable and, based on the +expression context, emits the proper opcode to load, store, or delete +the variable.

      +

      As for handling the line number on which a statement is defined, is +handled by compiler_visit_stmt() and thus is not a worry.

      +

      In addition to emitting bytecode based on the AST node, handling the +creation of basic blocks must be done. Below are the macros and +functions used for managing basic blocks:

      +
      +
      NEW_BLOCK()
      +
      create block and set it as current
      +
      NEXT_BLOCK()
      +
      basically NEW_BLOCK() plus jump from current block
      +
      compiler_new_block()
      +
      create a block but don’t use it (used for generating jumps)
      +
      +

      Once the CFG is created, it must be flattened and then final emission of +bytecode occurs. Flattening is handled using a post-order depth-first +search. Once flattened, jump offsets are backpatched based on the +flattening and then a PyCodeObject file is created. All of this is +handled by calling assemble() .

      +
      +
      +

      26.8. Introducing New Bytecode

      +

      Sometimes a new feature requires a new opcode. But adding new bytecode is +not as simple as just suddenly introducing new bytecode in the AST -> +bytecode step of the compiler. Several pieces of code throughout Python depend +on having correct information about what bytecode exists.

      +

      First, you must choose a name and a unique identifier number. The official +list of bytecode can be found in Include/opcode.h . If the opcode is to take +an argument, it must be given a unique number greater than that assigned to +HAVE_ARGUMENT (as found in Include/opcode.h).

      +

      Once the name/number pair +has been chosen and entered in Include/opcode.h, you must also enter it into +Lib/opcode.py and Doc/library/dis.rst .

      +

      With a new bytecode you must also change what is called the magic number for +.pyc files. The variable MAGIC in Python/import.c contains the number. +Changing this number will lead to all .pyc files with the old MAGIC +to be recompiled by the interpreter on import.

      +

      Finally, you need to introduce the use of the new bytecode. Altering +Python/compile.c and Python/ceval.c will be the primary places to change. +But you will also need to change the ‘compiler’ package. The key files +to do that are Lib/compiler/pyassem.py and Lib/compiler/pycodegen.py .

      +

      If you make a change here that can affect the output of bytecode that +is already in existence and you do not change the magic number constantly, make +sure to delete your old .py(c|o) files! Even though you will end up changing +the magic number if you change the bytecode, while you are debugging your work +you will be changing the bytecode output without constantly bumping up the +magic number. This means you end up with stale .pyc files that will not be +recreated. Running +find . -name '*.py[co]' -exec rm -f {} ';' should delete all .pyc files you +have, forcing new ones to be created and thus allow you test out your new +bytecode properly.

      +
      +
      +

      26.9. Code Objects

      +

      The result of PyAST_Compile() is a PyCodeObject which is defined in +Include/code.h . And with that you now have executable Python bytecode!

      +

      The code objects (byte code) is executed in Python/ceval.c . This file +will also need a new case statement for the new opcode in the big switch +statement in PyEval_EvalFrameEx().

      +
      +
      +

      26.10. Important Files

      +
        +

      • Parser/

        +
        +
        +
        Python.asdl
        +

        ASDL syntax file

        +
        +
        asdl.py
        +

        “An implementation of the Zephyr Abstract Syntax Definition +Language.” Uses SPARK to parse the ASDL files.

        +
        +
        asdl_c.py
        +

        “Generate C code from an ASDL description.” Generates +Python/Python-ast.c and Include/Python-ast.h .

        +
        +
        spark.py
        +

        SPARK parser generator

        +
        +
        +
        +
        • +

      • Python/

        +
        +
        +
        Python-ast.c
        +

        Creates C structs corresponding to the ASDL types. Also +contains code for marshaling AST nodes (core ASDL types have +marshaling code in asdl.c). “File automatically generated by +Parser/asdl_c.py”. This file must be committed separately +after every grammar change is committed since the __version__ +value is set to the latest grammar change revision number.

        +
        +
        asdl.c
        +

        Contains code to handle the ASDL sequence type. Also has code +to handle marshalling the core ASDL types, such as number and +identifier. used by Python-ast.c for marshaling AST nodes.

        +
        +
        ast.c
        +

        Converts Python’s parse tree into the abstract syntax tree.

        +
        +
        ceval.c
        +

        Executes byte code (aka, eval loop).

        +
        +
        compile.c
        +

        Emits bytecode based on the AST.

        +
        +
        symtable.c
        +

        Generates a symbol table from AST.

        +
        +
        pyarena.c
        +

        Implementation of the arena memory manager.

        +
        +
        import.c
        +

        Home of the magic number (named MAGIC) for bytecode versioning

        +
        +
        +
        +
        • +

      • Include/

        +
        +
        +
        Python-ast.h
        +

        Contains the actual definitions of the C structs as generated by +Python/Python-ast.c . +“Automatically generated by Parser/asdl_c.py”.

        +
        +
        asdl.h
        +

        Header for the corresponding Python/ast.c .

        +
        +
        ast.h
        +

        Declares PyAST_FromNode() external (from Python/ast.c).

        +
        +
        code.h
        +

        Header file for Objects/codeobject.c; contains definition of +PyCodeObject.

        +
        +
        symtable.h
        +

        Header for Python/symtable.c . struct symtable and +PySTEntryObject are defined here.

        +
        +
        pyarena.h
        +

        Header file for the corresponding Python/pyarena.c .

        +
        +
        opcode.h
        +

        Master list of bytecode; if this file is modified you must modify +several other files accordingly (see “Introducing New Bytecode”)

        +
        +
        +
        +
        • +

      • Objects/

        +
        +
        +
        codeobject.c
        +

        Contains PyCodeObject-related code (originally in +Python/compile.c).

        +
        +
        +
        +
        • +

      • Lib/

        +
        +
        +
        opcode.py
        +

        One of the files that must be modified if Include/opcode.h is.

        +
        +
        +

        compiler/

        +
        +
        +
        pyassem.py
        +

        One of the files that must be modified if Include/opcode.h is +changed.

        +
        +
        pycodegen.py
        +

        One of the files that must be modified if Include/opcode.h is +changed.

        +
        +
        +
        +
        +
        • +
      +
      + +
      +

      26.12. References

      +
      + + + + +
      [Aho86]Alfred V. Aho, Ravi Sethi, Jeffrey D. Ullman. +Compilers: Principles, Techniques, and Tools, +http://www.amazon.com/exec/obidos/tg/detail/-/0201100886/104-0162389-6419108
      + + + + + +
      [Wang97]Daniel C. Wang, Andrew W. Appel, Jeff L. Korn, and Chris +S. Serra. The Zephyr Abstract Syntax Description Language. +In Proceedings of the Conference on Domain-Specific Languages, pp. +213–227, 1997.
      + + + + + +
      [1]Skip Montanaro’s Peephole Optimizer Paper +(http://www.python.org/workshops/1998-11/proceedings/papers/montanaro/montanaro.html)
      + + + + + +
      [2]Bytecodehacks Project +(http://bytecodehacks.sourceforge.net/bch-docs/bch/index.html)
      + + + + + +
      [3]CALL_ATTR opcode +(http://www.python.org/sf/709744)
      + + + + + + + +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      25. Changing CPython’s Grammar

      +

      Next topic

      +

      27. Coverity Scan

      +

      This Page

      + + + +
      +
      +
      + +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/coredev.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/coredev.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,244 @@ + + + + + + + + 14. How to Become a Core Developer — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      14. How to Become a Core Developer

      +
      +

      14.1. What it Takes

      +

      When you have consistently contributed patches which meet quality standards +without requiring extensive rewrites prior to being committed, +you may qualify for +commit privileges and become a core developer of Python. You must also work +well with other core developers (and people in general) as you become an +ambassador for the Python project.

      +

      Typically a core developer will offer you the chance to gain commit privilege. +The person making the offer will become your mentor and watch your commits for +a while to make sure you understand the development process. If other core +developers agree that you should gain commit privileges you are then extended +an official offer.

      +

      You may request commit privileges yourself, but do not be surprised if your +request is turned down. Do not take this personally! It simply means that other +core developers think you need more time contributing patches before you are +able to commit them without supervision.

      +

      A complete list of core developer usernames can be found at +http://hg.python.org/committers.txt. Developer Log lists when and why +someone received commit privileges.

      +
      +
      +

      14.2. Gaining Commit Privileges

      +

      When you have been extended an official offer to become a Python core +developer, there are several things you must do.

      +
      +

      14.2.1. Mailing Lists

      +

      You are expected to subscribe to python-committers, python-dev, +python-checkins, and one of new-bugs-announce or python-bugs-list. See +Following Python’s Development for links to these mailing lists.

      +
      +
      +

      14.2.2. Issue Tracker

      +

      If you did not gain the Developer role in the issue tracker before gaining +commit privileges, please say so. This will allow issues to be assigned to you. +A tracker admin should also flip your “is committer” bit in the tracker’s +account screen.

      +

      It is expected that on the issue tracker you have a username in the form of +“first_name.last_name”. If your initial issue tracker username is not of this +form, please change it. This is so that it is easier to assign issues to the +right person.

      +
      +
      +

      14.2.3. SSH

      +

      You need to generate an SSH 2 RSA key to be able to commit code. You may have +multiple keys if you wish (e.g., for work and home). Send your key as an +attachment in an email to hgaccounts@python.org. Help in generating an SSH key +can be found in the Python Developer FAQ.

      +

      Your SSH key will be set to a username in the form of “first_name.last_name”. +This should match your username on the issue tracker.

      +

      You can verify your commit access by looking at +http://hg.python.org/committers.txt which lists all core developers by +username. If you want to practice, there is a test repository where you can freely commit and push any +changes you like:

      +
      hg clone ssh://hg@hg.python.org/test/ hgtest
+
      +
      +

      An entry in the Developer Log should also be entered for you. +Typically the person who sponsored your application to become a core developer +makes sure an entry is created for you.

      +
      +
      +

      14.2.4. Sign a Contributor Agreement

      +

      Submitting a contributor form for Python licenses any code you contribute to +the Python Software Foundation. While you retain the copyright, giving the PSF +the ability to license your code means it can be put under the PSF license so +it can be legally distributed with Python.

      +

      This is a very important step! Hopefully you have already submitted a +contributor agreement if you have been submitting patches. But if you have not +done this yet, it is best to do this ASAP, probably before you even do your +first commit so as to not forget.

      +
      +
      +

      14.2.5. Read/Write Checkout

      +

      With your commit privileges working and your contributor form submitted, you +can now get a read/write checkout of the code. URLs for read/write checkouts +are different than those for read-only checkouts as SSH is used instead of +HTTP.

      +

      You can clone the repository (which contains all active branches) with:

      +
      hg clone ssh://hg@hg.python.org/cpython
+
      +
      +

      The default branch in that repository is the current development branch. +You can of course switch your working copy to one of the maintenance branches, +for example:

      +
      hg update 2.7
+
      +
      +
      +
      +
      +

      14.3. Responsibilities

      +

      As a core developer, there are certain things that are expected of you.

      +

      First and foremost, be a good person. This might sound melodramatic, but you +are now a member of the Python project and thus represent the project and your +fellow core developers whenever you discuss Python with anyone. We have a +reputation for being a very nice group of people and we would like to keep it +that way.

      +

      Second, please be prompt in responding to questions. We are all volunteers so +what little free time one can dedicate to Python should be spent being +productive. If you have been asked to respond to an issue or answer a question +and you put it off it ends up stalling other people’s work. It is completely +acceptable to say you are too busy, but you need to say that instead of +stringing people along. This obviously applies to anything you do on the issue +tracker as well.

      +

      Third, please list what areas you want to be considered an expert in the +Experts Index. This allows triagers to direct issues to you which involve +an area you are an expert in. But, +as stated in the second point above, if you do not have the time to answer +questions promptly then please remove yourself as needed from the file so that +you will not be bothered in the future. Once again, we all understand how life +gets in the way, so no one will be insulted if you remove yourself from the +list.

      +

      And finally, enjoy yourself! Contributing to open source software should be fun +(overall). If you find yourself no longer enjoying the work then either take a +break or figure out what you need to do to make it enjoyable again.

      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      13. Following Python’s Development

      +

      Next topic

      +

      15. Developer Log

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/coverage.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/coverage.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,345 @@ + + + + + + + + 6. Increase Test Coverage — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      6. Increase Test Coverage

      +

      Python development follows a practice that all semantic changes and additions +to the language and stdlib are accompanied by +appropriate unit tests. Unfortunately Python was in existence for a long time +before the practice came into effect. This has left chunks of the stdlib +untested which is not a desirable situation to be in.

      +

      A good, easy way to become acquainted with Python’s code and to help out is to +help increase the test coverage for Python’s stdlib. Ideally we would like to +have 100% coverage, but any increase is a good one. Do realize, though, that +getting 100% coverage is not always possible. There could be platform-specific +code that simply will not execute for you, errors in the output, etc. You can +use your judgement as to what should and should not be covered, but being +conservative and assuming something should be covered is generally a good rule +to follow.

      +

      Choosing what module you want to increase test coverage for can be done in a +couple of ways. +A third-party website at http://coverage.livinglogic.de/ provides an +overall view of how good coverage is for various modules (you will want to +focus on those in the Lib directory as those are the pure Python modules +from Python’s stdlib, and thus easier to work with than the C extension +modules). But since this is a third-party site we cannot promise that it will +always be accessible or have useful information (i.e., be working properly).

      +

      Another is to follow the examples below and simply see what +coverage your favorite module has. This is “stabbing in the dark”, though, and +so it might take some time to find a module that needs coverage help.

      +

      Finally, you can simply run the entire test suite yourself with coverage turned +on and see what modules need help. This has the drawback of running the entire +test suite under coverage measuring which takes some time to complete, but you +will have an accurate, up-to-date notion of what modules need the most work.

      +

      Do make sure, though, that for any module you do decide to work on that you run +coverage for just that module. This will make sure you know how good the +explicit coverage of the module is from its own set of tests instead of from +implicit testing by other code that happens to use the module.

      +
      +

      6.1. Common Gotchas

      +

      Please realize that coverage reports on modules already imported before coverage +data starts to be recorded will be wrong. Typically you can tell a module falls +into this category by the coverage report saying that global statements that +would obviously be executed upon import have gone unexecuted while local +statements have been covered. In these instances you can ignore the global +statement coverage and simply focus on the local statement coverage.

      +

      When writing new tests to increase coverage, do take note of the style of tests +already provided for a module (e.g., whitebox, blackbox, etc.). As +some modules are primarily maintained by a single core developer they may have +a specific preference as to what kind of test is used (e.g., whitebox) and +prefer that other types of tests not be used (e.g., blackbox). When in doubt, +stick with whitebox testing in order to properly exercise the code.

      +
      +
      +

      6.2. Measuring Coverage

      +

      It should be noted that a quirk of running coverage over Python’s own stdlib is +that certain modules are imported as part of interpreter startup. Those modules +required by Python itself will not be viewed as executed by the coverage tools +and thus look like they have very poor coverage (e.g., the stat +module). In these instances the module will appear to not have any coverage of +global statements but will have proper coverage of local statements (e.g., +function definitions will be not be traced, but the function bodies will). +Calculating the coverage of modules in this situation will simply require +manually looking at what local statements were not executed.

      +
      +

      6.2.1. Using coverage.py

      +

      One of the most popular third-party coverage tools is coverage.py which +provides very nice HTML output along with advanced features such as +branch coverage. If you prefer to stay with tools only +provided by the stdlib then you can by using test.regrtest.

      +

      Because the in-development version of Python is bleeding-edge, it is possible +that the latest release version of coverage.py will not work. In that case you +should try using the in-development of coverage.py to see if it has been +updated as needed. To do this you should clone/check out the development version +of coverage.py:

      +
      hg clone https://bitbucket.org/ned/coveragepy
+
      +
      +

      Another option is to use an installed copy of coverage.py if you already have an +installed copy. But if you do not already have it installed then it is preferred +you use a clone of coverage.py for gathering coverage results.

      +

      If you are using a clone of coverage.py, the following should work (substitute +COVERAGEDIR with the directory where your clone exists, e.g. +../coveragepy):

      +
      ./python COVERAGEDIR
+
      +
      +

      Coverage.py will print out a little bit of helper text verifying that +everything is working. If you are using an installed copy, you can do the +following instead:

      +
      ./python -m coverage
+
      +
      +

      The rest of the examples on how to use coverage.py will assume you are using a +cloned copy, but you can substitute the above and all instructions should still +be valid.

      +

      To run the test suite under coverage.py, do the following:

      +
      ./python COVERAGEDIR run --pylib Lib/test/regrtest.py
+
      +
      +

      To run only a single test, specify the module/package being tested +in the --source flag (so as to prune the coverage reporting to only the +module/package you are interested in) and then append the name of the test you +wish to run to the command:

      +
      ./python COVERAGEDIR run --pylib --source=abc Lib/test/regrtest.py test_abc
+
      +
      +

      To see the results of the coverage run, you can view a text-based report with:

      +
      ./python COVERAGEDIR report
+
      +
      +

      You can use the --show-missing flag to get a list of lines that were not +executed:

      +
      ./python COVERAGEDIR report --show-missing
+
      +
      +

      But one of the strengths of coverage.py is its HTML-based reports which let +you visually see what lines of code were not tested:

      +
      ./python COVERAGEDIR html -i --include=`pwd`/Lib/* --omit="Lib/test/*,Lib/*/tests/*"
+
      +
      +

      This will generate an HTML report in a directory named htmlcov which +ignores any errors that may arise and ignores modules for which test coverage is +unimportant (e.g. tests, temp files, etc.). You can then open the +htmlcov/index.html file in a web browser to view the coverage results along +with pages that visibly show what lines of code were or were not executed.

      +
      +

      6.2.1.1. Branch Coverage

      +

      For the truly daring, you can use another powerful feature of coverage.py: +branch coverage. Testing every possible branch path through code, while a great +goal to strive for, is a secondary goal to getting 100% line +coverage for the entire stdlib (for now).

      +

      If you decide you want to try to improve branch coverage, simply add the +--branch flag to your coverage run:

      +
      ./python COVERAGEDIR run --pylib --branch <arguments to run test(s)>
+
      +
      +

      This will lead to the report stating not only what lines were not covered, but +also what branch paths were not executed.

      +
      +
      +

      6.2.1.2. Coverage Results For Modules Imported Early On

      +

      For the truly truly daring, you can use a hack to get coverage.py to include +coverage for modules that are imported early on during CPython’s startup (e.g. +the encodings module). Do not worry if you can’t get this to work or it doesn’t +make any sense; it’s entirely optional and only important for a small number of +modules.

      +

      If you still choose to try this, the first step is to build coverage.py’s C +extension code. Assuming that coverage.py’s clone is at COVERAGEDIR and +your clone of CPython is at CPYTHONDIR, you execute the following in your +coverage.py clone:

      +
      CPPFLAGS="-I CPYTHONDIR -I CPYTHONDIR/Include" CPYTHONDIR/python setup.py build_ext --inplace
+
      +
      +

      This will build coverage.py’s C extension code in-place, allowing the previous +instructions on how to gather coverage to continue to work.

      +

      To get coverage.py to be able to gather the most accurate coverage data on as +many modules as possible +with a HORRIBLE HACK that you should NEVER use in your own code, run the +following from your CPython clone:

      +
      PYTHONPATH=COVERAGEDIR/coverage/fullcoverage ./python COVERAGEDIR run --pylib Lib/test/regrtest.py
+
      +
      +

      This will give you the most complete coverage possible for CPython’s standard +library.

      +
      +
      +
      +

      6.2.2. Using test.regrtest

      +

      If you prefer to rely solely on the stdlib to generate coverage data, you can +do so by passing the appropriate flags to test.regrtest (along with +any other flags you want to):

      +
      ./python -m test --coverage -D `pwd`/coverage_data <test arguments>
+
      +
      +

      Do note the argument to -D; if you do not specify an absolute path to where +you want the coverage data to end up it will go somewhere you don’t expect.

      +
      +

      Note

      +

      If you are running coverage over the entire test suite, make sure to +add -x test_importlib test_runpy test_trace to exclude those tests as +they trigger exceptions during coverage; see +http://bugs.python.org/issue10541 and http://bugs.python.org/issue10991.

      +
      +

      Once the tests are done you will find the directory you specified contains +files for each executed module along with which lines were executed how many +times.

      +
      +
      +
      +

      6.3. Filing the Issue

      +

      Once you have increased coverage, you need to +generate the patch and submit it to the issue tracker. On the +issue set the “Components” to “Test” and “Versions” to the version of Python you +worked on (i.e., the in-development version).

      +
      +
      +

      6.4. Measuring coverage of C code with gcov and lcov

      +

      It’s also possible to measure the function, line and branch coverage of +Python’s C code. Right now only GCC with gcov is supported. In order to +create an instrumented build of Python with gcov, run:

      +
      make coverage
+
      +
      +

      Then run some code and gather coverage data with the gcov command. In +order to create a HTML report you can install lcov. The command:

      +
      make coverage-lcov
+
      +
      +

      assembles coverage data, removes 3rd party and system libaries and finally +creates a report. You can skip both steps and just run:

      +
      make coverage-report
+
      +
      +

      if you like to generate a coverage report for Python’s stdlib tests. It takes +about 20 to 30 minutes on a modern computer.

      +
      +

      Note

      +

      Multiple test jobs may not work properly. C coverage reporting has only +been tested with a single test process.

      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      5. Running & Writing Tests

      +

      Next topic

      +

      7. Helping with Documentation

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/coverity.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/coverity.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,249 @@ + + + + + + + + 27. Coverity Scan — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      27. Coverity Scan

      +

      Coverity Scan is a free service for static code analysis of Open Source +projects. It is based on Coverity’s commercial product and is able to analyze +C, C++ and Java code.

      +

      Coverity’s static code analysis doesn’t run the code. Instead of that it uses +abstract interpretation to gain information about the code’s control flow and +data flow. It’s able to follow all possible code paths that a program may +take. For example the analyzer understands that malloc() returns a memory +that must be freed with free() later. It follows all branches and function +calls to see if all possible combinations free the memory. The analyzer is +able to detect all sorts of issues like resource leaks (memory, file +descriptors), NULL dereferencing, use after free, unchecked return values, +dead code, buffer overflows, integer overflows, uninitialized variables, and +many more.

      +
      +

      27.1. Access to analysis reports

      +

      The results are available on the Coverity Scan website. In order to +access the results you have to create an account yourself. Then go to +Projects using Scan and add yourself to the Python project. New members must +be approved by an admin (see Contact).

      +

      Access is restricted to Python core developers only. Other individuals may be +given access at our own discretion, too. Every now and then Coverity detects a +critical issue in Python’s code – new analyzers may even find new bugs in +mature code. We don’t want to disclose issues prematurely.

      +
      +
      +

      27.2. Building and uploading analysis

      +

      The process is automated. A script runs hg pull, hg update, +cov-build and uploads the latest analysis to Coverity. Since Coverity has +limited the maximum number of builds per week Python is analyzed every second +day. The build runs on a dedicated virtual machine on PSF’s infrastructure at +OSU Open Source Labs. The process is maintained by Christian Heimes (see +Contact). At present only the tip is analyzed with the 64bit Linux tools.

      +
      +
      +

      27.3. Known limitations

      +

      Some aspects of Python’s C code are not yet understood by Coverity.

      +
      +

      27.3.1. False positives

      +
      +
      Py_BuildValue("N", PyObject*)
      +
      Coverity doesn’t understand that N format char passes the object along +without touching its reference count. On this ground the analyzer detects +a resource leak. CID 719685
      +
      PyLong_FromLong() for negative values
      +
      Coverity claims that PyLong_FromLong() and other PyLong_From*() +functions cannot handle a negative value because the value might be used as +an array index in get_small_int(). CID 486783
      +
      PyLong_FromLong() for n in [-5 ... +255]
      +
      For integers in the range of Python’s small int cache the PyLong_From*() +function can never fail and never returns NULL. CID 1058291
      +
      PyArg_ParseTupleAndKeywords(args, kwargs, "s#", &data, &length)
      +
      Some functions use the format char combination such as s#, u# or +z# to get data and length of a character array. Coverity doesn’t +recognize the relation between data and length. Sometimes it detects a buffer +overflow if data is written to a fixed size buffer although +length <= sizeof(buffer). CID 486613
      +
      path_converter() dereferencing after null check
      +
      The path_converter() function in posixmodule.c makes sure that +either path_t.narrow or path_t.wide is filled unless +path_t.nullable is explicitly enabled. CID 719648
      +
      +
      +
      +

      27.3.2. Intentionally

      +
      +
      Py_VA_COPY()
      +
      Python is written in C89 (ANSI C), therefore it can’t use C99 features such +as va_copy(). Python’s own variant Py_VA_COPY() uses memcpy() +to make a copy of a va_list variable. Coverity detects two issues in +this approach: “Passing argument “lva” of type “va_list” and sizeof(va_list) +to function memcpy() is suspicious.” CID 486405 and “Uninitialized pointer +read” CID 486630.
      +
      +
      +
      +
      +

      27.4. Modeling

      +

      Modeling is explained in the Coverity Help Center which is available in +the help menu of Coverity Connect. coverity_model.c contains a copy of +Python’s modeling file for Coverity. Please keep the copy in sync with the +model file in Analysis Settings of Coverity Scan.

      +
      +
      +

      27.5. Workflow

      +
      +

      27.5.1. False positive and intentional issues

      +

      If the problem is listed under Known limitations then please set the +classification to either “False positive” or “Intentional”, the action to +“Ignore”, owner to your own account and add a comment why the issue +is considered false positive or intentional.

      +

      If you think it’s a new false positive or intentional then please contact an +admin. The first step should be an updated to Python’s Modeling file.

      +
      +
      +

      27.5.2. Positive issues

      +

      You should always create an issue unless it’s really a trivial case. Please +add the full url to the ticket under Ext. Reference and add the CID +(Coverity ID) to both the ticket and the checkin message. It makes it much +easier to understand the relation between tickets, fixes and Coverity issues.

      +
      +
      +
      +

      27.6. Contact

      +

      Please include both Brett and Christian in any mail regarding Coverity. Mails +to Coverity should go through Brett or Christian, too.

      +
      +
      Christian Heimes <christian (at) python (dot) org>
      +
      admin, maintainer of build machine, intermediary between Python and Coverity
      +
      Brett Cannon <brett (at) python (dot) org>
      +
      co-admin
      +
      Dakshesh Vyas <scan-admin@coverity.com>
      +
      Technical Manager - Coverity Scan
      +
      +
      +

      See also

      +

      Coverity Scan FAQ

      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      26. Design of CPython’s Compiler

      +

      Next topic

      +

      28. Dynamic Analysis with Clang

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/devcycle.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/devcycle.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,270 @@ + + + + + + + + 18. Development Cycle — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      18. Development Cycle

      +

      The responsibilities of a core developer shift based on what kind of branch of +Python a developer is working on and what stage the branch is in.

      +

      To clarify terminology, Python uses a major.minor.micro nomenclature +for production-ready releases. So for Python 3.1.2 final, that is a major +version of 3, a minor version of 1, and a micro version of 2.

      +
        +
      • new major versions are exceptional; they only come when strongly +incompatible changes are deemed necessary, and are planned very long +in advance;
        • +
      • new minor versions are feature releases; they get released roughly +every 18 months, from the current in-development +branch;
        • +
      • new micro versions are bugfix releases; they get released roughly +every 6 months, although they can come more often if necessary; they are +prepared in maintenance branches.
        • +
      +

      We also publish non-final versions which get an additional qualifier: +Alpha, Beta, release candidate. These versions +are aimed at testing by advanced users, not production use.

      +
      +

      18.1. Branches

      +

      There is a branch for each feature version, whether released or not (e.g. +2.7, 3.5). Development is handled separately for Python 2 and Python 3: +no merging happens between 2.x and 3.x branches.

      +

      In each of the 2.x and 3.x realms, the branch for a feature version is always a +descendant of the previous feature version: for example, the 3.3 branch is a +descendant of the 3.2 branch.

      +

      Therefore, each change should be made first in the oldest branch to which it +applies and forward-ported as appropriate: if a bug must be fixed in both Python +3.4 and 3.5, first fix it in 3.4 and then merge 3.4 into default +(which holds the future 3.5).

      +
      +

      18.1.1. In-development (main) branch

      +

      The default branch is the branch for the next feature release; it is +under active development for all kinds of changes: new features, semantic +changes, performance improvements, bug fixes. As the name indicates, it +is the branch checked out by default by Mercurial.

      +

      Once a Final release (say, 3.3) is made from the in-development branch, a +new maintenance branch is created to host all bug fixing +activity for further micro versions (3.3.1, 3.3.2, etc.).

      +
      +
      +

      18.1.2. Maintenance branches

      +

      A branch for a previous feature release, currently being maintained for bug +fixes. There are usually two maintenance branches at any given time: one for +Python 3.x and +one for Python 2.x. At some point in the future, Python 2.x will be closed +for bug fixes and there will be only one maintenance branch left.

      +

      The only changes allowed to occur in a maintenance branch without debate are +bug fixes. Also, a general rule for maintenance branches is that compatibility +must not be broken at any point between sibling minor releases (3.3.1, 3.3.2, +etc.). For both rules, only rare exceptions are accepted and must be +discussed first.

      +

      Sometime after a new maintenance branch is created (after a new minor version +is released), the old maintenance branch on that major version will go into +security mode, +usually after one last maintenance release at the discretion of the +release manager. For example, the 3.2 maintenance branch was put into +security mode after the 3.2.4 final maintenance release +following the release of 3.3.0.

      +
      +
      +

      18.1.3. Security branches

      +

      A branch less than 5 years old but no longer in maintenance mode.

      +

      The only changes made to a security branch are those fixing issues exploitable +by attackers such as crashes, privilege escalation and, optionally, other +issues such as denial of service attacks. Any other changes are +not considered a security risk and thus not backported to a security branch.

      +

      Commits to security branches are to be coordinated with the release manager +for the corresponding feature version, as listed below in the Summary. +Any release made from a security branch is source-only and done only when actual +security patches have been applied to the branch.

      +
      +
      +

      18.1.4. Summary

      +

      There are 5 open branches right now in the Mercurial repository:

      +
        +
      • the default branch holds the future 3.5 version and descends from 3.4 +(future RM: Larry Hastings)
        • +
      • the 3.4 branch holds bug fixes for future 3.4.x maintenance releases +and descends from 3.3 (RM: Larry Hastings)
        • +
      • the 3.3 branch holds security fixes for future 3.3.x maintenance releases +and descends from 3.2 (RM: Georg Brandl)
        • +
      • the 3.2 branch holds security fixes for future 3.2.x security releases +(RM: Georg Brandl)
        • +
      • the 3.1 branch holds security fixes for future 3.1.x security releases +(RM: Benjamin Peterson)
        • +
      • the 2.7 branch holds bug fixes for future 2.7.x maintenance releases and +descends from 2.6 (RM: Benjamin Peterson)
        • +
      +
      +
      +
      +

      18.2. Stages

      +

      Based on what stage the in-development version of Python +is in, the responsibilities of a core developer change in regards to commits +to the VCS.

      +
      +

      18.2.1. Pre-alpha

      +

      The branch is in this stage when no official release has been done since +the latest final release. There are no special restrictions placed on +commits, although the usual advice applies (getting patches reviewed, avoiding +breaking the buildbots).

      +
      +
      +

      18.2.2. Alpha

      +

      Alpha releases typically serve as a reminder to core developers that they +need to start getting in changes that change semantics or add something to +Python as such things should not be added during a Beta. Otherwise no new +restrictions are in place while in alpha.

      +
      +
      +

      18.2.3. Beta

      +

      After a first beta release is published, no new features are accepted. Only +bug fixes can now be committed. This is when core developers should concentrate +on the task of fixing regressions and other new issues filed by users who have +downloaded the alpha and beta releases.

      +

      Being in beta can be viewed much like being in RC but without the extra overhead +of needing commit reviews.

      +
      +
      +

      18.2.4. Release Candidate (RC)

      +

      A branch preparing for an RC release can only have bugfixes applied that have +been reviewed by other core developers. Generally, these issues must be +severe enough (e.g. crashes) that they deserve fixing before the final release. +All other issues should be deferred to the next development cycle, since stability +is the strongest concern at this point.

      +

      You cannot skip the peer review during an RC, no matter how small! Even if +it is a simple copy-and-paste change, everything requires peer review from +a core developer.

      +
      +
      +

      18.2.5. Final

      +

      When a final release is being cut, only the release manager (RM) can make +changes to the branch. After the final release is published, the full +development cycle starts again for the next minor version.

      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      16. Committing and Pushing Changes

      +

      Next topic

      +

      19. Continuous Integration

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/developers.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/developers.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,525 @@ + + + + + + + + 15. Developer Log — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      15. Developer Log

      +

      This file is a running log of developers given commit privileges for Python.

      +

      The purpose is to provide some institutional memory of who was given access +and why.

      +

      The first entry starts in April 2005. In keeping with the style of +Misc/NEWS, newer entries should be added to the top. +Entries should include the initials of the +project admin who made the change or granted access.

      +

      Note, when giving new commit permissions, be sure to get a contributor agreement +from the committer. See http://www.python.org/psf/contrib/ for details. When +the agreement is signed, please note it in this log. SSH keys of the committer +should be sent to hgaccounts@python.org.

      +

      This file is encoded in UTF-8. If the usual form for a name is not in +a Latin or extended Latin alphabet, make sure to include an ASCII +transliteration too.

      +
      +

      15.1. Permissions History

      +
        +

      • Yury Selivanov was given push privileges on Jan 23 2014 by GFB, for “inspect” +module and general contributions, on recommendation by Nick Coghlan.

        +
        • +

      • Donald Stufft was given push privileges on Aug 14 2013 by BAC, for PEP +editing, on the recommendation of Nick Coghlan.

        +
        • +

      • Ethan Furman was given push privileges on May 11 2013 by BAC, for PEP 435 +work, on the recommendation of Eli Bendersky.

        +
        • +

      • Roger Serwy was given push privileges on Mar 21 2013 by GFB, for IDLE +contributions, on recommendation by Ned Deily.

        +
        • +

      • Serhiy Storchaka was given push privileges on Dec 26 2012 by GFB, for general +contributions, on recommendation by Trent Nelson.

        +
        • +

      • Chris Jerdonek was given push privileges on Sep 24 2012 by GFB, for general +contributions, on recommendation by Ezio Melotti.

        +
        • +

      • Daniel Holth was given push privileges on Sep 9 2012 by GFB, for PEP editing.

        +
        • +

      • Eric Snow was given push privileges on Sep 5 2012 by Antoine Pitrou for +general contributions, on recommendation by Nick Coghlan.

        +
        • +

      • Peter Moody was given push privileges on May 20 2012 by Antoine Pitrou for +authorship and maintenance of the ipaddress module (accepted in PEP 3144 by +Nick Coghlan).

        +
        • +

      • Hynek Schlawack was given push privileges on May 14 2012 by Antoine Pitrou +for general contributions.

        +
        • +

      • Richard Oudkerk was given push privileges on Apr 29 2012 by Antoine Pitrou +on recommendation by Charles-François Natali and Jesse Noller, for various +contributions to multiprocessing (and original authorship of +multiprocessing’s predecessor, the processing package).

        +
        • +

      • Andrew Svetlov was given push privileges on Mar 13 2012 by MvL at +the PyCon sprint.

        +
        • +

      • Petri Lehtinen was given push privileges on Oct 22 2011 by GFB, for +general contributions, on recommendation by Antoine Pitrou.

        +
        • +

      • Meador Inge was given push privileges on Sep 19 2011 by GFB, for +general contributions, on recommendation by Mark Dickinson.

        +
        • +

      • Sandro Tosi was given push privileges on Aug 1 2011 by Antoine Pitrou, +for documentation and other contributions, on recommendation by Ezio +Melotti, R. David Murray and others.

        +
        • +

      • Charles-François Natali was given push privileges on May 19 2011 by Antoine +Pitrou, for general contributions, on recommendation by Victor Stinner, +Brian Curtin and others.

        +
        • +

      • Nadeem Vawda was given push privileges on Apr 10 2011 by GFB, for +general contributions, on recommendation by Antoine Pitrou.

        +
        • +

      • Carl Friedrich Bolz was given push privileges on Mar 21 2011 by BAC, for +stdlib compatibility work for PyPy.

        +
        • +

      • Alexis Métaireau, Elson Rodriguez, Kelsey Hightower, Michael Mulich and +Walker Hale were given push privileges on Mar 16 2011 by GFB, for +contributions to the packaging module.

        +
        • +

      • Jeff Hardy was given push privileges on Mar 14 2011 by BAC, for stdlib +compatibility work for IronPython.

        +
        • +

      • Alex Gaynor and Maciej Fijalkowski were given push privileges on Mar 13 2011 +by BAC, for stdlib compatibility work for PyPy.

        +
        • +

      • Ross Lagerwall was given push privileges on Mar 13 2011 by GFB, +on recommendation by Antoine Pitrou and Ned Deily.

        +
        • +

      • Eli Bendersky was given commit access on Jan 11 2011 by BAC, +on recommendation by Terry Reedy and Nick Coghlan.

        +
        • +

      • Ned Deily was given commit access on Jan 9 2011 by MvL, +on recommendation by Antoine Pitrou.

        +
        • +

      • David Malcolm was given commit access on Oct 27 2010 by GFB, +at recommendation by Antoine Pitrou and Raymond Hettinger.

        +
        • +

      • Tal Einat was given commit access on Oct 4 2010 by MvL, +for improving IDLE.

        +
        • +

      • Łukasz Langa was given commit access on Sep 08 2010 by GFB, +at suggestion of Antoine Pitrou, for general bug fixing.

        +
        • +

      • Daniel Stutzbach was given commit access on Aug 22 2010 by MvL, +for general bug fixing.

        +
        • +

      • Ask Solem was given commit access on Aug 17 2010 by MvL, +on recommendation by Jesse Noller, for work on the multiprocessing +library.

        +
        • +

      • George Boutsioukis was given commit access on Aug 10 2010 +by MvL, for work on 2to3.

        +
        • +

      • Éric Araujo was given commit access on Aug 10 2010 by BAC, +at suggestion of Tarek Ziadé.

        +
        • +

      • Terry Reedy was given commit access on Aug 04 2010 by MvL, +at suggestion of Nick Coghlan.

        +
        • +

      • Brian Quinlan was given commit access on Jul 26 2010 by GFB, +for work related to PEP 3148.

        +
        • +

      • Reid Kleckner was given commit access on Jul 11 2010 by GFB, +for work on the py3k-jit branch, at suggestion of the Unladen +Swallow team.

        +
        • +

      • Alexander Belopolsky was given commit access on May 25 2010 +by MvL at suggestion of Mark Dickinson.

        +
        • +

      • Tim Golden was given commit access on April 21 2010 by MvL, +at suggestion of Michael Foord.

        +
        • +

      • Giampaolo Rodolà was given commit access on April 17 2010 by +MvL, at suggestion of R. David Murray.

        +
        • +

      • Jean-Paul Calderone was given commit access on April 6 2010 by +GFB, at suggestion of Michael Foord and others.

        +
        • +

      • Brian Curtin was given commit access on March 24 2010 by MvL.

        +
        • +

      • Florent Xicluna was given commit access on February 25 2010 by +MvL, based on Antoine Pitrou’s recommendation.

        +
        • +

      • Dino Viehland was given SVN access on February 23 2010 by Brett +Cannon, for backporting tests from IronPython.

        +
        • +

      • Larry Hastings was given SVN access on February 22 2010 by +Andrew Kuchling, based on Brett Cannon’s recommendation.

        +
        • +

      • Victor Stinner was given SVN access on January 30 2010 by MvL, +at recommendation by Mark Dickinson and Amaury Forgeot d’Arc.

        +
        • +

      • Stefan Krah was given SVN access on January 5 2010 by GFB, at +suggestion of Mark Dickinson, for work on the decimal module.

        +
        • +

      • Doug Hellmann was given SVN access on September 19 2009 by GFB, at +suggestion of Jesse Noller, for documentation work.

        +
        • +

      • Ezio Melotti was given SVN access on June 7 2009 by GFB, for work on and +fixes to the documentation.

        +
        • +

      • Paul Kippes was given commit privileges at PyCon 2009 by BAC to work on 3to2.

        +
        • +

      • Ron DuPlain was given commit privileges at PyCon 2009 by BAC to work on 3to2.

        +
        • +

      • Several developers of alternative Python implementations where +given access for test suite and library adaptions by MvL: +Allison Randal (Parrot), Michael Foord (IronPython), +Jim Baker, Philip Jenvey, and Frank Wierzbicki (all Jython).

        +
        • +

      • R. David Murray was given SVN access on March 30 2009 by MvL, after +recommendation by BAC.

        +
        • +

      • Chris Withers was given SVN access on March 8 2009 by MvL, +after recommendation by GvR.

        +
        • +

      • Tarek Ziadé was given SVN access on December 21 2008 by NCN, +for maintenance of distutils.

        +
        • +

      • Hirokazu Yamamoto was given SVN access on August 12 2008 by MvL, +for contributions to the Windows build.

        +
        • +

      • Antoine Pitrou was given SVN access on July 16 2008, by recommendation +from GvR, for general contributions to Python.

        +
        • +

      • Jesse Noller was given SVN access on 16 June 2008 by GFB, +for work on the multiprocessing module.

        +
        • +

      • Gregor Lingl was given SVN access on 10 June 2008 by MvL, +for work on the turtle module.

        +
        • +

      • Robert Schuppenies was given SVN access on 21 May 2008 by MvL, +for GSoC contributions.

        +
        • +

      • Rodrigo Bernardo Pimentel was given SVN access on 29 April 2008 by MvL, +for GSoC contributions.

        +
        • +

      • Heiko Weinen was given SVN access on 29 April 2008 by MvL, +for GSoC contributions.

        +
        • +

      • Jesus Cea was given SVN access on 24 April 2008 by MvL, +for maintenance of bsddb.

        +
        • +

      • Guilherme Polo was given SVN access on 24 April 2008 by MvL, +for GSoC contributions.

        +
        • +

      • Thomas Lee was given SVN access on 21 April 2008 by NCN, +for work on branches (ast/optimizer related).

        +
        • +

      • Jeroen Ruigrok van der Werven was given SVN access on 12 April 2008 +by GFB, for documentation work.

        +
        • +

      • Josiah Carlson was given SVN access on 26 March 2008 by GFB, +for work on asyncore/asynchat.

        +
        • +

      • Benjamin Peterson was given SVN access on 25 March 2008 by GFB, +for bug triage work.

        +
        • +

      • Jerry Seutter was given SVN access on 20 March 2008 by BAC, for +general contributions to Python.

        +
        • +

      • Jeff Rush was given SVN access on 18 March 2008 by AMK, for Distutils work.

        +
        • +

      • David Wolever was given SVN access on 17 March 2008 by MvL, +for 2to3 work.

        +
        • +

      • Trent Nelson was given SVN access on 17 March 2008 by MvL, +for general contributions to Python.

        +
        • +

      • Mark Dickinson was given SVN access on 6 January 2008 by Facundo +Batista for his work on mathematics and number related issues.

        +
        • +

      • Amaury Forgeot d’Arc was given SVN access on 9 November 2007 by MvL, +for general contributions to Python.

        +
        • +

      • Christian Heimes was given SVN access on 31 October 2007 by MvL, +for general contributions to Python.

        +
        • +

      • Chris Monson was given SVN access on 20 October 2007 by NCN, +for his work on editing PEPs.

        +
        • +

      • Bill Janssen was given SVN access on 28 August 2007 by NCN, +for his work on the SSL module and other things related to (SSL) sockets.

        +
        • +

      • Jeffrey Yasskin was given SVN access on 9 August 2007 by NCN, +for his work on PEPs and other general patches.

        +
        • +

      • Mark Summerfield was given SVN access on 1 August 2007 by GFB, +for work on documentation.

        +
        • +

      • Armin Ronacher was given SVN access on 23 July 2007 by GFB, +for work on the documentation toolset. He now maintains the +ast module.

        +
        • +

      • Senthil Kumaran was given SVN access on 16 June 2007 by MvL, +for his Summer-of-Code project, mentored by Skip Montanaro.

        +
        • +

      • Alexandre Vassalotti was given SVN access on 21 May 2007 by MvL, +for his Summer-of-Code project, mentored by Brett Cannon.

        +
        • +

      • Travis Oliphant was given SVN access on 17 Apr 2007 by MvL, +for implementing the extended buffer protocol.

        +
        • +

      • Ziga Seilnacht was given SVN access on 09 Mar 2007 by MvL, +for general maintenance.

        +
        • +

      • Pete Shinners was given SVN access on 04 Mar 2007 by NCN, +for PEP 3101 work in the sandbox.

        +
        • +

      • Pat Maupin and Eric V. Smith were given SVN access on 28 Feb 2007 by NCN, +for PEP 3101 work in the sandbox.

        +
        • +

      • Steven Bethard (SF name “bediviere”) added to the SourceForge Python +project 26 Feb 2007, by NCN, as a tracker tech.

        +
        • +

      • Josiah Carlson (SF name “josiahcarlson”) added to the SourceForge Python +project 06 Jan 2007, by NCN, as a tracker tech. He will maintain asyncore.

        +
        • +

      • Collin Winter was given SVN access on 05 Jan 2007 by NCN, for PEP +update access.

        +
        • +

      • Lars Gustaebel was given SVN access on 20 Dec 2006 by NCN, for tarfile.py +related work.

        +
        • +

      • 2006 Summer of Code entries: SoC developers are expected to work +primarily in nondist/sandbox or on a branch of their own, and will +have their work reviewed before changes are accepted into the trunk.

        +
          +
        • Matt Fleming was added on 25 May 2006 by AMK; he’ll be working on +enhancing the Python debugger.
          • +
        • Jackilyn Hoxworth was added on 25 May 2006 by AMK; she’ll be adding logging +to the standard library.
          • +
        • Mateusz Rukowicz was added on 30 May 2006 by AMK; he’ll be +translating the decimal module into C.
          • +
        +
        • +

      • SVN access granted to the “Need for Speed” Iceland sprint attendees, +between May 17 and 21, 2006, by Tim Peters. All work is to be done +in new sandbox projects or on new branches, with merging to the +trunk as approved:

        +

        Andrew Dalke +Christian Tismer +Jack Diederich +John Benediktsson +Kristján V. Jónsson +Martin Blais +Richard Emslie +Richard Jones +Runar Petursson +Steve Holden +Richard M. Tew

        +
        • +

      • Steven Bethard was given SVN access on 27 Apr 2006 by DJG, for PEP +update access.

        +
        • +

      • Talin was given SVN access on 27 Apr 2006 by DJG, for PEP update +access.

        +
        • +

      • George Yoshida (SF name “quiver”) added to the SourceForge Python +project 14 Apr 2006, by Tim Peters, as a tracker admin. See +contemporaneous python-checkins thread with the unlikely Subject: +r45329 - python/trunk/Doc/whatsnew/whatsnew25.tex

        +
        • +

      • Ronald Oussoren was given SVN access on 3 Mar 2006 by NCN, for Mac +related work.

        +
        • +

      • Bob Ippolito was given SVN access on 2 Mar 2006 by NCN, for Mac +related work.

        +
        • +

      • Nick Coghlan requested CVS access so he could update his PEP directly. +Granted by GvR on 16 Oct 2005.

        +
        • +

      • Added two new developers for the Summer of Code project. 8 July 2005 +by RDH. Andrew Kuchling will be mentoring Gregory K Johnson for a +project to enhance mailbox. Brett Cannon requested access for Flovis +Bruynooghe (sirolf) to work on pstats, profile, and hotshot. Both users +are expected to work primarily in nondist/sandbox and have their work +reviewed before making updates to active code.

        +
        • +

      • Georg Brandl was given SF tracker permissions on 28 May 2005 +by RDH. Since the beginning of 2005, he has been active in discussions +on python-dev and has submitted a dozen patch reviews. The permissions +add the ability to change tracker status and to attach patches. On +3 June 2005, this was expanded by RDH to include checkin permissions.

        +
        • +

      • Terry Reedy was given SF tracker permissions on 7 Apr 2005 by RDH.

        +
        • +

      • Nick Coghlan was given SF tracker permissions on 5 Apr 2005 by RDH. +For several months, he has been active in reviewing and contributing +patches. The added permissions give him greater flexibility in +working with the tracker.

        +
        • +

      • Eric Price was made a developer on 2 May 2003 by TGP. This was +specifically to work on the new decimal package, which lived in +nondist/sandbox/decimal/ at the time.

        +
        • +

      • Eric S. Raymond was made a developer on 2 Jul 2000 by TGP, for general +library work. His request is archived here: +http://mail.python.org/pipermail/python-dev/2000-July/005314.html

        +
        • +
      +
      +
      +

      15.2. Permissions Dropped on Request

      +
        +
      • Roy Smith, Matt Fleming and Richard Emslie sent drop requests. +4 Aug 2008 GFB
        • +
      • Per note from Andrew Kuchling, the permissions for Gregory K Johnson +and the Summer Of Code project are no longer needed. 4 Aug 2008 GFB
        • +
      • Per note from Andrew Kuchling, the permissions for Gregory K Johnson +and the Summer Of Code project are no longer needed. AMK will make +any future checkins directly. 16 Oct 2005 RDH
        • +
      • Johannes Gijsbers sent a drop request. 27 July 2005 RDH
        • +
      • Flovis Bruynooghe sent a drop request. 14 July 2005 RDH
        • +
      • Paul Prescod sent a drop request. 30 Apr 2005 RDH
        • +
      • Finn Bock sent a drop request. 13 Apr 2005 RDH
        • +
      • Eric Price sent a drop request. 10 Apr 2005 RDH
        • +
      • Irmen de Jong requested dropping CVS access while keeping tracker +access. 10 Apr 2005 RDH
        • +
      • Moshe Zadka and Ken Manheimer sent drop requests. 8 Apr 2005 by RDH
        • +
      • Steve Holden, Gerhard Haring, and David Cole sent email stating that +they no longer use their access. 7 Apr 2005 RDH
        • +
      +
      +
      +

      15.3. Permissions Dropped after Loss of Contact

      +
        +
      • Several unsuccessful efforts were made to contact Charles G Waldman. +Removed on 8 Apr 2005 by RDH.
        • +
      +
      +
      +

      15.4. Initials of Project Admins

      +
        +
      • TGP: Tim Peters
        • +
      • GFB: Georg Brandl
        • +
      • BAC: Brett Cannon
        • +
      • NCN: Neal Norwitz
        • +
      • DJG: David Goodger
        • +
      • MvL: Martin v. Loewis
        • +
      • GvR: Guido van Rossum
        • +
      • RDH: Raymond Hettinger
        • +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      14. How to Become a Core Developer

      +

      Next topic

      +

      16. Committing and Pushing Changes

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/docquality.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/docquality.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,187 @@ + + + + + + + + 7. Helping with Documentation — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      7. Helping with Documentation

      +

      Python is known for having good documentation. But maintaining all of it and +keeping a high level of quality takes a lot of effort. Help is always +appreciated with the documentation, and it requires little programming +experience (with or without Python).

      +

      Documenting Python covers the details of how Python’s documentation works. +It includes an explanation of the markup used (although you can figure a lot +out simply by looking at pre-existing documentation) and how to build the documentation (which allows you to see how your changes +will look along with validating that your new markup is correct).

      +

      The documentation built from the in-development and +maintenance branches can be viewed from +http://docs.python.org/dev/. The in-development and most recent 2.x and 3.x +maintenance branches are rebuilt once per day.

      +

      If you care to get more involved with documentation, you may also consider +subscribing to the +docs@python.org mailing list. +Documentation issues reported on the issue tracker are sent here as well as +some bug reports being directly emailed to the mailing list. There is also the +docs-sig@python.org mailing list which discusses the +documentation toolchain, projects, standards, etc.

      +
      +

      7.1. Helping with issues filed on the issue tracker

      +

      If you look at documentation issues on the issue tracker, you +will find various documentation problems that need work. Issues vary from +typos, to unclear documentation, to something completely lacking documentation.

      +

      If you decide to tackle a documentation issue, you simply create a patch for the issue and upload it. If you are worried that someone else might +be working simultaneously on the issue, simply leave a comment on the issue +saying you are going to try and create a patch and roughly how long you think +you will take to do it (this allows others to take on the issue if you happen +to forget or lose interest).

      +
      +
      +

      7.2. Proofreading

      +

      While an issue filed on the issue tracker means there is a known issue +somewhere, that does not mean there are not other issues lurking about in the +documentation. Simply proofreading parts of the documentation is enough to +uncover problems (e.g., documentation that needs to be updated for Python 3 +from Python 2).

      +

      If you decide to proofread, then read a section of the documentation from start +to finish, filing issues in the issue tracker for each problem you find. Don’t +file a single issue for an entire section containing multiple problems as that +makes it harder to break the work up for multiple people to help with.

      +
      +
      +

      7.3. Helping with the Developer’s Guide

      +

      The Developer’s Guide uses the same process as the main Python documentation, +except for some small differences. The source lives in a separate +repository. Bug reports and patches should be submitted to the Python +bug tracker using the devguide component. Changes to the devguide +are normally published within a day, on a schedule that may be different from +the main documentation.

      +

      To clone the Developer’s Guide:

      +
      $ hg clone http://hg.python.org/devguide
+
      +
      +

      Core developers should use:

      +
      $ hg clone ssh://hg@hg.python.org/devguide
+
      +
      +

      instead so that they can push back their edits to the server.

      +

      To build the devguide, you must have Sphinx installed. The devguide HTML +can be built by running:

      +
      $ make html
+
      +
      +

      in the checkout directory, which will write the files to the _build/html +directory.

      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      6. Increase Test Coverage

      +

      Next topic

      +

      8. Documenting Python

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/documenting.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/documenting.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,1666 @@ + + + + + + + + 8. Documenting Python — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      8. Documenting Python

      +

      The Python language has a substantial body of documentation, much of it +contributed by various authors. The markup used for the Python documentation is +reStructuredText, developed by the docutils project, amended by custom +directives and using a toolset named Sphinx to post-process the HTML output.

      +

      This document describes the style guide for our documentation as well as the +custom reStructuredText markup introduced by Sphinx to support Python +documentation and how it should be used.

      +

      The documentation in HTML, PDF or EPUB format is generated from text files +written using the reStructuredText format and contained in the +CPython Mercurial repository.

      +
      +

      Note

      +

      If you’re interested in contributing to Python’s documentation, there’s no +need to write reStructuredText if you’re not so inclined; plain text +contributions are more than welcome as well. Send an e-mail to +docs@python.org or open an issue on the tracker.

      +
      +
      +

      8.1. Introduction

      +

      Python’s documentation has long been considered to be good for a free +programming language. There are a number of reasons for this, the most +important being the early commitment of Python’s creator, Guido van Rossum, to +providing documentation on the language and its libraries, and the continuing +involvement of the user community in providing assistance for creating and +maintaining documentation.

      +

      The involvement of the community takes many forms, from authoring to bug reports +to just plain complaining when the documentation could be more complete or +easier to use.

      +

      This document is aimed at authors and potential authors of documentation for +Python. More specifically, it is for people contributing to the standard +documentation and developing additional documents using the same tools as the +standard documents. This guide will be less useful for authors using the Python +documentation tools for topics other than Python, and less useful still for +authors not using the tools at all.

      +

      If your interest is in contributing to the Python documentation, but you don’t +have the time or inclination to learn reStructuredText and the markup structures +documented here, there’s a welcoming place for you among the Python contributors +as well. Any time you feel that you can clarify existing documentation or +provide documentation that’s missing, the existing documentation team will +gladly work with you to integrate your text, dealing with the markup for you. +Please don’t let the material in this document stand between the documentation +and your desire to help out!

      +
      +
      +

      8.2. Style guide

      +
      +

      8.2.1. Use of whitespace

      +

      All reST files use an indentation of 3 spaces; no tabs are allowed. The +maximum line length is 80 characters for normal text, but tables, deeply +indented code samples and long links may extend beyond that. Code example +bodies should use normal Python 4-space indentation.

      +

      Make generous use of blank lines where applicable; they help grouping things +together.

      +

      A sentence-ending period may be followed by one or two spaces; while reST +ignores the second space, it is customarily put in by some users, for example +to aid Emacs’ auto-fill mode.

      +
      +
      +

      8.2.2. Footnotes

      +

      Footnotes are generally discouraged, though they may be used when they are the +best way to present specific information. When a footnote reference is added at +the end of the sentence, it should follow the sentence-ending punctuation. The +reST markup should appear something like this:

      +
      This sentence has a footnote reference. [#]_ This is the next sentence.
+
      +
      +

      Footnotes should be gathered at the end of a file, or if the file is very long, +at the end of a section. The docutils will automatically create backlinks to +the footnote reference.

      +

      Footnotes may appear in the middle of sentences where appropriate.

      +
      +
      +

      8.2.3. Capitalization

      +
      +

      Sentence case

      +

      Sentence case is a set of capitalization rules used in English +sentences: the first word is always capitalized and other words are +only capitalized if there is a specific rule requiring it.

      +
      +

      In the Python documentation, the use of sentence case in section titles is +preferable, but consistency within a unit is more important than +following this rule. If you add a section to a chapter where most +sections are in title case, you can either convert all titles to +sentence case or use the dominant style in the new section title.

      +

      Sentences that start with a word for which specific rules require +starting it with a lower case letter should be avoided.

      +
      +

      Note

      +

      Sections that describe a library module often have titles in the +form of “modulename — Short description of the module.” In this +case, the description should be capitalized as a stand-alone +sentence.

      +
      +

      Many special names are used in the Python documentation, including the names of +operating systems, programming languages, standards bodies, and the like. Most +of these entities are not assigned any special markup, but the preferred +spellings are given here to aid authors in maintaining the consistency of +presentation in the Python documentation.

      +

      Other terms and words deserve special mention as well; these conventions should +be used to ensure consistency throughout the documentation:

      +
      +
      CPU
      +
      For “central processing unit.” Many style guides say this should be +spelled out on the first use (and if you must use it, do so!). For +the Python documentation, this abbreviation should be avoided since +there’s no reasonable way to predict which occurrence will be the +first seen by the reader. It is better to use the word “processor” +instead.
      +
      POSIX
      +
      The name assigned to a particular group of standards. This is always +uppercase.
      +
      Python
      +
      The name of our favorite programming language is always capitalized.
      +
      reST
      +
      For “reStructuredText,” an easy to read, plaintext markup syntax +used to produce Python documentation. When spelled out, it is +always one word and both forms start with a lower case ‘r’.
      +
      Unicode
      +
      The name of a character coding system. This is always written +capitalized.
      +
      Unix
      +
      The name of the operating system developed at AT&T Bell Labs in the early +1970s.
      +
      +
      +
      +

      8.2.4. Affirmative Tone

      +

      The documentation focuses on affirmatively stating what the language does and +how to use it effectively.

      +

      Except for certain security risks or segfault risks, the docs should avoid +wording along the lines of “feature x is dangerous” or “experts only”. These +kinds of value judgments belong in external blogs and wikis, not in the core +documentation.

      +

      Bad example (creating worry in the mind of a reader):

      +
      +
      Warning: failing to explicitly close a file could result in lost data or +excessive resource consumption. Never rely on reference counting to +automatically close a file.
      +

      Good example (establishing confident knowledge in the effective use of the language):

      +
      +
      A best practice for using files is use a try/finally pair to explicitly +close a file after it is used. Alternatively, using a with-statement can +achieve the same effect. This assures that files are flushed and file +descriptor resources are released in a timely manner.
      +
      +
      +

      8.2.5. Economy of Expression

      +

      More documentation is not necessarily better documentation. Err on the side +of being succinct.

      +

      It is an unfortunate fact that making documentation longer can be an impediment +to understanding and can result in even more ways to misread or misinterpret the +text. Long descriptions full of corner cases and caveats can create the +impression that a function is more complex or harder to use than it actually is.

      +
      +
      +

      8.2.6. Security Considerations (and Other Concerns)

      +

      Some modules provided with Python are inherently exposed to security issues +(e.g. shell injection vulnerabilities) due to the purpose of the module +(e.g. ssl). Littering the documentation of these modules with red +warning boxes for problems that are due to the task at hand, rather than +specifically to Python’s support for that task, doesn’t make for a good +reading experience.

      +

      Instead, these security concerns should be gathered into a dedicated +“Security Considerations” section within the module’s documentation, and +cross-referenced from the documentation of affected interfaces with a note +similar to "Please refer to the :ref:`security-considerations` section +for important information on how to avoid common mistakes.".

      +

      Similarly, if there is a common error that affects many interfaces in a +module (e.g. OS level pipe buffers filling up and stalling child processes), +these can be documented in a “Common Errors” section and cross-referenced +rather than repeated for every affected interface.

      +
      +
      +

      8.2.7. Code Examples

      +

      Short code examples can be a useful adjunct to understanding. Readers can often +grasp a simple example more quickly than they can digest a formal description in +prose.

      +

      People learn faster with concrete, motivating examples that match the context of +a typical use case. For instance, the str.rpartition() method is better +demonstrated with an example splitting the domain from a URL than it would be +with an example of removing the last word from a line of Monty Python dialog.

      +

      The ellipsis for the sys.ps2 secondary interpreter prompt should only be +used sparingly, where it is necessary to clearly differentiate between input +lines and output lines. Besides contributing visual clutter, it makes it +difficult for readers to cut-and-paste examples so they can experiment with +variations.

      +
      +
      +

      8.2.8. Code Equivalents

      +

      Giving pure Python code equivalents (or approximate equivalents) can be a useful +adjunct to a prose description. A documenter should carefully weigh whether the +code equivalent adds value.

      +

      A good example is the code equivalent for all(). The short 4-line code +equivalent is easily digested; it re-emphasizes the early-out behavior; and it +clarifies the handling of the corner-case where the iterable is empty. In +addition, it serves as a model for people wanting to implement a commonly +requested alternative where all() would return the specific object +evaluating to False whenever the function terminates early.

      +

      A more questionable example is the code for itertools.groupby(). Its code +equivalent borders on being too complex to be a quick aid to understanding. +Despite its complexity, the code equivalent was kept because it serves as a +model to alternative implementations and because the operation of the “grouper” +is more easily shown in code than in English prose.

      +

      An example of when not to use a code equivalent is for the oct() function. +The exact steps in converting a number to octal doesn’t add value for a user +trying to learn what the function does.

      +
      +
      +

      8.2.9. Audience

      +

      The tone of the tutorial (and all the docs) needs to be respectful of the +reader’s intelligence. Don’t presume that the readers are stupid. Lay out the +relevant information, show motivating use cases, provide glossary links, and do +your best to connect-the-dots, but don’t talk down to them or waste their time.

      +

      The tutorial is meant for newcomers, many of whom will be using the tutorial to +evaluate the language as a whole. The experience needs to be positive and not +leave the reader with worries that something bad will happen if they make a +misstep. The tutorial serves as guide for intelligent and curious readers, +saving details for the how-to guides and other sources.

      +

      Be careful accepting requests for documentation changes from the rare but vocal +category of reader who is looking for vindication for one of their programming +errors (“I made a mistake, therefore the docs must be wrong ...”). Typically, +the documentation wasn’t consulted until after the error was made. It is +unfortunate, but typically no documentation edit would have saved the user from +making false assumptions about the language (“I was surprised by ...”).

      +
      +
      +
      +

      8.3. reStructuredText Primer

      +

      This section is a brief introduction to reStructuredText (reST) concepts and +syntax, intended to provide authors with enough information to author documents +productively. Since reST was designed to be a simple, unobtrusive markup +language, this will not take too long.

      +
      +

      See also

      +

      The authoritative reStructuredText User +Documentation.

      +
      +
      +

      8.3.1. Paragraphs

      +

      The paragraph is the most basic block in a reST document. Paragraphs are simply +chunks of text separated by one or more blank lines. As in Python, indentation +is significant in reST, so all lines of the same paragraph must be left-aligned +to the same level of indentation.

      +
      +
      +

      8.3.2. Inline markup

      +

      The standard reST inline markup is quite simple: use

      +
        +
      • one asterisk: *text* for emphasis (italics),
        • +
      • two asterisks: **text** for strong emphasis (boldface), and
        • +
      • backquotes: ``text`` for code samples.
        • +
      +

      If asterisks or backquotes appear in running text and could be confused with +inline markup delimiters, they have to be escaped with a backslash.

      +

      Be aware of some restrictions of this markup:

      +
        +
      • it may not be nested,
        • +
      • content may not start or end with whitespace: * text* is wrong,
        • +
      • it must be separated from surrounding text by non-word characters. Use a +backslash escaped space to work around that: thisis\ *one*\ word.
        • +
      +

      These restrictions may be lifted in future versions of the docutils.

      +

      reST also allows for custom “interpreted text roles”’, which signify that the +enclosed text should be interpreted in a specific way. Sphinx uses this to +provide semantic markup and cross-referencing of identifiers, as described in +the appropriate section. The general syntax is :rolename:`content`.

      +
      +
      +

      8.3.3. Lists and Quotes

      +

      List markup is natural: just place an asterisk at the start of a paragraph and +indent properly. The same goes for numbered lists; they can also be +automatically numbered using a # sign:

      +
      * This is a bulleted list.
+* It has two items, the second
+  item uses two lines.
+
+1. This is a numbered list.
+2. It has two items too.
+
+#. This is a numbered list.
+#. It has two items too.
+
      +
      +

      Nested lists are possible, but be aware that they must be separated from the +parent list items by blank lines:

      +
      * this is
+* a list
+
+  * with a nested list
+  * and some subitems
+
+* and here the parent list continues
+
      +
      +

      Definition lists are created as follows:

      +
      term (up to a line of text)
+   Definition of the term, which must be indented
+
+   and can even consist of multiple paragraphs
+
+next term
+   Description.
+
      +
      +

      Paragraphs are quoted by just indenting them more than the surrounding +paragraphs.

      +
      +
      +

      8.3.4. Source Code

      +

      Literal code blocks are introduced by ending a paragraph with the special marker +::. The literal block must be indented:

      +
      This is a normal text paragraph. The next paragraph is a code sample::
+
+   It is not processed in any way, except
+   that the indentation is removed.
+
+   It can span multiple lines.
+
+This is a normal text paragraph again.
+
      +
      +

      The handling of the :: marker is smart:

      +
        +
      • If it occurs as a paragraph of its own, that paragraph is completely left +out of the document.
        • +
      • If it is preceded by whitespace, the marker is removed.
        • +
      • If it is preceded by non-whitespace, the marker is replaced by a single +colon.
        • +
      +

      That way, the second sentence in the above example’s first paragraph would be +rendered as “The next paragraph is a code sample:”.

      +
      + +
      +

      8.3.6. Sections

      +

      Section headers are created by underlining (and optionally overlining) the +section title with a punctuation character, at least as long as the text:

      +
      =================
+This is a heading
+=================
+
      +
      +

      Normally, there are no heading levels assigned to certain characters as the +structure is determined from the succession of headings. However, for the +Python documentation, here is a suggested convention:

      +
        +
      • # with overline, for parts
        • +
      • * with overline, for chapters
        • +
      • =, for sections
        • +
      • -, for subsections
        • +
      • ^, for subsubsections
        • +
      • ", for paragraphs
        • +
      +
      +
      +

      8.3.7. Explicit Markup

      +

      “Explicit markup” is used in reST for most constructs that need special +handling, such as footnotes, specially-highlighted paragraphs, comments, and +generic directives.

      +

      An explicit markup block begins with a line starting with .. followed by +whitespace and is terminated by the next paragraph at the same level of +indentation. (There needs to be a blank line between explicit markup and normal +paragraphs. This may all sound a bit complicated, but it is intuitive enough +when you write it.)

      +
      +
      +

      8.3.8. Directives

      +

      A directive is a generic block of explicit markup. Besides roles, it is one of +the extension mechanisms of reST, and Sphinx makes heavy use of it.

      +

      Basically, a directive consists of a name, arguments, options and content. (Keep +this terminology in mind, it is used in the next chapter describing custom +directives.) Looking at this example,

      +
      .. function:: foo(x)
+              foo(y, z)
+   :bar: no
+
+   Return a line of text input from the user.
+
      +
      +

      function is the directive name. It is given two arguments here, the +remainder of the first line and the second line, as well as one option bar +(as you can see, options are given in the lines immediately following the +arguments and indicated by the colons).

      +

      The directive content follows after a blank line and is indented relative to the +directive start.

      +
      +
      +

      8.3.9. Footnotes

      +

      For footnotes, use [#]_ to mark the footnote location, and add the footnote +body at the bottom of the document after a “Footnotes” rubric heading, like so:

      +
      Lorem ipsum [#]_ dolor sit amet ... [#]_
+
+.. rubric:: Footnotes
+
+.. [#] Text of the first footnote.
+.. [#] Text of the second footnote.
+
      +
      +

      You can also explicitly number the footnotes for better context.

      +
      +
      +

      8.3.10. Comments

      +

      Every explicit markup block which isn’t a valid markup construct (like the +footnotes above) is regarded as a comment.

      +
      +
      +

      8.3.11. Source encoding

      +

      Since the easiest way to include special characters like em dashes or copyright +signs in reST is to directly write them as Unicode characters, one has to +specify an encoding:

      +

      All Python documentation source files must be in UTF-8 encoding, and the HTML +documents written from them will be in that encoding as well.

      +
      +
      +

      8.3.12. Gotchas

      +

      There are some problems one commonly runs into while authoring reST documents:

      +
        +
      • Separation of inline markup: As said above, inline markup spans must be +separated from the surrounding text by non-word characters, you have to use +an escaped space to get around that.
        • +
      +
      +
      +
      +

      8.4. Additional Markup Constructs

      +

      Sphinx adds a lot of new directives and interpreted text roles to standard reST +markup. This section contains the reference material for these facilities. +Documentation for “standard” reST constructs is not included here, though +they are used in the Python documentation.

      +
      +

      Note

      +

      This is just an overview of Sphinx’ extended markup capabilities; full +coverage can be found in its own documentation.

      +
      +
      +

      8.4.1. Meta-information markup

      +
      +
      +sectionauthor
      +

      Identifies the author of the current section. The argument should include +the author’s name such that it can be used for presentation (though it isn’t) +and email address. The domain name portion of the address should be lower +case. Example:

      +
      .. sectionauthor:: Guido van Rossum <guido@python.org>
+
      +
      +

      Currently, this markup isn’t reflected in the output in any way, but it helps +keep track of contributions.

      +
      + +
      +
      +

      8.4.2. Module-specific markup

      +

      The markup described in this section is used to provide information about a +module being documented. Each module should be documented in its own file. +Normally this markup appears after the title heading of that file; a typical +file might start like this:

      +
      :mod:`parrot` -- Dead parrot access
+===================================
+
+.. module:: parrot
+   :platform: Unix, Windows
+   :synopsis: Analyze and reanimate dead parrots.
+.. moduleauthor:: Eric Cleese <eric@python.invalid>
+.. moduleauthor:: John Idle <john@python.invalid>
+
      +
      +

      As you can see, the module-specific markup consists of two directives, the +module directive and the moduleauthor directive.

      +
      +
      +module
      +

      This directive marks the beginning of the description of a module, package, +or submodule. The name should be fully qualified (i.e. including the +package name for submodules).

      +

      The platform option, if present, is a comma-separated list of the +platforms on which the module is available (if it is available on all +platforms, the option should be omitted). The keys are short identifiers; +examples that are in use include “IRIX”, “Mac”, “Windows”, and “Unix”. It is +important to use a key which has already been used when applicable.

      +

      The synopsis option should consist of one sentence describing the +module’s purpose – it is currently only used in the Global Module Index.

      +

      The deprecated option can be given (with no value) to mark a module as +deprecated; it will be designated as such in various locations then.

      +
      + +
      +
      +moduleauthor
      +

      The moduleauthor directive, which can appear multiple times, names the +authors of the module code, just like sectionauthor names the author(s) +of a piece of documentation. It too does not result in any output currently.

      +
      + +
      +

      Note

      +

      It is important to make the section title of a module-describing file +meaningful since that value will be inserted in the table-of-contents trees +in overview files.

      +
      +
      +
      +

      8.4.3. Information units

      +

      There are a number of directives used to describe specific features provided by +modules. Each directive requires one or more signatures to provide basic +information about what is being described, and the content should be the +description. The basic version makes entries in the general index; if no index +entry is desired, you can give the directive option flag :noindex:. The +following example shows all of the features of this directive type:

      +
      .. function:: spam(eggs)
+              ham(eggs)
+   :noindex:
+
+   Spam or ham the foo.
+
      +
      +

      The signatures of object methods or data attributes should not include the +class name, but be nested in a class directive. The generated files will +reflect this nesting, and the target identifiers (for HTML output) will use +both the class and method name, to enable consistent cross-references. If you +describe methods belonging to an abstract protocol such as context managers, +use a class directive with a (pseudo-)type name too to make the +index entries more informative.

      +

      The directives are:

      +
      +
      +c:function
      +

      Describes a C function. The signature should be given as in C, e.g.:

      +
      .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
      +
      +

      This is also used to describe function-like preprocessor macros. The names +of the arguments should be given so they may be used in the description.

      +

      Note that you don’t have to backslash-escape asterisks in the signature, +as it is not parsed by the reST inliner.

      +
      + +
      +
      +c:member
      +

      Describes a C struct member. Example signature:

      +
      .. c:member:: PyObject* PyTypeObject.tp_bases
+
      +
      +

      The text of the description should include the range of values allowed, how +the value should be interpreted, and whether the value can be changed. +References to structure members in text should use the member role.

      +
      + +
      +
      +c:macro
      +

      Describes a “simple” C macro. Simple macros are macros which are used +for code expansion, but which do not take arguments so cannot be described as +functions. This is not to be used for simple constant definitions. Examples +of its use in the Python documentation include PyObject_HEAD and +Py_BEGIN_ALLOW_THREADS.

      +
      + +
      +
      +c:type
      +

      Describes a C type. The signature should just be the type name.

      +
      + +
      +
      +c:var
      +

      Describes a global C variable. The signature should include the type, such +as:

      +
      .. cvar:: PyObject* PyClass_Type
+
      +
      +
      + +
      +
      +data
      +

      Describes global data in a module, including both variables and values used +as “defined constants.” Class and object attributes are not documented +using this directive.

      +
      + +
      +
      +exception
      +

      Describes an exception class. The signature can, but need not include +parentheses with constructor arguments.

      +
      + +
      +
      +function
      +

      Describes a module-level function. The signature should include the +parameters, enclosing optional parameters in brackets. Default values can be +given if it enhances clarity. For example:

      +
      .. function:: repeat([repeat=3[, number=1000000]])
+
      +
      +

      Object methods are not documented using this directive. Bound object methods +placed in the module namespace as part of the public interface of the module +are documented using this, as they are equivalent to normal functions for +most purposes.

      +

      The description should include information about the parameters required and +how they are used (especially whether mutable objects passed as parameters +are modified), side effects, and possible exceptions. A small example may be +provided.

      +
      + +
      +
      +decorator
      +

      Describes a decorator function. The signature should not represent the +signature of the actual function, but the usage as a decorator. For example, +given the functions

      +
      def removename(func):
+    func.__name__ = ''
+    return func
+
+def setnewname(name):
+    def decorator(func):
+        func.__name__ = name
+        return func
+    return decorator
+
      +
      +

      the descriptions should look like this:

      +
      .. decorator:: removename
+
+   Remove name of the decorated function.
+
+.. decorator:: setnewname(name)
+
+   Set name of the decorated function to *name*.
+
      +
      +

      There is no deco role to link to a decorator that is marked up with +this directive; rather, use the :func: role.

      +
      + +
      +
      +class
      +

      Describes a class. The signature can include parentheses with parameters +which will be shown as the constructor arguments.

      +
      + +
      +
      +attribute
      +

      Describes an object data attribute. The description should include +information about the type of the data to be expected and whether it may be +changed directly. This directive should be nested in a class directive, +like in this example:

      +
      .. class:: Spam
+
+      Description of the class.
+
+      .. data:: ham
+
+         Description of the attribute.
+
      +
      +

      If is also possible to document an attribute outside of a class directive, +for example if the documentation for different attributes and methods is +split in multiple sections. The class name should then be included +explicitly:

      +
      .. data:: Spam.eggs
+
      +
      +
      + +
      +
      +method
      +

      Describes an object method. The parameters should not include the self +parameter. The description should include similar information to that +described for function. This directive should be nested in a class +directive, like in the example above.

      +
      + +
      +
      +decoratormethod
      +

      Same as decorator, but for decorators that are methods.

      +

      Refer to a decorator method using the :meth: role.

      +
      + +
      +
      +opcode
      +

      Describes a Python bytecode instruction.

      +
      + +
      +
      +cmdoption
      +

      Describes a Python command line option or switch. Option argument names +should be enclosed in angle brackets. Example:

      +
      .. cmdoption:: -m <module>
+
+   Run a module as a script.
+
      +
      +
      + +
      +
      +envvar
      +

      Describes an environment variable that Python uses or defines.

      +
      + +

      There is also a generic version of these directives:

      +
      +
      +describe
      +

      This directive produces the same formatting as the specific ones explained +above but does not create index entries or cross-referencing targets. It is +used, for example, to describe the directives in this document. Example:

      +
      .. describe:: opcode
+
+   Describes a Python bytecode instruction.
+
      +
      +
      + +
      +
      +

      8.4.4. Showing code examples

      +

      Examples of Python source code or interactive sessions are represented using +standard reST literal blocks. They are started by a :: at the end of the +preceding paragraph and delimited by indentation.

      +

      Representing an interactive session requires including the prompts and output +along with the Python code. No special markup is required for interactive +sessions. After the last line of input or output presented, there should not be +an “unused” primary prompt; this is an example of what not to do:

      +
      >>> 1 + 1
+2
+>>>
+
      +
      +

      Syntax highlighting is handled in a smart way:

      +
        +

      • There is a “highlighting language” for each source file. Per default, +this is 'python' as the majority of files will have to highlight Python +snippets.

        +
        • +

      • Within Python highlighting mode, interactive sessions are recognized +automatically and highlighted appropriately.

        +
        • +

      • The highlighting language can be changed using the highlightlang +directive, used as follows:

        +
        .. highlightlang:: c
+
        +
        +

        This language is used until the next highlightlang directive is +encountered.

        +
        • +

      • The code-block directive can be used to specify the highlight language +of a single code block, e.g.:

        +
        .. code-block:: c
+
+   #include <stdio.h>
+
+   void main() {
+       printf("Hello world!\n");
+   }
+
        +
        +
        • +

      • The values normally used for the highlighting language are:

        +
          +
        • python (the default)
          • +
        • c
          • +
        • rest
          • +
        • none (no highlighting)
          • +
        +
        • +

      • If highlighting with the current language fails, the block is not highlighted +in any way.

        +
        • +
      +

      Longer displays of verbatim text may be included by storing the example text in +an external file containing only plain text. The file may be included using the +literalinclude directive. [1] For example, to include the Python source file +example.py, use:

      +
      .. literalinclude:: example.py
+
      +
      +

      The file name is relative to the current file’s path. Documentation-specific +include files should be placed in the Doc/includes subdirectory.

      +
      +
      +

      8.4.5. Inline markup

      +

      As said before, Sphinx uses interpreted text roles to insert semantic markup in +documents.

      +

      Names of local variables, such as function/method arguments, are an exception, +they should be marked simply with *var*.

      +

      For all other roles, you have to write :rolename:`content`.

      +

      There are some additional facilities that make cross-referencing roles more +versatile:

      +
        +

      • You may supply an explicit title and reference target, like in reST direct +hyperlinks: :role:`title <target>` will refer to target, but the link +text will be title.

        +
        • +

      • If you prefix the content with !, no reference/hyperlink will be created.

        +
        • +

      • For the Python object roles, if you prefix the content with ~, the link +text will only be the last component of the target. For example, +:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only +display get as the link text.

        +

        In HTML output, the link’s title attribute (that is e.g. shown as a +tool-tip on mouse-hover) will always be the full target name.

        +
        • +
      +

      The following roles refer to objects in modules and are possibly hyperlinked if +a matching identifier is found:

      +
      +
      +mod
      +

      The name of a module; a dotted name may be used. This should also be used for +package names.

      +
      + +
      +
      +func
      +

      The name of a Python function; dotted names may be used. The role text +should not include trailing parentheses to enhance readability. The +parentheses are stripped when searching for identifiers.

      +
      + +
      +
      +data
      +

      The name of a module-level variable or constant.

      +
      + +
      +
      +const
      +

      The name of a “defined” constant. This may be a C-language #define +or a Python variable that is not intended to be changed.

      +
      + +
      +
      +class
      +

      A class name; a dotted name may be used.

      +
      + +
      +
      +meth
      +

      The name of a method of an object. The role text should include the type +name and the method name. A dotted name may be used.

      +
      + +
      +
      +attr
      +

      The name of a data attribute of an object.

      +
      + +
      +
      +exc
      +

      The name of an exception. A dotted name may be used.

      +
      + +

      The name enclosed in this markup can include a module name and/or a class name. +For example, :func:`filter` could refer to a function named filter in +the current module, or the built-in function of that name. In contrast, +:func:`foo.filter` clearly refers to the filter function in the foo +module.

      +

      Normally, names in these roles are searched first without any further +qualification, then with the current module name prepended, then with the +current module and class name (if any) prepended. If you prefix the name with a +dot, this order is reversed. For example, in the documentation of the +codecs module, :func:`open` always refers to the built-in function, +while :func:`.open` refers to codecs.open().

      +

      A similar heuristic is used to determine whether the name is an attribute of +the currently documented class.

      +

      The following roles create cross-references to C-language constructs if they +are defined in the API documentation:

      +
      +
      +c:data
      +

      The name of a C-language variable.

      +
      + +
      +
      +c:func
      +

      The name of a C-language function. Should include trailing parentheses.

      +
      + +
      +
      +c:macro
      +

      The name of a “simple” C macro, as defined above.

      +
      + +
      +
      +c:type
      +

      The name of a C-language type.

      +
      + +
      +
      +c:member
      +

      The name of a C type member, as defined above.

      +
      + +

      The following role does possibly create a cross-reference, but does not refer +to objects:

      +
      +
      +token
      +

      The name of a grammar token (used in the reference manual to create links +between production displays).

      +
      + +

      The following role creates a cross-reference to the term in the glossary:

      +
      +
      +term
      +

      Reference to a term in the glossary. The glossary is created using the +glossary directive containing a definition list with terms and +definitions. It does not have to be in the same file as the term +markup, in fact, by default the Python docs have one global glossary +in the glossary.rst file.

      +

      If you use a term that’s not explained in a glossary, you’ll get a warning +during build.

      +
      + +
      +

      The following roles don’t do anything special except formatting the text +in a different style:

      +
      +
      +command
      +

      The name of an OS-level command, such as rm.

      +
      + +
      +
      +dfn
      +

      Mark the defining instance of a term in the text. (No index entries are +generated.)

      +
      + +
      +
      +envvar
      +

      An environment variable. Index entries are generated.

      +
      + +
      +
      +file
      +

      The name of a file or directory. Within the contents, you can use curly +braces to indicate a “variable” part, for example:

      +
      ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
+
      +
      +

      In the built documentation, the x will be displayed differently to +indicate that it is to be replaced by the Python minor version.

      +
      + +
      +
      +guilabel
      +

      Labels presented as part of an interactive user interface should be marked +using guilabel. This includes labels from text-based interfaces such as +those created using curses or other text-based libraries. Any label +used in the interface should be marked with this role, including button +labels, window titles, field names, menu and menu selection names, and even +values in selection lists.

      +
      + +
      +
      +kbd
      +

      Mark a sequence of keystrokes. What form the key sequence takes may depend +on platform- or application-specific conventions. When there are no relevant +conventions, the names of modifier keys should be spelled out, to improve +accessibility for new users and non-native speakers. For example, an +xemacs key sequence may be marked like :kbd:`C-x C-f`, but without +reference to a specific application or platform, the same sequence should be +marked as :kbd:`Control-x Control-f`.

      +
      + +
      +
      +keyword
      +

      The name of a Python keyword. Using this role will generate a link to the +documentation of the keyword. True, False and None do not use +this role, but simple code markup (``True``), given that they’re +fundamental to the language and should be known to any programmer.

      +
      + +
      +
      +mailheader
      +

      The name of an RFC 822-style mail header. This markup does not imply that +the header is being used in an email message, but can be used to refer to any +header of the same “style.” This is also used for headers defined by the +various MIME specifications. The header name should be entered in the same +way it would normally be found in practice, with the camel-casing conventions +being preferred where there is more than one common usage. For example: +:mailheader:`Content-Type`.

      +
      + +
      +
      +makevar
      +

      The name of a make variable.

      +
      + +
      +
      +manpage
      +

      A reference to a Unix manual page including the section, +e.g. :manpage:`ls(1)`.

      +
      + +
      +
      +menuselection
      +

      Menu selections should be marked using the menuselection role. This is +used to mark a complete sequence of menu selections, including selecting +submenus and choosing a specific operation, or any subsequence of such a +sequence. The names of individual selections should be separated by +-->.

      +

      For example, to mark the selection “Start > Programs”, use this markup:

      +
      :menuselection:`Start --> Programs`
+
      +
      +

      When including a selection that includes some trailing indicator, such as the +ellipsis some operating systems use to indicate that the command opens a +dialog, the indicator should be omitted from the selection name.

      +
      + +
      +
      +mimetype
      +

      The name of a MIME type, or a component of a MIME type (the major or minor +portion, taken alone).

      +
      + +
      +
      +newsgroup
      +

      The name of a Usenet newsgroup.

      +
      + +
      +
      +option
      +

      A command-line option of Python. The leading hyphen(s) must be included. +If a matching cmdoption directive exists, it is linked to. For options +of other programs or scripts, use simple ``code`` markup.

      +
      + +
      +
      +program
      +

      The name of an executable program. This may differ from the file name for +the executable for some platforms. In particular, the .exe (or other) +extension should be omitted for Windows programs.

      +
      + +
      +
      +regexp
      +

      A regular expression. Quotes should not be included.

      +
      + +
      +
      +samp
      +

      A piece of literal text, such as code. Within the contents, you can use +curly braces to indicate a “variable” part, as in :file:.

      +

      If you don’t need the “variable part” indication, use the standard +``code`` instead.

      +
      + +

      The following roles generate external links:

      +
      +
      +pep
      +

      A reference to a Python Enhancement Proposal. This generates appropriate +index entries. The text “PEP number” is generated; in the HTML output, +this text is a hyperlink to an online copy of the specified PEP.

      +
      + +
      +
      +rfc
      +

      A reference to an Internet Request for Comments. This generates appropriate +index entries. The text “RFC number” is generated; in the HTML output, +this text is a hyperlink to an online copy of the specified RFC.

      +
      + +

      Note that there are no special roles for including hyperlinks as you can use +the standard reST markup for that purpose.

      +
      +
      +

      8.4.6. Cross-linking markup

      +

      To support cross-referencing to arbitrary sections in the documentation, the +standard reST labels are “abused” a bit: Every label must precede a section +title; and every label name must be unique throughout the entire documentation +source.

      +

      You can then reference to these sections using the :ref:`label-name` role.

      +

      Example:

      +
      .. _my-reference-label:
+
+Section to cross-reference
+--------------------------
+
+This is the text of the section.
+
+It refers to the section itself, see :ref:`my-reference-label`.
+
      +
      +

      The :ref: invocation is replaced with the section title.

      +

      Alternatively, you can reference any label (not just section titles) +if you provide the link text :ref:`link text <reference-label>`.

      +
      +
      +

      8.4.7. Paragraph-level markup

      +

      These directives create short paragraphs and can be used inside information +units as well as normal text:

      +
      +
      +note
      +

      An especially important bit of information about an API that a user should be +aware of when using whatever bit of API the note pertains to. The content of +the directive should be written in complete sentences and include all +appropriate punctuation.

      +

      Example:

      +
      .. note::
+
+   This function is not suitable for sending spam e-mails.
+
      +
      +
      + +
      +
      +warning
      +

      An important bit of information about an API that a user should be aware of +when using whatever bit of API the warning pertains to. The content of the +directive should be written in complete sentences and include all appropriate +punctuation. In the interest of not scaring users away from pages filled +with warnings, this directive should only be chosen over note for +information regarding the possibility of crashes, data loss, or security +implications.

      +
      + +
      +
      +versionadded
      +

      This directive documents the version of Python which added the described +feature, or a part of it, to the library or C API. When this applies to an +entire module, it should be placed at the top of the module section before +any prose.

      +

      The first argument must be given and is the version in question; if the +addition is only part of the described API element, you should add a second +argument consisting of a brief explanation of the change.

      +

      Example:

      +
      .. versionadded:: 3.1
+   The *spam* parameter.
+
      +
      +

      Note that there must be no blank line between the directive head and the +explanation; this is to make these blocks visually continuous in the markup.

      +
      + +
      +
      +versionchanged
      +

      Similar to versionadded, but describes when and what changed in the named +feature in some way (changed side effects, platform support, etc.). This one +must have the second argument (explanation of the change).

      +
      + +
      +
      +
      +impl-detail
      +

      This directive is used to mark CPython-specific information. Use either with +a block content or a single sentence as an argument, i.e. either

      +
      .. impl-detail::
+
+   This describes some implementation detail.
+
+   More explanation.
+
      +
      +

      or

      +
      .. impl-detail:: This shortly mentions an implementation detail.
+
      +
      +

      “CPython implementation detail:” is automatically prepended to the +content.

      +
      + +
      +
      +seealso
      +

      Many sections include a list of references to module documentation or +external documents. These lists are created using the seealso directive.

      +

      The seealso directive is typically placed in a section just before any +sub-sections. For the HTML output, it is shown boxed off from the main flow +of the text.

      +

      The content of the seealso directive should be a reST definition list. +Example:

      +
      .. seealso::
+
+   Module :mod:`zipfile`
+      Documentation of the :mod:`zipfile` standard module.
+
+   `GNU tar manual, Basic Tar Format <http://link>`_
+      Documentation for tar archive files, including GNU tar extensions.
+
      +
      +
      + +
      +
      +rubric
      +

      This directive creates a paragraph heading that is not used to create a +table of contents node. It is currently used for the “Footnotes” caption.

      +
      + +
      +
      +centered
      +

      This directive creates a centered boldfaced paragraph. Use it as follows:

      +
      .. centered::
+
+   Paragraph contents.
+
      +
      +
      + +
      +
      +

      8.4.8. Table-of-contents markup

      +

      Since reST does not have facilities to interconnect several documents, or split +documents into multiple output files, Sphinx uses a custom directive to add +relations between the single files the documentation is made of, as well as +tables of contents. The toctree directive is the central element.

      +
      +
      +toctree
      +

      This directive inserts a “TOC tree” at the current location, using the +individual TOCs (including “sub-TOC trees”) of the files given in the +directive body. A numeric maxdepth option may be given to indicate the +depth of the tree; by default, all levels are included.

      +

      Consider this example (taken from the library reference index):

      +
      .. toctree::
+   :maxdepth: 2
+
+   intro
+   strings
+   datatypes
+   numeric
+   (many more files listed here)
+
      +
      +

      This accomplishes two things:

      +
        +
      • Tables of contents from all those files are inserted, with a maximum depth +of two, that means one nested heading. toctree directives in those +files are also taken into account.
        • +
      • Sphinx knows that the relative order of the files intro, +strings and so forth, and it knows that they are children of the +shown file, the library index. From this information it generates “next +chapter”, “previous chapter” and “parent chapter” links.
        • +
      +

      In the end, all files included in the build process must occur in one +toctree directive; Sphinx will emit a warning if it finds a file that is +not included, because that means that this file will not be reachable through +standard navigation.

      +

      The special file contents.rst at the root of the source directory is the +“root” of the TOC tree hierarchy; from it the “Contents” page is generated.

      +
      + +
      +
      +

      8.4.9. Index-generating markup

      +

      Sphinx automatically creates index entries from all information units (like +functions, classes or attributes) like discussed before.

      +

      However, there is also an explicit directive available, to make the index more +comprehensive and enable index entries in documents where information is not +mainly contained in information units, such as the language reference.

      +

      The directive is index and contains one or more index entries. Each entry +consists of a type and a value, separated by a colon.

      +

      For example:

      +
      .. index::
+   single: execution; context
+   module: __main__
+   module: sys
+   triple: module; search; path
+
      +
      +

      This directive contains five entries, which will be converted to entries in the +generated index which link to the exact location of the index statement (or, in +case of offline media, the corresponding page number).

      +

      The possible entry types are:

      +
      +
      single
      +
      Creates a single index entry. Can be made a subentry by separating the +subentry text with a semicolon (this notation is also used below to describe +what entries are created).
      +
      pair
      +
      pair: loop; statement is a shortcut that creates two index entries, +namely loop; statement and statement; loop.
      +
      triple
      +
      Likewise, triple: module; search; path is a shortcut that creates three +index entries, which are module; search path, search; path, module and +path; module search.
      +
      module, keyword, operator, object, exception, statement, builtin
      +
      These all create two index entries. For example, module: hashlib +creates the entries module; hashlib and hashlib; module. The +builtin entry type is slightly different in that “built-in function” is used +in place of “builtin” when creating the two entries.
      +
      +

      For index directives containing only “single” entries, there is a shorthand +notation:

      +
      .. index:: BNF, grammar, syntax, notation
+
      +
      +

      This creates four index entries.

      +
      +
      +

      8.4.10. Grammar production displays

      +

      Special markup is available for displaying the productions of a formal grammar. +The markup is simple and does not attempt to model all aspects of BNF (or any +derived forms), but provides enough to allow context-free grammars to be +displayed in a way that causes uses of a symbol to be rendered as hyperlinks to +the definition of the symbol. There is this directive:

      +
      +
      +productionlist
      +

      This directive is used to enclose a group of productions. Each production is +given on a single line and consists of a name, separated by a colon from the +following definition. If the definition spans multiple lines, each +continuation line must begin with a colon placed at the same column as in the +first line.

      +

      Blank lines are not allowed within productionlist directive arguments.

      +

      The definition can contain token names which are marked as interpreted text +(e.g. unaryneg ::= "-" `integer`) – this generates cross-references +to the productions of these tokens.

      +

      Note that no further reST parsing is done in the production, so that you +don’t have to escape * or | characters.

      +
      + +

      The following is an example taken from the Python Reference Manual:

      +
      .. productionlist::
+   try_stmt: try1_stmt | try2_stmt
+   try1_stmt: "try" ":" `suite`
+            : ("except" [`expression` ["," `target`]] ":" `suite`)+
+            : ["else" ":" `suite`]
+            : ["finally" ":" `suite`]
+   try2_stmt: "try" ":" `suite`
+            : "finally" ":" `suite`
+
      +
      +
      +
      +

      8.4.11. Substitutions

      +

      The documentation system provides three substitutions that are defined by default. +They are set in the build configuration file conf.py.

      +
      +
      +|release|
      +

      Replaced by the Python release the documentation refers to. This is the full +version string including alpha/beta/release candidate tags, e.g. 2.5.2b3.

      +
      + +
      +
      +|version|
      +

      Replaced by the Python version the documentation refers to. This consists +only of the major and minor version parts, e.g. 2.5, even for version +2.5.1.

      +
      + +
      +
      +|today|
      +

      Replaced by either today’s date, or the date set in the build configuration +file. Normally has the format April 14, 2007.

      +
      + +

      Footnotes

      + + + + + +
      [1]There is a standard .. include directive, but it raises errors if the +file is not found. This one only emits a warning.
      +
      +
      +
      +

      8.5. Building the documentation

      +

      The toolset used to build the docs is written in Python and is called Sphinx. +Sphinx is maintained separately and is not included in this tree. Also needed +are docutils, supplying the base markup that Sphinx uses; Jinja, a templating +engine; and optionally Pygments, a code highlighter.

      +

      To build the documentation, follow the instructions from one of the sections +below. You can view the documentation after building the HTML by pointing +a browser at the file Doc/build/html/index.html.

      +

      In the Python 2.7 and 3.3 branches, the Sphinx toolchain will be checked out +using Subversion from svn.python.org by the Makefile. This toolchain will +need an installed Python 2 to run.

      +

      In the Python 3.4 and later branches, you are expected to have installed a +recent version of Sphinx on your system, so that the Makefile can find the +sphinx-build command.

      +
      +

      8.5.1. Using make / make.bat

      +

      On Unix, run the following from the root of your repository clone:

      +
      cd Doc
+make html
+
      +
      +

      or alternatively make -C Doc html. This builds the output as HTML.

      +

      For Windows users there is a make.bat batchfile that tries to work like +make does.

      +

      Available make targets are:

      +
      +
        +

      • “html”, which builds standalone HTML files for offline viewing.

        +
        • +

      • “htmlhelp”, which builds HTML files and a HTML Help project file usable to +convert them into a single Compiled HTML (.chm) file – these are popular +under Microsoft Windows, but very handy on every platform.

        +

        To create the CHM file, you need to run the Microsoft HTML Help Workshop +over the generated project (.hhp) file.

        +
        • +

      • “latex”, which builds LaTeX source files as input to “pdflatex” to produce +PDF documents.

        +
        • +

      • “text”, which builds a plain text file for each source file.

        +
        • +

      • “linkcheck”, which checks all external references to see whether they are +broken, redirected or malformed, and outputs this information to stdout +as well as a plain-text (.txt) file.

        +
        • +

      • “changes”, which builds an overview over all versionadded/versionchanged/ +deprecated items in the current version. This is meant as a help for the +writer of the “What’s New” document.

        +
        • +

      • “coverage”, which builds a coverage overview for standard library modules +and C API.

        +
        • +

      • “pydoc-topics”, which builds a Python module containing a dictionary with +plain text documentation for the labels defined in +Doc/tools/sphinxext/pyspecific.py – pydoc needs these to show topic +and keyword help.

        +
        • +

      • “suspicious”, which checks the parsed markup for text that looks like +malformed and thus unconverted reST.

        +
        • +
      +
      +
      +
      +

      8.5.2. Without make

      +

      Install the Sphinx package and its dependencies from PyPI.

      +

      Then, from the Docs directory, run

      +
      sphinx-build -b<builder> . build/<builder>
+
      +
      +

      where <builder> is one of html, text, latex, or htmlhelp (for explanations +see the make targets above).

      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      7. Helping with Documentation

      +

      Next topic

      +

      9. Silence Warnings From the Test Suite

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/emacs.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/emacs.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,123 @@ + + + + + + + + 23. Emacs support — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      23. Emacs support

      +

      If you want to edit Python code in Emacs, you should download python-mode.el +and install it somewhere on your load-path. See the project page to download: +https://launchpad.net/python-mode

      +

      While Emacs comes with a python.el file, it is not recommended. +python-mode.el is maintained by core Python developers and is generally +considered more Python programmer friendly. For example, python-mode.el +includes a killer feature called pdbtrack which allows you to set a pdb +breakpoint in your code, run your program in an Emacs shell buffer, and do gud +style debugging when the breakpoint is hit.

      +

      python-mode.el is compatible with both GNU Emacs from the FSF, and XEmacs.

      +

      For more information and bug reporting, see the above project page. For help, +development, or discussions, see the python-mode mailing list: +http://mail.python.org/mailman/listinfo/python-mode

      +
      + + +
      +
      +
      +
      +
      +

      Previous topic

      +

      22. Experts Index

      +

      Next topic

      +

      24. gdb Support

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/experts.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/experts.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,1002 @@ + + + + + + + + 22. Experts Index — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      22. Experts Index

      +

      This document has tables that list Python Modules, Tools, Platforms and +Interest Areas and names for each item that indicate a maintainer or an +expert in the field. This list is intended to be used by issue submitters, +issue triage people, and other issue participants to find people to add to +the nosy list or to contact directly by email for help and decisions on +feature requests and bug fixes. People on this list may be asked to render +final judgement on a feature or bug. If no active maintainer is listed for +a given module, then questionable changes should go to python-dev, while +any other issues can and should be decided by any committer.

      +

      Unless a name is followed by a ‘*’, you should never assign an issue to +that person, only make them nosy. Names followed by a ‘*’ may be assigned +issues involving the module or topic.

      +

      The Platform and Interest Area tables list broader fields in which various +people have expertise. These people can also be contacted for help, +opinions, and decisions when issues involve their areas.

      +

      If a listed maintainer does not respond to requests for comment for an +extended period (three weeks or more), they should be marked as inactive +in this list by placing the word ‘inactive’ in parenthesis behind their +tracker id. They are of course free to remove that inactive mark at +any time.

      +

      Committers should update these tables as their areas of expertise widen. +New topics may be added to the Interest Area table at will.

      +

      The existence of this list is not meant to indicate that these people +must be contacted for decisions; it is, rather, a resource to be used +by non-committers to find responsible parties, and by committers who do +not feel qualified to make a decision in a particular context.

      +

      See also PEP 291 and PEP 360 for information about certain modules +with special rules.

      +
      +

      22.1. Stdlib

      + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      ModuleMaintainers
      __future__ 
      __main__gvanrossum, ncoghlan
      _dummy_threadbrett.cannon
      _threadpitrou
      abc 
      aifcr.david.murray
      argparsebethard
      array 
      astbenjamin.peterson
      asynchatjosiahcarlson, giampaolo.rodola, stutzbach
      asynciogvanrossum, haypo, pitrou, yselivanov
      asyncorejosiahcarlson, giampaolo.rodola, stutzbach
      atexit 
      audioop 
      base64 
      bdb 
      binascii 
      binhex 
      bisectrhettinger
      builtins 
      bz2nadeem.vawda
      calendarrhettinger
      cgi 
      cgitb 
      chunk 
      cmathmark.dickinson
      cmd 
      code 
      codecslemburg, doerwalter
      codeop 
      collectionsrhettinger
      collections.abcrhettinger, stutzbach
      colorsys 
      compileall 
      concurrent.futuresbquinlan
      configparserlukasz.langa*
      contextlibncoghlan*
      copyalexandre.vassalotti
      copyregalexandre.vassalotti
      cProfile 
      cryptjafo*
      csvskip.montanaro (inactive)
      ctypestheller (inactive), belopolsky, amaury.forgeotdarc, +meador.inge
      curses 
      datetimebelopolsky
      dbm 
      decimalfacundobatista, rhettinger, mark.dickinson
      difflibtim.peters (inactive)
      disncoghlan*
      distutilseric.araujo
      doctesttim.peters (inactive)
      dummy_threadingbrett.cannon
      emailbarry, r.david.murray*
      encodingslemburg, loewis
      enumeli.bendersky*, barry, ethan.furman*
      errno 
      exceptions 
      fcntl 
      filecmp 
      fileinput 
      fnmatch 
      formatter 
      fpectl 
      fractionsmark.dickinson, rhettinger
      ftplibgiampaolo.rodola
      functoolsncoghlan, rhettinger
      gcpitrou
      getopt 
      getpass 
      gettextloewis
      glob 
      grp 
      gzip 
      hashlibchristian.heimes, gregory.p.smith
      heapqrhettinger, stutzbach
      hmacchristian.heimes, gregory.p.smith
      htmlezio.melotti
      http 
      idlelibkbk, terry.reedy, roger.serwy
      imaplib 
      imghdr 
      imp 
      importlibbrett.cannon
      inspectyselivanov
      iopitrou, benjamin.peterson, stutzbach
      ipaddresspmoody, ncoghlan
      itertoolsrhettinger
      jsonbob.ippolito (inactive), ezio.melotti, rhettinger, pitrou
      keyword 
      lib2to3benjamin.peterson
      linecache 
      localeloewis, lemburg
      loggingvinay.sajip
      lzmanadeem.vawda
      macpath 
      mailboxpetri.lehtinen
      mailcap 
      marshal 
      mathmark.dickinson, rhettinger, stutzbach
      mimetypes 
      mmap 
      modulefindertheller (inactive), jvr
      msilibloewis
      msvcrt 
      multiprocessingjnoller, sbt*
      netrc 
      nis 
      nntplibpitrou
      numbers 
      operator 
      optparsearonacher
      osloewis
      ossaudiodev 
      parserbenjamin.peterson
      pathlibpitrou*
      pdbgeorg.brandl*
      picklealexandre.vassalotti, pitrou
      pickletoolsalexandre.vassalotti
      pipes 
      pkgutil 
      platformlemburg
      plistlib 
      poplibgiampaolo.rodola
      posix 
      pprintfdrake
      profilegeorg.brandl
      pstatsgeorg.brandl
      pty 
      pwd 
      py_compile 
      pybenchlemburg, pitrou
      pyclbr 
      pydoc 
      queuerhettinger
      quopri 
      randomrhettinger, mark.dickinson
      reeffbot (inactive), pitrou, ezio.melotti
      readline 
      reprlib 
      resource 
      rlcompleter 
      runpyncoghlan
      schedgiampaolo.rodola
      select 
      selectors 
      shelve 
      shlex 
      shutiltarek, hynek
      signal 
      site 
      smtpdgiampaolo.rodola
      smtplib 
      sndhdr 
      socketpitrou
      socketserver 
      spwd 
      sqlite3ghaering
      ssljanssen, pitrou, giampaolo.rodola, christian.heimes
      statchristian.heimes
      statistics 
      stringgeorg.brandl*
      stringprep 
      structmark.dickinson, meador.inge
      subprocessastrand (inactive)
      sunau 
      symbol 
      symtablebenjamin.peterson
      sys 
      sysconfigtarek
      syslogjafo*
      tabnannytim.peters (inactive)
      tarfilelars.gustaebel
      telnetlib 
      tempfilegeorg.brandl, ncoghlan
      termios 
      testezio.melotti
      textwrapgeorg.brandl
      threadingpitrou
      timebelopolsky
      timeitgeorg.brandl
      tkintergpolo
      tokengeorg.brandl
      tokenizemeador.inge
      tracebelopolsky
      tracebackgeorg.brandl*
      tty 
      turtlegregorlingl
      types 
      unicodedataloewis, lemburg, ezio.melotti
      unittestmichael.foord*, ezio.melotti
      unittest.mockmichael.foord*
      urlliborsenthil
      uu 
      uuid 
      venvvinay.sajip
      warnings 
      wave 
      weakreffdrake, pitrou
      webbrowsergeorg.brandl
      winregstutzbach
      winsoundeffbot (inactive)
      wsgirefpje
      xdrlib 
      xml.dom 
      xml.dom.minidom 
      xml.dom.pulldom 
      xml.etreeeffbot (inactive), eli.bendersky*, scoder
      xml.parsers.expatchristian.heimes
      xml.saxchristian.heimes
      xml.sax.handler 
      xml.sax.saxutils 
      xml.sax.xmlreader 
      xmlrpcloewis
      zipfilealanmcintyre
      zipimport 
      zlibnadeem.vawda
      +
      +
      +

      22.2. Tools

      + ++++ + + + + + + + + + + +
      ToolMaintainers
      pybenchlemburg
      +
      +
      +

      22.3. Platforms

      + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      PlatformMaintainers
      AIXDavid.Edelsohn
      Cygwinjlt63, stutzbach
      FreeBSD 
      HP-UX 
      Linux 
      Mac OS Xronaldoussoren, ned.deily, hynek
      NetBSD1 
      OS2/EMXaimacintyre
      Solaris/OpenIndianajcea
      Windowstim.golden
      JVM/Javafrank.wierzbicki
      +
      +
      +

      22.4. Miscellaneous

      + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      Interest AreaMaintainers
      algorithms 
      ast/compilerncoghlan, benjamin.peterson, brett.cannon, georg.brandl
      autoconf/makefiles 
      bsd 
      benchmarkspitrou, brett.cannon
      bug trackerezio.melotti
      buildbotspitrou
      bytecodebenjamin.peterson, pitrou, georg.brandl
      context managersncoghlan
      coverity scanchristian.heimes, brett.cannon
      cryptographychristian.heimes, gregory.p.smith
      data formatsmark.dickinson, georg.brandl
      databaselemburg
      devguidencoghlan, eric.araujo, ezio.melotti
      documentationgeorg.brandl, ezio.melotti, eric.araujo
      GUI 
      i18nlemburg, eric.araujo
      import machinerybrett.cannon, ncoghlan, eric.snow
      iopitrou, benjamin.peterson, stutzbach, hynek
      localelemburg, loewis
      mathematicsmark.dickinson, eric.smith, lemburg, stutzbach
      memory managementtim.peters, lemburg
      networkinggiampaolo.rodola, pitrou
      object modelbenjamin.peterson
      packagingtarek, lemburg, alexis, eric.araujo
      py3 transitionbenjamin.peterson
      release managementtarek, lemburg, benjamin.peterson, barry, loewis, +gvanrossum, anthonybaxter, eric.araujo, ned.deily, +georg.brandl
      str.formateric.smith
      testingmichael.foord, pitrou, ezio.melotti
      test coveragencoghlan, giampaolo.rodola, christian.heimes
      threadspitrou
      time and dateslemburg, belopolsky
      unicodelemburg, ezio.melotti, haypo, benjamin.peterson, pitrou
      version controleric.araujo, georg.brandl, ezio.melotti
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      21. Changing the Python Language

      +

      Next topic

      +

      23. Emacs support

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/faq.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/faq.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,972 @@ + + + + + + + + 29. Python Developer FAQ — Python Developer's Guide + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      29. Python Developer FAQ

      +
      + +
      +
      +

      29.1. Communications

      +
      +

      29. Where should I ask general Python questions?

      +

      General Python questions should still go to python-list or tutor +or similar resources, such as StackOverflow or the #python IRC channel +on Freenode.

      +
      +
      +

      29. Where should I suggest new features and language changes?

      +

      The python-ideas mailing list is specifically intended for discussion of +new features and language changes. Please don’t be disappointed if your +idea isn’t met with universal approval: as the long list of Rejected and +Withdrawn PEPs in the PEP Index attests, and as befits a reasonably mature +programming language, getting significant changes into Python isn’t a simple +task.

      +

      If the idea is reasonable, someone will suggest posting it as a feature +request on the issue tracker, or, for larger changes, writing it up as +a draft PEP.

      +

      Sometimes core developers will differ in opinion, or merely be collectively +unconvinced. When there isn’t an obvious victor then the +Status Quo Wins a Stalemate as outlined in the linked post.

      +

      For some examples on language changes that were accepted please read +Justifying Python Language Changes.

      +

      See also the Changing the Python Language section of this guide.

      +
      +
      +

      29. Where should I ask general questions about contributing to CPython?

      +

      The Python Mentors program is specifically about encouraging +developers and others that would like to contribute to Python development in +general, rather than necessarily being focused on one particular issue. +Some core developers are also available on the #python-dev IRC channel on +Freenode.

      +
      +
      +

      29. Where should I report specific problems?

      +

      Specific problems should be posted to the issue tracker.

      +
      +
      +

      29. What if I’m not sure it is a bug?

      +

      The general Python help locations listed above are the best place to start +with that kind of question. If they agree it looks like a bug, then the +next step is to either post it to the issue tracker or else to ask further +on the core development mailing list, python-dev.

      +
      +
      +

      29. What if I disagree with an issue resolution on the tracker?

      +

      First, take some time to consider any comments made in association with the +resolution of the tracker issue. On reflection, they may seem more reasonable +than they first appeared.

      +

      If you still feel the resolution is incorrect, then raise the question on +python-dev. If the consensus there supports the disputed resolution, please +take any further objections to python-ideas (or some other forum). Further +argument on python-dev after a consensus has been reached amongst the core +developers is unlikely to win any converts.

      +
      +
      +

      29. How do I tell who is and isn’t a core developer?

      +

      You can check their name against the full list of developers with commit +rights to the main source control repository.

      +

      On the issue tracker, most core developers will have the Python logo +appear next to their name.

      +
      +
      +

      29. What standards of behaviour are expected in these communication channels?

      +

      We try to foster environments of mutual respect, tolerance and encouragement, +as described in the PSF’s Diversity Statement. Abiding by the guidelines +in this document and asking questions or posting suggestions in the +appropriate channels are an excellent way to get started on the mutual respect +part, greatly increasing the chances of receiving tolerance and encouragement +in return.

      +
      +
      +
      +

      29.2. Version Control

      +
      +

      29. For everyone

      +

      The following FAQs are intended for both core developers and contributors.

      +
      +

      29. Where can I learn about the version control system used, Mercurial (hg)?

      +

      Mercurial‘s (also known as hg) official web site is at +http://mercurial.selenic.com/. A book on Mercurial published by +O’Reilly Media, Mercurial: The Definitive Guide, is available +for free online. Another resource is Hg Init: a Mercurial tutorial +by Joel Spolsky.

      +

      With Mercurial installed, you can run the help tool that comes with +Mercurial to get help:

      +
      hg help
+
      +
      +

      The man page for hg provides a quick refresher on the details of +various commands, but doesn’t provide any guidance on overall +workflow.

      +
      +
      +

      29. I already know how to use Git, can I use that instead?

      +

      While the main workflow for core developers requires Mercurial, if +you just want to generate patches with git diff and post them to the +issue tracker, Petri Lehtinen maintains a git mirror of the main +CPython repository. To create a local clone based on this mirror rather +than the main repository:

      +
      git clone git://github.com/akheron/cpython
+
      +
      +

      The mirror’s master branch tracks the main repository’s default branch, +while the maintenance branch names (2.7, 3.3, etc) are mapped +directly.

      +

      Please only use this approach if you’re already an experienced Git user and +don’t require assistance with the specifics of version control commands. All +other parts of this developer’s guide assume the use of Mercurial for local +version control.

      +
      +
      +

      29. What do I need to use Mercurial?

      +
      +
      29. UNIX
      +

      First, you need to download Mercurial. Most UNIX-based operating systems +have binary packages available. Most package management systems also +have native Mercurial packages available.

      +

      If you have push rights, you need OpenSSH. This is needed to verify +your identity when performing commits. As with Mercurial, binary packages +are typically available either online or through the platform’s package +management system.

      +

      Mercurial does not use its own compression via SSH +because it is better to enable compression at the SSH level. Enabling +SSH compression can make cloning a remote repository much faster. +You can configure it in your ~/.ssh/config file; for example:

      +
      Host hg.python.org
+  Compression yes
+
      +
      +
      +
      +
      29. Windows
      +

      The recommended option on Windows is to download TortoiseHg which +integrates with Windows Explorer and also bundles the command line client +(meaning you can type hg in a DOS box). Note that most +entries in this FAQ only cover the command line client in detail - refer +to the TortoiseHg documentation for assistance with its graphical interface.

      +

      If you have push rights, you need to configure Mercurial to work with +your SSH keys. For that, open your Mercurial configuration file +(you can do so by opening the TortoiseHg Global Settings dialog and then +clicking “Edit File”). If there is no [ui] section, create it by +typing just that on a line by itself. Then add the following line:

      +
      ssh = TortoisePlink.exe -ssh -2 -C -i C:\path\to\yourkey.ppk
+
      +
      +

      where C:\path\to\yourkey.ppk should be replaced with the actual path +to your SSH private key.

      +
      +

      Note

      +

      If your private key is in OpenSSH format, you must first convert it to +PuTTY format by loading it into PuTTYgen.

      +
      +
      +
      +
      +

      29. What’s a working copy? What’s a repository?

      +

      Mercurial is a “distributed” version control system. This means that each +participant, even casual contributors, download a complete copy (called a +clone, since it is obtained by calling hg clone) of the central +repository which can be treated as a stand-alone repository for all purposes. +That copy is called in the FAQ the local repository, to differentiate +with any remote repository you might also interact with.

      +

      But you don’t modify files directly in the local repository; Mercurial doesn’t +allow for it. You modify files in what’s called the working copy associated +with your local repository: you also run compilations and tests there. +Once you are satisfied with your changes, you can commit them; +committing records the changes as a new revision in the local repository.

      +

      Changes in your local repository don’t get automatically shared with the +rest of the world. Mercurial ensures that you have to do so explicitly +(this allows you to experiment quite freely with multiple branches of +development, all on your private computer). The main commands for doing +so are hg pull and hg push.

      +
      +
      +

      29. Which branches are in my local repository?

      +

      Typing hg branches displays the open branches in your local repository:

      +
      $ hg branches
+default                    86781:52ec6a3eeda5
+2.7                        86776:dd12639b82bf
+3.3                        86779:544b654d000c (inactive)
+3.2                        86778:dda1a32748e0 (inactive)
+3.1                        86777:b1ddcb220a7f (inactive)
+
      +
      +
      +
      +

      29. Why are some branches marked “inactive”?

      +

      Assuming you get the following output:

      +
      $ hg branches
+default                    68042:8ff33af017ef
+3.3                        68039:c17d7772c638 (inactive)
+
      +
      +

      This means all changesets in the “3.3” branch have been merged into the +“default” branch (or any other branch, if such exists).

      +
      +
      +

      29. Which branch is currently checked out in my working copy?

      +

      Use:

      +
      $ hg branch
+default
+
      +
      +

      Or to get more information:

      +
      $ hg summary
+parent: 68026:f12ef116dd10 tip
+ In FTP.close() method, make sure to also close the socket object, not only the file.
+branch: default
+commit: (clean)
+update: (current)
+
      +
      +
      +
      +

      29. How do I switch between branches inside my working copy?

      +

      Simply use hg update to checkout another branch in the current directory:

      +
      $ hg branch
+default
+$ hg update 3.3
+86 files updated, 0 files merged, 11 files removed, 0 files unresolved
+$ hg branch
+3.3
+
      +
      +

      Adding the -v option to hg update will list all updated files.

      +

      Note that, due to some previously built executables being used as a part of +the build process, you may sometimes run into issues when attempting to +switch between Python 2.x and Python 3.x branches. In these cases, it is +best to run a make distclean to ensure that all previously built files +are removed.

      +
      +
      +

      29. I want to keep a separate working copy per development branch, is it possible?

      +

      There are two ways:

      +
        +
      1. Use the “share extension” as described in the Multiple Clones Approach +section;
        2. +
      2. Create several clones of your local repository;
        3. +
      +

      If you want to use the second way, you can do:

      +
      $ hg clone cpython py33
+updating to branch default
+3434 files updated, 0 files merged, 0 files removed, 0 files unresolved
+$ cd py33
+$ hg update 3.3
+86 files updated, 0 files merged, 11 files removed, 0 files unresolved
+
      +
      +

      The current branch in a working copy is “sticky”: if you pull in some new +changes, hg update will update to the head of the current branch.

      +
      + +
      +

      29. How do I create a shorthand alias for a remote repository?

      +

      In your global .hgrc file add a section similar to the following:

      +
      [paths]
+dg = ssh://hg@hg.python.org/devguide
+
      +
      +

      This example creates a dg alias for the devguide repository +on hg.python.org. This allows “dg” to be entered instead of the +full URL for commands taking a repository argument (e.g. hg pull dg or +hg outgoing dg).

      +

      Anywhere that <remote repository> is used in the commands in this +FAQ, hg should accept an alias in place of a complete remote URL.

      +
      +
      +

      29. How do I compare my local repository to a remote repository?

      +

      To display the list of changes that are in your local repository, but not +in the remote, use:

      +
      hg outgoing <remote repository>
+
      +
      +

      This is the list of changes that will be sent if you call +hg push <remote repository>. It does not include any uncommitted +changes in your working copy!

      +

      Conversely, for the list of changes that are in the remote repository but +not in the local, use:

      +
      hg incoming <remote repository>
+
      +
      +

      This is the list of changes that will be retrieved if you call +hg pull <remote repository>.

      +
      +

      Note

      +

      In most daily use, you will work against the default remote repository, +and therefore simply type hg outgoing and hg incoming.

      +

      In this case, you can also get a synthetic summary using +hg summary --remote.

      +
      +
      +
      +

      29. How do I update my local repository to be in sync with a remote repository?

      +

      Run:

      +
      hg pull <remote repository>
+
      +
      +

      from the repository you wish to pull the latest changes into. Most of the +time, that repository is a clone of the repository you want to pull from, +so you can simply type:

      +
      hg pull
+
      +
      +

      This doesn’t update your working copy, though. See below:

      +
      +
      +

      29. How do I update my working copy with the latest changes?

      +

      Do:

      +
      hg update
+
      +
      +

      This will update your working copy with the latest changes on the +current branch. If you had uncommitted +changes in your working copy, they will be merged in.

      +

      If you find yourself typing often hg pull followed by hg update, +be aware that you can combine them in a single command:

      +
      hg pull -u
+
      +
      +
      +
      +

      29. How do I apply a patch?

      +

      If you want to try out or review a patch generated using Mercurial, do:

      +
      patch -p1 < somework.patch
+
      +
      +

      This will apply the changes in your working copy without committing them. +If the patch was not created by Mercurial (for example, a patch created by +Subversion and thus lacking any a/b directory prefixes in the patch), +replace -p1 with -p0.

      +

      If the patch contains renames, deletions or copies, and you intend committing +it after your review, you might prefer using:

      +
      hg import --no-commit somework.patch
+
      +
      +

      If you want to work on the patch using mq (Mercurial Queues), type instead:

      +
      hg qimport somework.patch
+
      +
      +

      This will create a patch in your queue with a name that matches the filename. +You can use the -n argument to specify a different name. To have the +patch applied to the working copy, type:

      +
      hg qpush
+
      +
      +

      Finally, to delete the patch, first un-apply it if necessary using hg qpop, +then do:

      +
      hg qdelete somework.patch
+
      +
      +
      +
      +

      29. How do I solve conflicts when applying a patch fails?

      +

      The standard patch command, as well as hg import, will produce +unhelpful *.rej files when it fails applying parts of a patch. +We suggest you try the mpatch utility, which can help resolve a number of +common causes of patch rejects.

      +

      To make use of mpatch transparent, you can define a shell alias in one +of your startup files. For example, if you want it to open the kdiff3 +merge program to fix failing patch hunks:

      +
      alias patch='mpatch --merge=kdiff3'
+
      +
      +

      or if you want it to automatically solve conflicts by using heuristics:

      +
      alias patch='mpatch --auto --no-merge'
+
      +
      +
      +
      +

      29. How do I add a file or directory to the repository?

      +

      Simply specify the path to the file or directory to add and run:

      +
      hg add PATH
+
      +
      +

      If PATH is a directory, Mercurial will recursively add any files in that +directory and its descendants.

      +

      If you want Mercurial to figure out by itself which files should be added +and/or removed, just run:

      +
      hg addremove
+
      +
      +

      Be careful though, as it might add some files that are not desired in +the repository (such as build products, cache files, or other data).

      +

      You will then need to run hg commit (as discussed below) to commit +the file(s) to your local repository.

      +
      +
      +

      29. What’s the best way to split a file into several files?

      +

      To split a file into several files (e.g. a module converted to a package or a +long doc file divided in two separate documents) use hg copy:

      +
      hg copy module.rst module2.rst
+
      +
      +

      and then remove the parts that are not necessary from module.rst and +module2.rst. This allows Mercurial to know that the content of +module2.rst used to be in module.rst, and will make subsequent merges +easier. If necessary, you can also use hg copy several times.

      +

      If you simply create module2.rst, add it with hg add, and copy part of +the content from module.rst, Mercurial won’t know that the two file are +related.

      +
      +
      +

      29. How do I delete a file or directory in the repository?

      +

      Specify the path to be removed with:

      +
      hg remove PATH
+
      +
      +

      This will remove the file or the directory from your working copy; you will +have to commit your changes for the removal to be recorded +in your local repository.

      +
      +
      +

      29. What files are modified in my working copy?

      +

      Running:

      +
      hg status
+
      +
      +

      will list any pending changes in the working copy. These changes will get +committed to the local repository if you issue an hg commit without +specifying any path.

      +

      Some +key indicators that can appear in the first column of output are:

      +
      +
      ++++ + + + + + + + + + + + + + + +
      AScheduled to be added
      RScheduled to be removed
      MModified locally
      ?Not under version control
      +
      +

      If you want a line-by-line listing of the differences, use:

      +
      hg diff
+
      +
      +
      +
      +

      29. How do I revert a file I have modified back to the version in the repository?

      +

      Running:

      +
      hg revert PATH
+
      +
      +

      will revert PATH to its version in the repository, throwing away any +changes you made locally. If you run:

      +
      hg revert -a
+
      +
      +

      from the root of your working copy it will recursively restore everything +to match up with the repository.

      +
      +
      +

      29. How do I find out who edited or what revision changed a line last?

      +

      You want:

      +
      hg annotate PATH
+
      +
      +

      This will output to stdout every line of the file along with which revision +last modified that line. When you have the revision number, it is then +easy to display it in detail.

      +
      +
      +

      29. How can I see a list of log messages for a file or specific revision?

      +

      To see the history of changes for a specific file, run:

      +
      hg log -v [PATH]
+
      +
      +

      That will list all messages of revisions which modified the file specified +in PATH. If PATH is omitted, all revisions are listed.

      +

      If you want to display line-by-line differences for each revision as well, +add the -p option:

      +
      hg log -vp [PATH]
+
      +
      +

      If you want to view the differences for a specific revision, run:

      +
      hg log -vp -r <revision number>
+
      +
      +
      +
      +

      29. How can I see the changeset graph in my repository?

      +

      In Mercurial repositories, changesets don’t form a simple list, but rather +a graph: every changeset has one or two parents (it’s called a merge changeset +in the latter case), and can have any number of children.

      +

      The graphlog extension is very useful for examining the structure of the +changeset graph. It is bundled with Mercurial.

      +

      Graphical tools, such as TortoiseHG, will display the changeset graph +by default.

      +
      +
      +

      29. How do I update to a specific release tag?

      +

      Run:

      +
      hg tags
+
      +
      +

      to get a list of tags. To update your working copy to a specific tag, use:

      +
      hg update <tag>
+
      +
      +
      +
      +

      29. How do I find which changeset introduced a bug or regression?

      +

      hg bisect, as the name indicates, helps you do a bisection of a range of +changesets.

      +

      You need two changesets to start the search: one that is “good” +(doesn’t have the bug), and one that is “bad” (has the bug). Usually, you +have just noticed the bug in your working copy, so you can start with:

      +
      hg bisect --bad
+
      +
      +

      Then you must update to a previous changeset that doesn’t have the bug. +You can conveniently choose a faraway changeset (for example a former release), +and check that it is indeed “good”. Then type:

      +
      hg bisect --good
+
      +
      +

      Mercurial will automatically bisect so as to narrow the range of possible +culprits, until a single changeset is isolated. Each time Mercurial presents +you with a new changeset, re-compile Python and run the offending test, for +example:

      +
      make -j2
+./python -m test -uall test_sometest
+
      +
      +

      Then, type either hg bisect --good or hg bisect --bad depending on +whether the test succeeded or failed.

      +
      +
      +

      29. How come feature XYZ isn’t available in Mercurial?

      +

      Mercurial comes with many bundled extensions which can be explicitly enabled. +You can get a list of them by typing hg help extensions. Some of these +extensions, such as color, can prettify output; others, such as fetch +or graphlog, add new Mercurial commands.

      +

      There are also many configuration options to tweak various aspects of the +command line and other Mercurial behaviour; typing man hgrc displays +their documentation inside your terminal.

      +

      In the end, please refer to the Mercurial wiki, especially the pages about +extensions (including third-party ones) and the tips and tricks.

      +
      +
      +
      +

      29. For core developers

      +

      These FAQs are intended mainly for core developers.

      +
      +

      29. How do I commit a change to a file?

      +

      To commit any changes to a file (which includes adding a new file or deleting +an existing one), you use the command:

      +
      hg commit [PATH]
+
      +
      +

      PATH is optional: if it is omitted, all changes in your working copy +will be committed to the local repository. When you commit, be sure that all +changes are desired by reviewing them first; +also, when making commits that you intend to push to public repositories, +you should not commit together unrelated changes.

      +

      To abort a commit that you are in the middle of, leave the message +empty (i.e., close the text editor without adding any text for the +message). Mercurial will then abort the commit operation so that you can +try again later.

      +

      Once a change is committed to your local repository, it is still only visible +by you. This means you are free to experiment with as many local commits +you feel like.

      +
      +

      Note

      +

      If you do not like the default text editor Mercurial uses for +entering commit messages, you may specify a different editor, +either by changing the EDITOR environment variable or by setting +a Mercurial-specific editor in your global .hgrc with the editor +option in the [ui] section.

      +
      +
      +
      +

      29. How do I solve merge conflicts?

      +

      The easiest way is to install KDiff3 — Mercurial will open it automatically +in case of conflicts, and you can then use it to solve the conflicts and +save the resulting file(s). KDiff3 will also take care of marking the +conflicts as resolved.

      +

      If you don’t use a merge tool, you can use hg resolve --list to list the +conflicting files, resolve the conflicts manually, and the use +hg resolve --mark <file path> to mark these conflicts as resolved. +You can also use hg resolve -am to mark all the conflicts as resolved.

      +
      +

      Note

      +

      Mercurial will use KDiff3 automatically if it’s installed and it can find +it — you don’t need to change any settings. KDiff3 is also already +included in the installer of TortoiseHg. For more information, see +http://mercurial.selenic.com/wiki/KDiff3.

      +
      +
      +
      +

      29. How do I make a null merge?

      +

      If you committed something (e.g. on 3.3) that shouldn’t be ported on newer +branches (e.g. on default), you have to do a null merge:

      +
      cd 3.x
+hg merge 3.3
+hg revert -ar default
+hg resolve -am  # needed only if the merge created conflicts
+hg ci -m '#12345: null merge with 3.3.'
+
      +
      +

      Before committing, hg status should list all the merged files as M, +but hg diff should produce no output. This will record the merge without +actually changing the content of the files.

      +
      +
      +

      29. I got “abort: push creates new remote heads!” while pushing, what do I do?

      +

      If you see this message while pushing, it means that you committed something +on a clone that was not up to date, thus creating a new head. +This usually happens for two reasons:

      +
        +
      1. You forgot to run hg pull and/or hg up before committing;
        2. +
      2. Someone else pushed on the main repo just before you, causing a push race;
        3. +
      +

      First of all you should pull the new changesets using hg pull. Then you can +use hg heads to see which branches have multiple heads.

      +

      If only one branch has multiple heads, you can do:

      +
      cd default
+hg heads .
+hg up csid-of-the-other-head
+hg merge
+hg ci -m 'Merge heads.'
+
      +
      +

      hg heads . will show you the two heads of the current branch: the one you +pulled and the one you created with your commit (you can also specify a branch +with hg heads <branch>). While not strictly necessary, it is highly +recommended to switch to the other head before merging. This way you will be +merging only your changeset with the rest, and in case of conflicts it will be +a lot easier.

      +

      If more than one branch has multiple heads, you have to repeat these steps for +each branch. Since this creates new changesets, you will also have to +merge them between branches. For example, if both 3.3 +and default have multiple heads, you should first merge heads in 3.3, +then merge heads in default, and finally merge 3.3 with default +using hg merge 3.3 as usual.

      +

      In order to avoid this, you should always remember to pull and update before +committing.

      +
      +
      +

      29. How do I undo the changes made in a recent commit?

      +

      First, this should not happen if you take the habit of reviewing changes before committing them.

      +

      In any case, run:

      +
      hg backout <revision number>
+
      +
      +

      This will modify your working copy so that all changes in <revision number> +(including added or deleted files) are undone. You then need to commit these changes so that the backout gets permanently recorded.

      +
      +

      Note

      +

      These instructions are for Mercurial 1.7 and higher. hg backout has +a slightly different behaviour in versions before 1.7.

      +
      +
      +
      +
      +
      +

      29.3. SSH

      +
      +

      29. How do I generate an SSH 2 public key?

      +

      All generated SSH keys should be sent to hgaccounts@python.org for +adding to the list of keys.

      +
      +

      29. UNIX

      +

      Run:

      +
      ssh-keygen -t rsa
+
      +
      +

      This will generate two files; your public key and your private key. Your +public key is the file ending in .pub.

      +
      +
      +

      29. Windows

      +

      Use PuTTYgen to generate your public key. Choose the “SSH2 DSA” radio button, +have it create an OpenSSH formatted key, choose a password, and save the private +key to a file. Copy the section with the public key (using Alt-P) to a file; +that file now has your public key.

      +
      +
      +
      +

      29. Is there a way to avoid having to constantly enter my password for my SSH 2 public key?

      +
      +

      29. UNIX

      +

      Use ssh-agent and ssh-add to register your private key with SSH for +your current session. The simplest solution, though, is to use KeyChain, +which is a shell script that will handle ssh-agent and ssh-add for you +once per login instead of per session.

      +
      +
      +

      29. Windows

      +

      The Pageant program is bundled with TortoiseHg. You can find it in its +installation directory (usually C:\Program Files (x86)\TortoiseHg\); +you can also download it separately.

      +

      Running Pageant will prevent you from having to type your password constantly. +If you add a shortcut to Pageant to your Autostart group and edit the shortcut +so that the command line includes an argument to your private key then Pageant +will load the key every time you log in.

      +
      +
      +
      +

      29. Can I make commits from machines other than the one I generated the keys on?

      +

      You can make commits from any machine, since they will be +recorded in your local repository.

      +

      However, to push these changes to the remote server, you will need proper +credentials. All you need is to make sure that the machine you want to +push changes from has both the public and private keys in the standard +place that ssh will look for them (i.e. ~/.ssh on Unix machines). +Please note that although the key file ending in .pub contains your +user name and machine name in it, that information is not used by the +verification process, therefore these key files can be moved to a +different computer and used for verification. Please guard your keys +and never share your private key with anyone. If you lose the media +on which your keys are stored or the machine on which your keys are +stored, be sure to report this to pydotorg@python.org at the same time +that you change your keys.

      +
      +
      +
      +

      29.4. General

      +
      +

      29. How do I regenerate configure?

      +

      If a change is made to Python which relies on some POSIX system-specific +functionality (such as using a new system call), it is necessary to update the +configure script to test for availability of the functionality.

      +

      Python’s configure script is generated from configure.ac using Autoconf. +Instead of editing configure, edit configure.ac and then run +autoreconf to regenerate configure and a number of other files (such as +pyconfig.h.

      +

      When submitting a patch with changes made to configure.ac, it is preferred +to leave out the generated files as differences between Autoconf versions +frequently results in many spurious changes cluttering the patch. Instead, +remind any potential reviewers on the tracker to run autoreconf.

      +

      Note that running autoreconf is not the same as running autoconf. For +example, autoconf by itself will not regenerate pyconfig.h.in. +autoreconf runs autoconf and a number of other tools repeatedly as is +appropriate.

      +

      Python’s configure.ac script typically requires a specific version of +Autoconf. At the moment, this reads: version_required(2.65)

      +

      If the system copy of Autoconf does not match this version, you will need to +install your own copy of Autoconf.

      +
      +
      +

      29. How do I update my auto-load-safe-path to allow test_gdb to run?

      +

      test_gdb attempts to automatically load additional Python specific +hooks into gdb in order to test them. Unfortunately, the command line +options it uses to do this aren’t always supported correctly.

      +

      If test_gdb is being skipped with an “auto-loading has been declined” +message, then it is necessary to identify any Python build directories as +auto-load safe. One way to achieve this is to add a line like the following +to ~/.gdbinit (edit the specific list of paths as appropriate):

      +
      add-auto-load-safe-path ~/devel/py3k:~/devel/py32:~/devel/py27
+
      +
      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      28. Dynamic Analysis with Clang

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/fixingissues.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/fixingissues.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,125 @@ + + + + + + + + 10. Fixing “easy” Issues (and Beyond) — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      10. Fixing “easy” Issues (and Beyond)

      +

      When you feel comfortable enough to want to help tackle issues by trying to +create a patch to fix an issue, you can start by looking at the “easy” +issues. These issues should be ones where it should take no longer than a day +or weekend to fix. But because the “easy” classification is typically done at +triage time it can turn out to be inaccurate, so do feel free to leave a +comment if you think the classification no longer applies.

      +

      For the truly adventurous looking for a challenge, you can look for issues that +are not considered easy and try to fix those. It must be warned, though, that +it is quite possible that a bug that has been left open has been left into that +state because of the difficulty compared to the benefit of the fix. It could +also still be open because no consensus has been reached on how to fix the +issue (although having a patch that proposes a fix can turn the tides of the +discussion to help bring it to a close). Regardless of why the issue is open, +you can also always provide useful comments if you do attempt a fix, successful +or not.

      +
      + + +
      +
      +
      +
      +
      +

      Previous topic

      +

      9. Silence Warnings From the Test Suite

      +

      Next topic

      +

      11. Issue Tracking

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/gdb.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/gdb.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,399 @@ + + + + + + + + 24. gdb Support — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      24. gdb Support

      +

      If you experience low-level problems such as crashes or deadlocks +(e.g. when tinkering with parts of CPython which are written in C), +it can be convenient to use a low-level debugger such as gdb in +order to diagnose and fix the issue. By default, however, gdb (or any +of its front-ends) doesn’t know about high-level information specific to the +CPython interpreter, such as which Python function is currently executing, +or what type or value has a given Python object represented by a standard +PyObject * pointer. We hereafter present two ways to overcome this +limitation.

      +
      +

      24.1. gdb 7 and later

      +

      In gdb 7, support for extending gdb with Python was +added. When CPython is built you will notice a python-gdb.py file in the +root directory of your checkout. Read the module docstring for details on how +to use the file to enhance gdb for easier debugging of a CPython process.

      +

      This is what a backtrace looks like (truncated) when this extension is +enabled:

      +
      #0  0x000000000041a6b1 in PyObject_Malloc (nbytes=Cannot access memory at address 0x7fffff7fefe8
+) at Objects/obmalloc.c:748
+#1  0x000000000041b7c0 in _PyObject_DebugMallocApi (id=111 'o', nbytes=24) at Objects/obmalloc.c:1445
+#2  0x000000000041b717 in _PyObject_DebugMalloc (nbytes=24) at Objects/obmalloc.c:1412
+#3  0x000000000044060a in _PyUnicode_New (length=11) at Objects/unicodeobject.c:346
+#4  0x00000000004466aa in PyUnicodeUCS2_DecodeUTF8Stateful (s=0x5c2b8d "__lltrace__", size=11, errors=0x0, consumed=
+    0x0) at Objects/unicodeobject.c:2531
+#5  0x0000000000446647 in PyUnicodeUCS2_DecodeUTF8 (s=0x5c2b8d "__lltrace__", size=11, errors=0x0)
+    at Objects/unicodeobject.c:2495
+#6  0x0000000000440d1b in PyUnicodeUCS2_FromStringAndSize (u=0x5c2b8d "__lltrace__", size=11)
+    at Objects/unicodeobject.c:551
+#7  0x0000000000440d94 in PyUnicodeUCS2_FromString (u=0x5c2b8d "__lltrace__") at Objects/unicodeobject.c:569
+#8  0x0000000000584abd in PyDict_GetItemString (v=
+    {'Yuck': <type at remote 0xad4730>, '__builtins__': <module at remote 0x7ffff7fd5ee8>, '__file__': 'Lib/test/crashers/nasty_eq_vs_dict.py', '__package__': None, 'y': <Yuck(i=0) at remote 0xaacd80>, 'dict': {0: 0, 1: 1, 2: 2, 3: 3}, '__cached__': None, '__name__': '__main__', 'z': <Yuck(i=0) at remote 0xaace60>, '__doc__': None}, key=
+    0x5c2b8d "__lltrace__") at Objects/dictobject.c:2171
+
      +
      +

      (notice how the dictionary argument to PyDict_GetItemString is displayed +as its repr(), rather than an opaque PyObject * pointer)

      +

      The extension works by supplying a custom printing routine for values of type +PyObject *. If you need to access lower-level details of an object, then +cast the value to a pointer of the appropriate type. For example:

      +
      (gdb) p globals
+$1 = {'__builtins__': <module at remote 0x7ffff7fb1868>, '__name__':
+'__main__', 'ctypes': <module at remote 0x7ffff7f14360>, '__doc__': None,
+'__package__': None}
+
+(gdb) p *(PyDictObject*)globals
+$2 = {ob_refcnt = 3, ob_type = 0x3dbdf85820, ma_fill = 5, ma_used = 5,
+ma_mask = 7, ma_table = 0x63d0f8, ma_lookup = 0x3dbdc7ea70
+<lookdict_string>, ma_smalltable = {{me_hash = 7065186196740147912,
+me_key = '__builtins__', me_value = <module at remote 0x7ffff7fb1868>},
+{me_hash = -368181376027291943, me_key = '__name__',
+me_value ='__main__'}, {me_hash = 0, me_key = 0x0, me_value = 0x0},
+{me_hash = 0, me_key = 0x0, me_value = 0x0},
+{me_hash = -9177857982131165996, me_key = 'ctypes',
+me_value = <module at remote 0x7ffff7f14360>},
+{me_hash = -8518757509529533123, me_key = '__doc__', me_value = None},
+{me_hash = 0, me_key = 0x0, me_value = 0x0}, {
+  me_hash = 6614918939584953775, me_key = '__package__', me_value = None}}}
+
      +
      +

      The pretty-printers try to closely match the repr() implementation of the +underlying implementation of Python, and thus vary somewhat between Python 2 +and Python 3.

      +

      An area that can be confusing is that the custom printer for some types look a +lot like gdb’s built-in printer for standard types. For example, the +pretty-printer for a Python 3 int gives a repr() that is not +distinguishable from a printing of a regular machine-level integer:

      +
      (gdb) p some_machine_integer
+$3 = 42
+
+(gdb) p some_python_integer
+$4 = 42
+
+(gdb) p *(PyLongObject*)some_python_integer
+$5 = {ob_base = {ob_base = {ob_refcnt = 8, ob_type = 0x3dad39f5e0}, ob_size = 1},
+ob_digit = {42}}
+
      +
      +

      A similar confusion can arise with the str type, where the output looks a +lot like gdb’s built-in printer for char *:

      +
      (gdb) p ptr_to_python_str
+$6 = '__builtins__'
+
      +
      +

      The pretty-printer for str instances defaults to using single-quotes (as +does Python’s repr for strings) whereas the standard printer for char * +values uses double-quotes and contains a hexadecimal address:

      +
      (gdb) p ptr_to_char_star
+$7 = 0x6d72c0 "hello world"
+
      +
      +

      Here’s how to see the implementation details of a str instance (for Python +3, where a str is a PyUnicodeObject *):

      +
      (gdb) p *(PyUnicodeObject*)$6
+$8 = {ob_base = {ob_refcnt = 33, ob_type = 0x3dad3a95a0}, length = 12,
+str = 0x7ffff2128500, hash = 7065186196740147912, state = 1, defenc = 0x0}
+
      +
      +

      As well as adding pretty-printing support for PyObject *, the extension adds a number of commands to gdb

      +
      +
      py-list
      +

      List the Python source code (if any) for the current frame in the selected +thread. The current line is marked with a “>”:

      +
      (gdb) py-list
+ 901        if options.profile:
+ 902            options.profile = False
+ 903            profile_me()
+ 904            return
+ 905
+>906        u = UI()
+ 907        if not u.quit:
+ 908            try:
+ 909                gtk.main()
+ 910            except KeyboardInterrupt:
+ 911                # properly quit on a keyboard interrupt...
+
      +
      +

      Use py-list START to list at a different line number within the python +source, and py-list START,END to list a specific range of lines within +the python source.

      +
      +
      py-up and py-down
      +

      The py-up and py-down commands are analogous to gdb’s regular up +and down commands, but try to move at the level of CPython frames, rather +than C frames.

      +

      gdb is not always able to read the relevant frame information, depending on +the optimization level with which CPython was compiled. Internally, the +commands look for C frames that are executing PyEval_EvalFrameEx (which +implements the core bytecode interpreter loop within CPython) and look up +the value of the related PyFrameObject *.

      +

      They emit the frame number (at the C level) within the thread.

      +

      For example:

      +
      (gdb) py-up
+#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/
+gnome_sudoku/main.py, line 906, in start_game ()
+    u = UI()
+(gdb) py-up
+#40 Frame 0x948e82c, for file /usr/lib/python2.6/site-packages/
+gnome_sudoku/gnome_sudoku.py, line 22, in start_game(main=<module at remote 0xb771b7f4>)
+    main.start_game()
+(gdb) py-up
+Unable to find an older python frame
+
      +
      +

      so we’re at the top of the python stack. Going back down:

      +
      (gdb) py-down
+#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/gnome_sudoku/main.py, line 906, in start_game ()
+    u = UI()
+(gdb) py-down
+#34 (unable to read python frame information)
+(gdb) py-down
+#23 (unable to read python frame information)
+(gdb) py-down
+#19 (unable to read python frame information)
+(gdb) py-down
+#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/game_selector.py, line 201, in run_swallowed_dialog (self=<NewOrSavedGameSelector(new_game_model=<gtk.ListStore at remote 0x98fab44>, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, 'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\n7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': <float at remote 0x984b474>, 'gsd.hints': 0, 'timer.active_time': <float at remote 0x984b494>, 'timer.total_time': <float at remote 0x984b464>}], dialog=<gtk.Dialog at remote 0x98faaa4>, saved_game_model=<gtk.ListStore at remote 0x98fad24>, sudoku_maker=<SudokuMaker(terminated=False, played=[], batch_siz...(truncated)
+            swallower.run_dialog(self.dialog)
+(gdb) py-down
+#11 Frame 0x9aead74, for file /usr/lib/python2.6/site-packages/gnome_sudoku/dialog_swallower.py, line 48, in run_dialog (self=<SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>, main_page=0) at remote 0x98fa6e4>, d=<gtk.Dialog at remote 0x98faaa4>)
+            gtk.main()
+(gdb) py-down
+#8 (unable to read python frame information)
+(gdb) py-down
+Unable to find a newer python frame
+
      +
      +

      and we’re at the bottom of the python stack.

      +
      +
      py-bt
      +

      The py-bt command attempts to display a Python-level backtrace of the +current thread.

      +

      For example:

      +
      (gdb) py-bt
+#8 (unable to read python frame information)
+#11 Frame 0x9aead74, for file /usr/lib/python2.6/site-packages/gnome_sudoku/dialog_swallower.py, line 48, in run_dialog (self=<SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>, main_page=0) at remote 0x98fa6e4>, d=<gtk.Dialog at remote 0x98faaa4>)
+            gtk.main()
+#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/game_selector.py, line 201, in run_swallowed_dialog (self=<NewOrSavedGameSelector(new_game_model=<gtk.ListStore at remote 0x98fab44>, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, 'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\n7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': <float at remote 0x984b474>, 'gsd.hints': 0, 'timer.active_time': <float at remote 0x984b494>, 'timer.total_time': <float at remote 0x984b464>}], dialog=<gtk.Dialog at remote 0x98faaa4>, saved_game_model=<gtk.ListStore at remote 0x98fad24>, sudoku_maker=<SudokuMaker(terminated=False, played=[], batch_siz...(truncated)
+            swallower.run_dialog(self.dialog)
+#19 (unable to read python frame information)
+#23 (unable to read python frame information)
+#34 (unable to read python frame information)
+#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/gnome_sudoku/main.py, line 906, in start_game ()
+    u = UI()
+#40 Frame 0x948e82c, for file /usr/lib/python2.6/site-packages/gnome_sudoku/gnome_sudoku.py, line 22, in start_game (main=<module at remote 0xb771b7f4>)
+    main.start_game()
+
      +
      +

      The frame numbers correspond to those displayed by gdb’s standard backtrace command.

      +
      +
      py-print
      +

      The py-print command looks up a Python name and tries to print it. It looks in locals within the current thread, then globals, then finally builtins:

      +
      (gdb) py-print self
+local 'self' = <SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>,
+main_page=0) at remote 0x98fa6e4>
+(gdb) py-print __name__
+global '__name__' = 'gnome_sudoku.dialog_swallower'
+(gdb) py-print len
+builtin 'len' = <built-in function len>
+(gdb) py-print scarlet_pimpernel
+'scarlet_pimpernel' not found
+
      +
      +
      +
      py-locals
      +

      The py-locals command looks up all Python locals within the current Python frame in the selected thread, and prints their representations:

      +
      (gdb) py-locals
+self = <SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>,
+main_page=0) at remote 0x98fa6e4>
+d = <gtk.Dialog at remote 0x98faaa4>
+
      +
      +
      +
      +

      You can of course use other gdb commands. For example, the frame command takes you directly to a particular frame within the selected thread. We can use it to go a specific frame shown by py-bt like this:

      +
      (gdb) py-bt
+(output snipped)
+#68 Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in <module> ()
+        main()
+(gdb) frame 68
+#68 0x00000000004cd1e6 in PyEval_EvalFrameEx (f=Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in <module> (), throwflag=0) at Python/ceval.c:2665
+2665                            x = call_function(&sp, oparg);
+(gdb) py-list
+1543        # Run the tests in a context manager that temporary changes the CWD to a
+1544        # temporary and writable directory. If it's not possible to create or
+1545        # change the CWD, the original CWD will be used. The original CWD is
+1546        # available from test_support.SAVEDCWD.
+1547        with test_support.temp_cwd(TESTCWD, quiet=True):
+>1548            main()
+
      +
      +

      The info threads command will give you a list of the threads within the process, and you can use the thread command to select a different one:

      +
      (gdb) info threads
+  105 Thread 0x7fffefa18710 (LWP 10260)  sem_wait () at ../nptl/sysdeps/unix/sysv/linux/x86_64/sem_wait.S:86
+  104 Thread 0x7fffdf5fe710 (LWP 10259)  sem_wait () at ../nptl/sysdeps/unix/sysv/linux/x86_64/sem_wait.S:86
+* 1 Thread 0x7ffff7fe2700 (LWP 10145)  0x00000038e46d73e3 in select () at ../sysdeps/unix/syscall-template.S:82
+
      +
      +

      You can use thread apply all COMMAND or (t a a COMMAND for short) to run a command on all threads. You can use this with py-bt to see what every thread is doing at the Python level:

      +
      (gdb) t a a py-bt
+
+Thread 105 (Thread 0x7fffefa18710 (LWP 10260)):
+#5 Frame 0x7fffd00019d0, for file /home/david/coding/python-svn/Lib/threading.py, line 155, in _acquire_restore (self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=<thread.lock at remote 0x858770>, _RLock__count=1) at remote 0xd7ff40>, count_owner=(1, 140737213728528), count=1, owner=140737213728528)
+        self.__block.acquire()
+#8 Frame 0x7fffac001640, for file /home/david/coding/python-svn/Lib/threading.py, line 269, in wait (self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=<thread.lock at remote 0x858770>, _RLock__count=1) at remote 0xd7ff40>, acquire=<instancemethod at remote 0xd80260>, _is_owned=<instancemethod at remote 0xd80160>, _release_save=<instancemethod at remote 0xd803e0>, release=<instancemethod at remote 0xd802e0>, _acquire_restore=<instancemethod at remote 0xd7ee60>, _Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, timeout=None, waiter=<thread.lock at remote 0x858a90>, saved_state=(1, 140737213728528))
+            self._acquire_restore(saved_state)
+#12 Frame 0x7fffb8001a10, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 348, in f ()
+            cond.wait()
+#16 Frame 0x7fffb8001c40, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 37, in task (tid=140737213728528)
+                f()
+
+Thread 104 (Thread 0x7fffdf5fe710 (LWP 10259)):
+#5 Frame 0x7fffe4001580, for file /home/david/coding/python-svn/Lib/threading.py, line 155, in _acquire_restore (self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=<thread.lock at remote 0x858770>, _RLock__count=1) at remote 0xd7ff40>, count_owner=(1, 140736940992272), count=1, owner=140736940992272)
+        self.__block.acquire()
+#8 Frame 0x7fffc8002090, for file /home/david/coding/python-svn/Lib/threading.py, line 269, in wait (self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=<thread.lock at remote 0x858770>, _RLock__count=1) at remote 0xd7ff40>, acquire=<instancemethod at remote 0xd80260>, _is_owned=<instancemethod at remote 0xd80160>, _release_save=<instancemethod at remote 0xd803e0>, release=<instancemethod at remote 0xd802e0>, _acquire_restore=<instancemethod at remote 0xd7ee60>, _Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, timeout=None, waiter=<thread.lock at remote 0x858860>, saved_state=(1, 140736940992272))
+            self._acquire_restore(saved_state)
+#12 Frame 0x7fffac001c90, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 348, in f ()
+            cond.wait()
+#16 Frame 0x7fffac0011c0, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 37, in task (tid=140736940992272)
+                f()
+
+Thread 1 (Thread 0x7ffff7fe2700 (LWP 10145)):
+#5 Frame 0xcb5380, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 16, in _wait ()
+    time.sleep(0.01)
+#8 Frame 0x7fffd00024a0, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 378, in _check_notify (self=<ConditionTests(_testMethodName='test_notify', _resultForDoCleanups=<TestResult(_original_stdout=<cStringIO.StringO at remote 0xc191e0>, skipped=[], _mirrorOutput=False, testsRun=39, buffer=False, _original_stderr=<file at remote 0x7ffff7fc6340>, _stdout_buffer=<cStringIO.StringO at remote 0xc9c7f8>, _stderr_buffer=<cStringIO.StringO at remote 0xc9c790>, _moduleSetUpFailed=False, expectedFailures=[], errors=[], _previousTestClass=<type at remote 0x928310>, unexpectedSuccesses=[], failures=[], shouldStop=False, failfast=False) at remote 0xc185a0>, _threads=(0,), _cleanups=[], _type_equality_funcs={<type at remote 0x7eba00>: <instancemethod at remote 0xd750e0>, <type at remote 0x7e7820>: <instancemethod at remote 0xd75160>, <type at remote 0x7e30e0>: <instancemethod at remote 0xd75060>, <type at remote 0x7e7d20>: <instancemethod at remote 0xd751e0>, <type at remote 0x7f19e0...(truncated)
+        _wait()
+
      +
      +
      +

      Note

      +

      This is only available for Python 2.7, 3.2 and higher.

      +
      +
      +
      +

      24.2. gdb 6 and earlier

      +

      The file at Misc/gdbinit contains a gdb configuration file which provides +extra commands when working with a CPython process. To register these commands +permanently, either copy the commands to your personal gdb configuration file +or symlink ~/.gdbinit to Misc/gdbinit. To use these commands from +a single gdb session without registering them, type source Misc/gdbinit +from your gdb session.

      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      23. Emacs support

      +

      Next topic

      +

      25. Changing CPython’s Grammar

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/genindex.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/genindex.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,142 @@ + + + + + + + + + Index — Python Developer's Guide + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + + +

      Index

      + +
      + P + +
      +

      P

      + + + +
      + +
      PEP process +
      + +
      + +
      in FAQ +
      + +
      +
      + +
      + Python Enhancement Proposals +
      + +
      + +
      PEP 1 +
      + + +
      PEP 291 +
      + + +
      PEP 360 +
      + + +
      PEP 387 +
      + + +
      PEP 7, [1] +
      + + +
      PEP 8, [1] +
      + +
      +
      + + + +
      +
      +
      +
      +
      + + + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/grammar.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/grammar.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,166 @@ + + + + + + + + 25. Changing CPython’s Grammar — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      25. Changing CPython’s Grammar

      +
      +

      25.1. Abstract

      +

      There’s more to changing Python’s grammar than editing +Grammar/Grammar and Python/compile.c. This document aims to be a +checklist of places that must also be fixed.

      +

      It is probably incomplete. If you see omissions, submit a bug or patch.

      +

      This document is not intended to be an instruction manual on Python +grammar hacking, for several reasons.

      +
      +
      +

      25.2. Rationale

      +

      People are getting this wrong all the time; it took well over a +year before someone noticed +that adding the floor division +operator (//) broke the parser module.

      +
      +
      +

      25.3. Checklist

      +
        +
      • Grammar/Grammar: OK, you’d probably worked this one out :)
        • +
      • Parser/Python.asdl may need changes to match the Grammar. Run make to +regenerate Include/Python-ast.h and Python/Python-ast.c.
        • +
      • Python/ast.c will need changes to create the AST objects involved with the +Grammar change.
        • +
      • Parser/pgen needs to be rerun to regenerate Include/graminit.h and +Python/graminit.c. (make should handle this for you.)
        • +
      • Python/symtable.c: This handles the symbol collection pass +that happens immediately before the compilation pass.
        • +
      • Python/compile.c: You will need to create or modify the +compiler_* functions to generate opcodes for your productions.
        • +
      • You may need to regenerate Lib/symbol.py and/or Lib/token.py +and/or Lib/keyword.py.
        • +
      • The parser module. Add some of your new syntax to test_parser, +bang on Modules/parsermodule.c until it passes.
        • +
      • Add some usage of your new syntax to test_grammar.py
        • +
      • If you’ve gone so far as to change the token structure of +Python, then the Lib/tokenizer.py library module will need to be changed.
        • +
      • Certain changes may require tweaks to the library module pyclbr.
        • +
      • Documentation must be written!
        • +
      • After everything has been checked in, you’re likely to see a new +change to Python/Python-ast.c. This is because this +(generated) file contains the hg version of the source from +which it was generated. There’s no way to avoid this; you just +have to submit this file separately.
        • +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      24. gdb Support

      +

      Next topic

      +

      26. Design of CPython’s Compiler

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/help.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/help.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,166 @@ + + + + + + + + 3. Where to Get Help — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      3. Where to Get Help

      +

      If you are working on Python it is very possible you will come across an issue +where you need some assistance to solve it (this happens to core developers +all the time).

      +

      Should you require help, there are a variety of options available to seek assistance. If the question involves process or tool +usage then please check the rest of this guide first (especially the +Python Developer FAQ) as it should answer your question.

      +
      +

      3.1. Ask #python-dev

      +

      If you are comfortable with IRC you can try asking on #python-dev (on +the freenode network). Typically there are a number of experienced +developers, ranging from triagers to core developers, who can answer +questions about developing for Python. Just remember that #python-dev +is for questions involving the development of Python whereas #python +is for questions concerning development with Python.

      +
      +
      +

      3.2. Core Mentorship

      +

      If you are interested in improving Python and contributing to its development, +but don’t yet feel entirely comfortable with the public channels mentioned +above, Python Mentors are here to help you. Python is fortunate to have a +community of volunteer core developers willing to mentor anyone wishing to +contribute code, work on bug fixes or improve documentation. Everyone is +welcomed and encouraged to contribute.

      +
      +
      +

      3.3. Mailing Lists

      +

      Further options for seeking assistance include the python-ideas and +python-dev mailing lists. Python-ideas contains discussion of speculative +Python language ideas for possible inclusion into the language. If an idea +gains traction it can then be discussed and honed to the point of becoming a +solid proposal and presented on python-dev. Python-dev contains discussion +of current Python design issues, release mechanics, and maintenance of +existing releases. As with #python-dev, these mailing lists are for +questions involving the development of Python, not for development +with Python.

      +
      +
      +

      3.4. File a Bug

      +

      If you strongly suspect you have stumbled on a bug (be it in the build +process, in the test suite, or in other areas), then open an issue on the +issue tracker. As with every bug report it is strongly advised that +you detail which conditions triggered it (including the OS name and version, +and what you were trying to do), as well as the exact error message you +encountered.

      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      2. Setting Up Windows - Advanced

      +

      Next topic

      +

      4. Lifecycle of a Patch

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/index.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/index.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,703 @@ + + + + + + + + Python Developer’s Guide — Python Developer's Guide + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      Python Developer’s Guide

      +

      This guide is a comprehensive resource for contributing +to Python – for both new and experienced contributors. It is +maintained by the same community +that maintains Python. We welcome your contributions to Python!

      +
      +

      Quick Start

      +

      Here are the basic steps needed to get set up and contribute a +patch:

      +
        +

      1. Get the source code:

        +
        hg clone http://hg.python.org/cpython
+
        +
        +
        2. +

      2. Build Python. On UNIX:

        +
        ./configure --with-pydebug && make -j2
+
        +
        +

        On Windows, open the solution file +PCbuild\pcbuild.sln in Visual Studio, select Debug, +and Build ‣ Build Solution. Run +Tools\buildbot\external.bat or +Tools\buildbot\external-amd64.bat to download and compile 3rd +party libraries. Note: Visual Studio may throw errors, but Python will +be built.

        +
        3. +

      3. Run the tests:

        +
        ./python -m test -j3
+
        +
        +

        On most Mac OS X systems, replace ./python +with ./python.exe. On Windows, use PCbuild\python_d.exe or +check the Windows instructions. With Python 2.7, +replace test with test.regrtest.

        +
        4. +

      4. Make the patch.

        +
        5. +

      5. Submit it to the issue tracker.

        +
        6. +
      +
      + +
      +

      Contributing

      +

      We encourage everyone to contribute to Python and that’s why we have put up this +developer’s guide. If you still have questions after reviewing the material in +this guide, then the Python Mentors group is available to help guide new +contributors through the process. The Developer FAQ is another +useful source of information.

      +

      Guide for contributing to Python:

      + +

      It is recommended that the above documents be read in the order listed. You +can stop where you feel comfortable and begin contributing immediately without +reading and understanding these documents all at once. If you do choose to skip +around within the documentation, be aware that it is written assuming preceding +documentation has been read so you may find it necessary to backtrack to fill in +missing concepts and terminology.

      +
      +
      +

      Proposing changes to Python itself

      +

      Improving Python’s code, documentation and tests are ongoing tasks that are +never going to be “finished”, as Python operates as part of an ever-evolving +system of technology. An even more challenging ongoing task than these +necessary maintenance activities is finding ways to make Python, in the form of +the standard library and the language definition, an even better tool in a +developer’s toolkit.

      +

      While these kinds of change are much rarer than those described above, they do +happen and that process is also described as part of this guide:

      + +

      Also refer to Where should I suggest new features and language changes? in the FAQ.

      +
      +
      +

      Other Interpreter Implementations

      +

      This guide is specifically for contributing to the Python reference interpreter, +also known as CPython (while most of the standard library is written in Python, +the interpreter core is written in C and integrates most easily with the C and +C++ ecosystems).

      +

      There are other Python implementations, each with a different focus. Like +CPython, they always have more things they would like to do than they have +developers to work on them. Some major example that may be of interest are:

      +
        +
      • PyPy: A Python interpreter focused on high speed (JIT-compiled) operation +on major platforms
        • +
      • Jython: A Python interpreter focused on good integration with the Java +Virtual Machine (JVM) environment
        • +
      • IronPython: A Python interpreter focused on good integration with the +Common Language Runtime (CLR) provided by .NET and Mono
        • +
      • Stackless: A Python interpreter focused on providing lightweight +microthreads while remaining largely compatible with CPython specific +extension modules
        • +
      +
      +
      +

      Key Resources

      + +
      +
      +

      Additional Resources

      + +
      +
      +

      Full Table of Contents

      +
      + +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Next topic

      +

      1. Getting Started

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/langchanges.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/langchanges.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,167 @@ + + + + + + + + 21. Changing the Python Language — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      21. Changing the Python Language

      +

      On occasion people come up with an idea on how to change or improve Python as a +programming language. This document is meant to explain exactly what changes +have a reasonable chance of being considered and what the process is to propose +changes to the language.

      +
      +

      21.1. What Qualifies

      +

      First and foremost, it must be understood that changes to the Python +programming language are difficult to make. When the language changes, +every Python programmer already in existence and all Python programmers to +come will end up eventually learning about the change you want to propose. +Books will need updating, code will be changed, and a new way to do things will +need to be learned. Changes to the Python programming language are never taken +lightly.

      +

      Because of the seriousness that language changes carry, any change must be +beneficial to a large proportion of Python users. If the change only benefits a +small percentage of Python developers then the change will not be made. A good +way to see if your idea would work for a large portion of the Python community +is to ask on python-list or python-ideas. You can also +go through Python’s stdlib and find examples of code which would benefit from +your proposed change (which helps communicate the usefulness of your change to +others). For further guidance, see Where should I suggest new features and language changes? in the FAQ.

      +

      Your proposed change also needs to be Pythonic. While Guido is the only +person who can truly classify something as Pythonic, you can read the Zen of +Python for guidance.

      +
      +
      +

      21.2. PEP Process

      +

      Once you are certain you have a language change proposal which will appeal to +the general Python community, you can begin the process of officially proposing +the change. This process is the Python Enhancement Proposal (PEP) process. +PEP 1 describes it in detail.

      +

      You will first need a PEP that you will present to python-ideas. You may be a +little hazy on the technical details as various core developers can help with +that, but do realize that if you do not present your idea to python-ideas or +python-list ahead of time you may find out it is technically not possible +(e.g., Python’s parser will not support the grammar change as it is an LL(1) +parser). Expect extensive comments on the PEP, some of which will be negative.

      +

      Once your PEP has been modified to be of proper quality and to take into +account comments made on python-ideas, it may proceed to python-dev. There it +will be assigned a PEP dictator and another general discussion will occur. Once +again, you will need to modify your PEP to incorporate the large amount of +comments you will receive.

      +

      The PEP dictator decides if your PEP is accepted (typically based on whether +most core developers support the PEP). If that occurs then your proposed +language change will be introduced in the next release of Python. Otherwise +your PEP will be recorded as rejected along with an explanation as to why so +that others do not propose the same language change in the future.

      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      20. Adding to the Stdlib

      +

      Next topic

      +

      22. Experts Index

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/objects.inv Binary file build/objects.inv has changed diff -r 85f290e474e2 build/patch.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/patch.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,275 @@ + + + + + + + + 4. Lifecycle of a Patch — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      4. Lifecycle of a Patch

      +
      +

      4.1. Creating

      +
      +

      4.1.1. Tool Usage

      +

      Mercurial allows for various workflows according to each person’s or +project’s preference. It is out of this guide’s scope to present them all, +so we will stick to a basic workflow where you work on a patch in your +working copy without ever making any local commits.

      +

      If you use this workflow, and your work adds or removes files to the +source tree, you will have to temporarily hg add or hg remove them, +respectively, before generating a patch.

      +

      To generate a patch, just invoke hg diff which will print out a +patch of the working copy’s changes against the current revision:

      +
      hg diff > mywork.patch
+
      +
      +

      If you want to undo your changes, you can revert them from the working copy:

      +
      hg revert -a
+
      +
      +

      You can later re-apply the changes if you want to continue working on the +patch:

      +
      hg import --no-commit mywork.patch
+
      +
      +
      +

      See also

      +

      Refer to the FAQ for +more information on using Mercurial.

      +
      +
      +
      +

      4.1.2. Preparation

      +

      When creating a patch for submission, there are several things that you should +do to help ensure that your patch is accepted.

      +

      First, make sure to follow Python’s style guidelines. For Python code you +should follow PEP 8, and for C code you should follow PEP 7. If you have +one or two discrepancies those can be fixed by the core developer who commits +your patch. But if you have systematic deviations from the style guides your +patch will be put on hold until you fix the formatting issues.

      +

      Second, be aware of backwards-compatibility considerations. While the core +developer who eventually handles your patch will make the final call on whether +something is acceptable, thinking about backwards-compatibility early +will help prevent having your patch rejected on these grounds. Put yourself in +the shoes of someone whose code will be broken by the change(s) introduced by +the patch. It is quite likely that any change made will break +someone’s code, so you need to have a good reason to make a change as you will +be forcing someone to update their code. (This obviously does not apply to new +classes or functions; new arguments should be optional and have default values +which maintain the existing behavior.) If in doubt, have a look at +PEP 387 or discuss the issue with experienced +developers.

      +

      Third, make sure you have proper tests to verify your patch works as expected. +Patches will not be accepted without the proper tests!

      +

      Fourth, make sure the entire test suite runs without +failure because of your changes. It is not sufficient to only run whichever +test seems impacted by your changes, because there might be interferences +unknown to you between your changes and some other part of the interpreter.

      +

      Fifth, proper documentation +additions/changes should be included.

      +
      +
      +

      4.1.3. Generation

      +

      To perform a quick sanity check on your patch, you can run:

      +
      make patchcheck
+
      +
      +

      This will check and/or fix various common things people forget to do for +patches, such as adding any new files needed for the patch to work (note +that not all checks apply to non-core developers). On Windows, use this +command:

      +
      ./python.exe Tools/scripts/patchcheck.py
+
      +
      +

      Assuming you are using the basic approach suggested earlier, +just type the following:

      +
      hg diff > mywork.patch
+
      +
      +

      If you are using another approach, you probably need to find out the right +invocation of hg diff for your purposes; see hg help diff and hg +help revisions. Just please make sure that you generate a +single, condensed patch rather than a series of several changesets.

      +
      +
      +
      +

      4.2. Licensing

      +

      For non-trivial changes, we must have your formal approval for distributing +your work under the PSF license. Therefore, you need to fill out a +contributor form which allows the Python Software Foundation to +license your code for use with Python (you retain the copyright).

      +
      +

      Note

      +

      You only have to sign this document once, it will then apply to all +your further contributions to Python.

      +
      +
      +
      +

      4.3. Submitting

      +

      If this is a patch in response to a pre-existing issue on the issue tracker, +attach the patch to the issue; use the Choose File button on the tracker +web page for the issue to upload your patch file. Please provide any details +about your patch that +would be relevant to the discussion of the issue or your patch.

      +

      If this is a patch for an unreported issue (assuming you already performed a +search on the issue tracker for a pre-existing issue), create a new issue and +attach your patch. Please fill in as much relevant detail as possible to +prevent patch reviewers from having to delay reviewing your patch because of +lack of information.

      +
      +
      +

      4.4. Reviewing

      +

      To begin with, please be patient! There are many more people submitting patches +than there are people capable of reviewing your patch. Getting your patch +reviewed requires a reviewer to have the spare time and motivation to +look at your patch (we cannot force anyone to review patches). If your patch has +not received any notice from reviewers (i.e., no comment made) after one +month, first “ping” the issue on the issue tracker to remind the nosy list +that the patch needs a review. If you don’t get a response within a few days +after pinging the issue, then you can try emailing python-dev@python.org asking +for someone to review your patch.

      +

      When someone does manage to find the time to look at your patch they will most +likely make comments about how it can be improved (don’t worry, even core +developers of Python have their patches sent back to them for changes). It +is then expected that you post a new patch addressing these comments, and the +review process will thus iterate until a satisfactory solution has emerged.

      +
      +
      +

      4.5. Committing/Rejecting

      +

      Once your patch has reached an acceptable state (and thus considered +“accepted”), it will either be committed or rejected. If it is rejected, please +do not take it personally! Your work is still appreciated regardless of whether +your patch is committed. Balancing what does and does not go into Python +is tricky and we simply cannot accept everyone’s contributions.

      +

      But if your patch is committed it will then go into Python’s +VCS to be released +with the next major release of Python. It may also be backported to older +versions of Python as a bugfix if the core developer doing the commit believes +it is warranted.

      +
      +
      +

      4.6. Crediting

      +

      Non-trivial contributions are credited in the Misc/ACKS file (and, most +often, in a contribution’s Misc/NEWS entry as well). This is something +the core developer will do when committing your patch, you don’t have to +propose the addition by yourself.

      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      3. Where to Get Help

      +

      Next topic

      +

      5. Running & Writing Tests

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/runtests.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/runtests.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,223 @@ + + + + + + + + 5. Running & Writing Tests — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      5. Running & Writing Tests

      +
      +

      Note

      +

      This document assumes you are working from an +in-development checkout of Python. If you +are not then some things presented here may not work as they may depend +on new features not available in earlier versions of Python.

      +
      +
      +

      5.1. Running

      +

      The shortest, simplest way of running the test suite is the following command +from the root directory of your checkout (after you have built Python):

      +
      ./python -m test
+
      +
      +

      You may need to change this command as follows throughout this section. +On most Mac OS X systems, replace ./python +with ./python.exe. On Windows, use PCbuild\python_d.exe or +check the detailed Windows instructions. If using +Python 2.7, replace test with test.regrtest.

      +

      If you don’t have easy access to a command line, you can run the test suite from +a Python or IDLE shell:

      +
      >>> from test import autotest
+
      +
      +

      This will run the majority of tests, but exclude a small portion of them; these +excluded tests use special kinds of resources: for example, accessing the +Internet, or trying to play a sound or to display a graphical interface on +your desktop. They are disabled by default so that running the test suite +is not too intrusive. To enable some of these additional tests (and for +other flags which can help debug various issues such as reference leaks), read +the help text:

      +
      ./python -m test -h
+
      +
      +

      If you want to run a single test, simply specify the test name as an argument. +You also probably want to enable verbose mode (using -v), so that individual +failures are detailed:

      +
      ./python -m test -v test_abc
+
      +
      +

      If you have a multi-core or multi-CPU machine, you can enable parallel testing +using several Python processes so as to speed up things:

      +
      ./python -m test -j0
+
      +
      +

      If you are running a version of Python prior to 3.3 you must specify the number +of processes to run simultaneously (e.g. -j2).

      +

      Finally, if you want to run tests under a more strenuous set of settings, you +can run test as:

      +
      ./python -bb -E -Wd -m test -r -w -uall
+
      +
      +

      The various extra flags passed to Python cause it to be much stricter about +various things (the -Wd flag should be -W error at some point, but the +test suite has not reached a point where all warnings have been dealt with and +so we cannot guarantee that a bug-free Python will properly complete a test run +with -W error). The -r flag to the test runner causes it to run tests in +a more random order which helps to check that the various tests do not interfere +with each other. The -w flag causes failing tests to be run again to see +if the failures are transient or consistent. +The -uall flag allows the use of all available +resources so as to not skip tests requiring, e.g., Internet access.

      +

      To check for reference leaks (only needed if you modified C code), use the +-R flag. For example, -R 3:2 will first run the test 3 times to settle +down the reference count, and then run it 2 more times to verify if there are +any leaks.

      +

      You can also execute the Tools/scripts/run_tests.py script as found in a +CPython checkout. The script tries to balance speed with thoroughness. But if +you want the most thorough tests you should use the strenuous approach shown +above.

      +
      +

      5.1.1. Unexpected Skips

      +

      Sometimes when running the test suite, you will see “unexpected skips” +reported. These represent cases where an entire test module has been +skipped, but the test suite normally expects the tests in that module to +be executed on that platform.

      +

      Often, the cause is that an optional module hasn’t been built due to missing +build dependencies. In these cases, the missing module reported when the test +is skipped should match one of the modules reported as failing to build when +Compiling (for debugging).

      +

      In other cases, the skip message should provide enough detail to help figure +out and resolve the cause of the problem (for example, the default security +settings on some platforms will disallow some tests)

      +
      +
      +
      +

      5.2. Writing

      +

      Writing tests for Python is much like writing tests for your own code. Tests +need to be thorough, fast, isolated, consistently repeatable, and as simple as +possible. We try to have tests both for normal behaviour and for error +conditions. Tests live in the Lib/test directory, where every file that +includes tests has a test_ prefix.

      +

      One difference with ordinary testing is that you are encouraged to rely on the +test.support module. It contains various helpers that are tailored to +Python’s test suite and help smooth out common problems such as platform +differences, resource consumption and cleanup, or warnings management. +That module is not suitable for use outside of the standard library.

      +

      When you are adding tests to an existing test file, it is also recommended +that you study the other tests in that file; it will teach you which precautions +you have to take to make your tests robust and portable.

      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      4. Lifecycle of a Patch

      +

      Next topic

      +

      6. Increase Test Coverage

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/search.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/search.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,99 @@ + + + + + + + + Search — Python Developer's Guide + + + + + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +

      Search

      +
      + +

      + Please activate JavaScript to enable the search + functionality. +

      +
      +

      + From here you can search these documents. Enter your search + words into the box below and click "search". Note that the search + function will automatically search for all of the words. Pages + containing fewer words won't appear in the result list. +

      +
      + + + +
      + +
      + +
      + +
      +
      +
      +
      +
      +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/searchindex.js --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/searchindex.js Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,1 @@ +Search.setIndex({objects:{},objnames:{},filenames:["gdb","silencewarnings","emacs","triaging","langchanges","buildbots","coverage","index","setupwindows","patch","stdlibchanges","faq","docquality","fixingissues","coredev","devcycle","setup","runtests","experts","clang","communication","grammar","documenting","developers","tracker","compiler","committing","help","coverity"],titles:["24. gdb Support","9. Silence Warnings From the Test Suite","23. Emacs support","12. Triaging an Issue","21. Changing the Python Language","19. Continuous Integration","6. Increase Test Coverage","Python Developer’s Guide","2. Setting Up Windows - Advanced","4. Lifecycle of a Patch","20. Adding to the Stdlib","29. Python Developer FAQ","7. Helping with Documentation","10. Fixing “easy” Issues (and Beyond)","14. How to Become a Core Developer","18. Development Cycle","1. Getting Started","5. Running & Writing Tests","22. Experts Index","28. Dynamic Analysis with Clang","13. Following Python’s Development","25. Changing CPython’s Grammar","8. Documenting Python","15. Developer Log","11. Issue Tracking","26. Design of CPython’s Compiler","16. Committing and Pushing Changes","3. Where to Get Help","27. Coverity Scan"],terms:{blogger:20,addop_jab:25,mailbox:[23,18],suspect:[27,19],enjoi:[14,20],wont:3,copyreg:18,analyz:[22,19,28],harder:[22,12],cannot:[15,17,3,0,19,5,22,9,6,28],cid:28,"_rlock":0,krah:23,mpatch:11,longest:5,languish:3,iceland:23,inclin:22,semant:[6,22,15,26],middl:[22,11],filecmp:18,shelv:18,benchmark:[25,18,3],abid:11,when:[],clean:[11,5,8],divis:21,conserv:[6,10],"0x0c327fff8810":19,stop:7,ticket:28,calcul:[25,6],timer:0,workflow:[],did:[24,14],venv:18,tackl:[12,1,13],span:[22,5],thread:[0,19,23,5,18],gaynor:23,alphabet:23,"3a0":5,five:22,audioop_getsample_impl:19,constant:22,reedi:[23,18],breviti:5,call_funct:[25,0],irix:22,xlinker:19,alexandr:[23,18],persist:5,alfr:25,stall:[22,14],doug:23,py_begin_allow_thread:22,previou:[6,22,11,10,15],git:[],over:[10,3,19,21,5,22,6],acronym:25,thisi:22,touch:[25,16,26,28],pycodeobject:25,putti:11,respond:[10,14,18],redzon:19,radio:11,lookup:25,everyon:[],"0x63f636":19,gone:[6,21,10],configpars:18,tex:23,mac:[16,17,18,3,19,7,22,23],legaci:[16,3],delimit:22,dev:[],brows:7,anoth:[10,26,3,4,7,8,9,6,11],testcwd:0,"0xd80160":0,segfault:22,move:[0,10,11,3],foremost:[4,14],"0x7fffe4001580":0,charl:23,need:[],head:[],"3regress":3,shift:[15,19],comment:[],settl:17,"0x000000000044060a":0,now:[15,26,3,23,24,25,6,11,14,28],parenthes:22,aurel32:19,absenc:19,stdio:[22,5],compiler_:21,suspici:[22,19,28],x86_64:[0,19,5],happen:[15,26,27,21,5,7,22,24,6,11,12],dozen:23,desir:[16,26,19,22,24,6,11],notabl:26,test_multiprocess:5,dec:23,interest:[26,18,3,27,19,5,20,7,22,24,6,12],chosen:[16,10,26,3,22,25],perl:8,return_kind:25,quickli:[22,1,24],ethan:[23,18],forum:11,four:22,variabl:[16,19,22,25,11,28],melodramat:14,project:[],"return":[0,19,22,25,11,28],stringo:0,him:[23,3],func:22,displai:[],proce:[4,1,8],facil:22,regrtest:[],johann:23,notifi:26,sens:6,anyon:[9,7,11,27,14],temporari:0,printf:22,depth:[25,22,26],brace:22,requir:16,consumpt:[22,17],focus:[7,11,22,20],rerun:21,repo:[11,3],wish:[6,27,11,5,14],yasskin:23,"0x000000000041a6b1":0,examin:[11,19],asyncio:18,match:[16,17,21,0,22,11,14],doesn:[16,26,3,0,22,6,11,28],commonli:22,modifi:[],rchild:25,chest:19,someon:[10,26,3,21,9,11,12,14],emerg:9,wolev:23,follow:[],spare:9,tab:22,nitem:22,inclus:[27,10,26],productionlist:22,pend:[11,3],spammi:26,macintosh:3,test_contain:5,numer:[25,22],curiou:22,initi:[],turtl:[23,18],toolkit:7,"long":[],pat:23,unforeseen:26,job:6,posixmodul:28,argpars:18,associ:[11,26],same:[],irmen:23,malform:22,try_stmt:22,classif:[13,28],appear:[6,22,11,26,3],diagnos:[0,5],foster:11,xicluna:23,meaning:22,namespac:[25,22],shutil:18,amet:22,portion:[4,19,10,22,17],asdl_seq_len:25,py3:18,revert:[],team:[22,23,24],pwd:[6,18],overhead:15,have:[],dylib:19,readm:[16,8],uncov:[19,12],rodrigo:23,come:[],libclang_rt:19,multi:[16,17,3],where:[],instanc:[16,0,19,22,24,25,6],warn:16,next:[15,3,4,19,5,22,24,25,9,11],substitut:[],none:[22,0],run_test:17,sandro:23,jackilyn:23,java:[7,28,18],side:[25,22,26],reput:14,randal:23,sax:18,imperfect:5,disput:11,lang:20,toolset:[22,23],librarydepend:19,monson:23,dictat:[4,10],typic:[15,16,1,10,3,26,4,27,22,8,25,6,11,13,14],dpy_build_cor:19,bleed:6,attempt:[22,0,11,13,8],strive:6,throwflag:0,"0x0c327fff8800":19,exploit:15,georg:[15,23,18],bac:23,distclean:11,ambassador:14,from:[],declar:25,"_condition__lock":0,principl:[25,26],snippet:22,anew:16,meador:[23,18],dakshesh:28,treat:[11,10],error:[16,26,17,3,27,0,19,7,22,24,8,6],signifi:22,inc:19,contrib:23,pseudo:22,uncheck:[16,28],primari:[25,22,20],openhatch:16,search:[10,3,19,5,7,22,24,25,9,11],livinglog:6,freed:[25,19,28],higher:[0,11],egg:22,shell:[22,11,2,17],"0x99262ac":0,render:[22,18],forgeotdarc:18,establish:[22,10],intrus:17,underli:0,enough:[15,16,26,17,3,19,5,22,24,12,13],pyconfig:[11,26],lib2to3:[18,3],studio:16,minimum:[19,16],origin:[25,0,26,23],urllib:18,back:[],luck:5,layout:24,jython:[7,23],peer:15,encount:[22,19,16,27],pyobject_fre:19,clariti:[22,19],jess:23,expans:22,directli:[10,26,3,18,0,22,23,25,11,12],summari:[],guilabel:22,horribl:6,truncat:0,rodolà:23,pyimport_importfrozenmoduleobject:19,binascii:18,asdl_seq_get:25,supersed:[],peephol:25,newsgroup:[22,20],space:22,invalid:[22,3],oparg:0,comma:22,oct:[22,23],pyunicodeucs2_decodeutf8st:0,outlin:[25,11,16,10],ever:[9,7],killer:2,prescod:23,implic:[22,3],"function":[16,10,3,0,19,21,20,22,8,25,9,6,11,28],solid:27,"0x7fff80fff010":19,maxdepth:22,"export":[19,26],thoma:23,todai:22,sentenc:[],reilli:11,me_valu:0,alwai:[15,16,26,3,0,7,22,24,6,11,12,13,28],her:3,fsf:2,hit:2,matur:[11,10,28],pool:25,timestamp:16,invoc:[9,22],gregori:[23,18],"3to2":23,machdep:19,perform:[15,16,3,19,9,11],deprec:22,deriv:22,"_wait":0,modern:6,python_d:[7,16,8,17],blai:23,accomplish:22,lookdict_str:0,forc:[25,9,10,5,8],vinai:18,contextlib:18,pulldom:18,deviat:9,creat:[],win:11,bsd:18,"_pyobject_debugmallocapi":0,crash:[22,0,15,3],liststor:0,isn:[],whenev:[22,16,14],me_kei:0,packag:[16,10,3,18,0,22,23,25,6,11],jong:23,lift:22,curli:22,issue12345:26,stat:[6,18],through:[16,10,26,4,19,20,7,22,25,6,11,28],intermedi:[25,26],jul:23,convert:[25,22,11],pick:[16,10,24],met:[11,10],"0x7fff80fff008":19,big:25,submodul:22,usenet:22,arbitrari:[25,22],piec:[25,22,16],symlink:0,ssh2:11,great:[6,16,10,24],minut:6,err:22,time:[1,3,4,27,9,11,26,19,21,20,24,6,17,5,13,14,15,18,0,22,23,25],waldman:23,cryptographi:18,fast:[26,17],repeat:[22,11,26,17],carlson:23,bump:25,selivanov:23,stdout:[22,11],py_debug:16,explan:[4,22,12,26],plu:[25,16,20],"0x0c327fff8820":19,includ:[16,10,2,3,26,17,27,19,21,20,22,23,24,25,9,6,11,12,28],python2:[22,0],unlik:[11,26,23],exc:22,yselivanov:18,perman:[0,11],distutils2:3,those:[15,16,26,0,7,22,24,8,25,9,6,13,14],abbrevi:[25,22,20],mdc2:8,extra:[15,16,1,17,0,24,25],trace:[6,19,18],platform:[],pyobject:[25,22,0,28],broke:21,talin:23,gijsber:23,ullman:25,load:[],firm:24,miss:[16,26,17,19,7,22,8,6],didn:26,saved_st:0,record:[6,4,11,26,5],pystentryobject:25,roi:23,write:[],assist:[22,11,16,27,3],manpag:22,inact:[],frequent:[7,11],thank:[25,26],read:[],"0xb771b7f4":0,"0x3dbdf85820":0,program:[16,10,2,4,19,22,25,11,12,28],concentr:15,scoder:18,qpop:11,boutsiouki:23,call:[10,2,5,22,25,9,11,28],win32:8,test_subprocess:5,supervis:14,situat:[6,3],ma_smallt:0,compiler_visit_xx:25,misalign:19,home:[25,0,19,5,14],microsoft:[22,16,8],qualif:22,lost:22,"0x0c327fff87f0":19,poor:6,issue10991:6,pdb:[2,18],pyframeobject:0,com:[25,11,5,28],accept:[],hightow:23,condens:9,coveragepi:6,append:6,websit:[6,28],jlt63:18,mous:22,diederich:23,hashlib:[22,18],jerri:23,stutzbach:[23,18],etre:18,jvr:18,sln:[7,16,8],person:[10,26,3,18,4,0,24,9,14],unexpect:[],pickletool:18,also:[3,4,8,9,11,10,26,19,21,20,24,6,17,5,7,12,13,14,15,16,18,22,25],gerhard:23,helper:[25,6,17],trigger:[6,27,5,3],bad:[22,11],ascii:23,"short":[22,0,26,24],connect:[25,22,28],complic:22,hasn:17,rememb:[27,11,26,3],rww:5,exactli:[4,5],identifi:[16,3,19,22,25,11],servic:[15,28],grouper:22,might:[16,26,3,19,5,22,24,25,9,6,11,12,14,28],string:[25,22,0,14,18],subsect:22,exit:25,pretti:0,removenam:22,web:[16,26,3,5,20,22,9,6,11],name:[15,16,26,17,3,18,27,0,5,20,22,23,24,8,25,6,11],prose:22,wang97:25,"catch":[16,26,20],bar:22,reprlib:18,xdrlib:18,copi:[],structur:[],"_testmethodnam":0,remind:[9,11,15,3],paramet:[25,22,11,19,5],contain:[16,10,17,3,27,0,19,21,5,22,8,25,6,11,12,14,28],privat:[11,26,20],server:[11,12,26,5],deco:22,occasion:[26,3],parenthesi:18,select:[16,18,3,0,7,22,24,8],simpl:[15,26,17,22,25,11],mytestsequ:5,bit:[16,26,19,22,8,6,14],likewis:22,py32:11,total_tim:0,mayb:26,doerwalt:18,mandatori:26,martin:23,der:23,reader:[22,20],qualiti:[4,19,10,12,14],opcod:[25,22,21],lock:0,pmoodi:18,mai:[16,10,26,3,17,18,4,21,5,7,22,23,24,8,25,9,6,11,12,14,28],abil:[23,26,24,14],len:0,admin:[],"0xaa4560":0,aimacintyr:18,cours:[18,0,26,5,14],sequenc:[25,22,5],successfulli:26,tosi:23,visit_slic:25,gdb:[],markup:[],snapshot:7,"0x0c327fff87c0":19,consum:0,consult:[22,3],ziadé:23,backlink:22,newer:[0,11,23],forward:[15,26,3],properli:[16,10,26,3,17,0,22,24,25,6],untest:6,maxim:5,bother:14,trunk:23,widen:18,holth:23,inplac:6,ippolito:[23,18],literalinclud:22,misread:22,address:[9,22,0,26,19],plistlib:18,disabl:17,split:[],pain:10,plan:15,alloc:25,rang:[10,27,0,22,11,28],"0x000000000041b717":0,except:[15,16,26,3,18,0,22,8,25,6,12],exercis:[6,26,5],mime:22,langa:[23,18],unreport:9,bug12345:26,optpars:18,cc_kext:19,emsli:23,gfb:23,"0x00000038e46d73e3":0,criteria:26,interconnect:22,wherev:16,pydebug:[7,16],jone:23,uncommon:24,login:11,hash:0,self:[22,0,19],pythonpath:6,gsd:0,creator:[22,10],recompil:[25,16,26],"0x7ffff7f14360":0,nice:[6,26,14],unix:[],later:[],tediou:5,databas:[24,18],justifi:11,cgi:18,laid:25,fedora:16,gvanrossum:18,sinc:[15,5,22,23,25,6,11,28],therefor:[15,26,5,22,9,11,28],test_threadsign:5,theller:18,test_python_29628:5,flexibl:23,inher:22,pyarena:25,screen:14,vya:28,mere:11,fwrapv:19,hast:[15,23],fellow:14,year:[15,10,21],independ:25,heurist:[22,11],highli:11,you:16,solari:18,ahead:4,whose:[25,9],omiss:21,allevi:10,sever:[],oussoren:23,commun:[],subject:23,arriv:10,success:[22,13,5],reach:[26,17,5,25,9,11,13],ftplib:18,link:[],sporad:[26,5],thu:[15,16,10,3,0,22,25,9,6,11,14],"final":[],pyclbr:[21,18],qpush:11,must:[15,16,10,26,3,17,18,4,21,5,22,8,25,9,11,12,13,14,28],understood:[4,28],led:25,datatyp:22,price:23,effect:[6,22,26,24],tabnanni:18,children:[25,22,11],stricter:17,pull:[11,26,28],decemb:23,end:[16,10,26,3,4,0,19,22,24,25,6,11,14],mailcap:18,py33:11,curtin:23,malloc:28,look:[3,0,19,5,22,24,25,9,6,11,12,13,14],convers:[25,11,3],confirm:5,termio:18,googl:5,misstep:22,sizeof:28,itertool:[22,10,18],belong:[22,16],gener:[],angl:22,someth:[15,10,26,3,4,20,22,24,25,9,6,11,12],"0x7fffd00019d0":0,tracker:[],mono:7,fifth:9,setnewnam:22,sourc:[],equival:[],cwd:0,mateusz:23,pylong_fromlong:28,dom:18,"0xc9c790":0,roger:[23,18],sometim:[15,16,10,26,17,19,5,20,25,11,28],fulli:22,ipsum:22,dereferenc:28,mimic:26,satisfi:11,issue10541:6,internet:[22,17],mailhead:22,misc:[16,26,0,7,23,24,9],run_dialog:0,ken:23,everyth:[15,26,21,19,8,6,11],bundl:11,affect:[16,3,20,22,24,25],urgenc:3,rfc:22,sirolf:23,michael:[25,23,18],testsrun:0,bquinlan:18,pylongobject:[0,19],auto:[],whole:[22,26,5],debugg:[0,23],contribut:[],cmath:18,sunau:18,net:[25,7,2,20],i18n:18,paper:[25,26],"0x00000000004466aa":0,prior:[17,16,26,14,3],storchaka:23,alpha:[],traction:27,incorrect:11,unimport:6,triager:[27,26,24,14,3],first_nam:14,topic:[22,18],test_poplib:5,"0xd75160":0,"0x984b474":0,stale:25,"0x3dad39f5e0":0,discourag:22,"_64_x2_dual_core_processor_4400":5,loewi:[23,18],overcom:[0,16],exhaust:25,sampl:22,ssh:[],winsound:18,firefox:7,distutil:[18,23,3],bottom:[22,0],activ:[],constitu:10,want:[],she:23,exact:[25,22,27,5],fijalkowski:23,wang:25,camel:22,descend:[11,15],demo:3,beginn:7,older:[9,0,16,10,26],victor:[11,23],front:[0,19],chapter:22,"class":[25,9,22,10,3],asan_symbol:19,lifecycl:[],javascript:[24,3],"_cleanup":0,spwd:18,succe:[26,5,8],ack:[9,26,24],publicli:[10,20],latin:23,asdl_seq_set:25,parent:[22,11],child:[25,22],hook:[],inde:11,diff:[9,11,16,26,3],gsoc:[23,3],determin:[22,16,24],electron:26,vptr:19,tid:0,soc:23,verif:11,dif:26,autotest:17,inter:5,tweak:[11,16,21],transliter:23,"0x98faaa4":0,speaker:22,nasty_eq_vs_dict:0,filesystem:[16,5],translat:[23,3],between:[],here:[16,26,17,27,0,19,5,20,7,22,23,25,12],cc_kext_ios5:19,sai:[15,1,3,22,6,12,14],saved_at:0,broken:[9,22,15,24],corner:22,asan_osx:19,anthonybaxt:18,prune:6,addon:8,refus:26,litter:22,relicens:26,denial:15,versionchang:22,asyncor:[23,18],holden:23,softwar:[9,16,24,14],c89:[16,28],parser:[16,18,3,4,19,21,22,25],lowercas:3,transpar:11,planet:20,size:[0,19,28],favorit:[6,22],flush:22,crasher:0,pyobject_head:22,functiondef:25,hint:0,tgp:23,bodi:[25,6,22,16],"0x681d77":19,struct:[25,22,18],credit:[],committ:[20,23,26,14,18],linkcheck:22,pycon:23,some_python_integ:0,lightweight:7,kuchl:23,addop_nam:25,hardwar:[24,5],man:11,amount:[25,4,10,26,3],edg:[25,6],bedivier:23,deepli:22,unrel:[11,26],recurs:[11,5],kei:[],item:[25,22,18],handi:[22,26],maintain:[15,16,10,2,26,18,7,22,23,9,6,11,12,28],obvious:[9,6,14],pyobject_malloc:0,elimin:1,least:[16,10,26,5,22,24],branch:[],act:[24,3],describ:[16,3,4,19,7,22,24,8,25,11],wall:19,uppercas:22,behind:18,insid:[],alreadi:[],dummy_thread:18,lsan:19,bch:25,soon:5,"_my":22,promptli:14,ravi:25,creation:25,daniel:[25,23],no_sit:5,out:[],press:[16,26,3],occurr:22,apart:26,live:[23,16,12,5,17],instruct:[16,26,17,3,21,7,22,24,25,6,11],thought:[25,1],librari:[16,26,17,3,19,21,5,7,22,23,8,25,6],restor:11,audioop_getsample_imp:19,slice:25,dot:[22,28],disk:26,stack:[0,26,19],swappablearea:0,userprofil:26,modif:26,seri:[25,9],"static":28,mismatch:16,decor:[25,22],weekend:13,valgrind:19,bitbucket:[6,26],"0x7fffac0011c0":0,netbsd1:18,sleep:0,"0xd802e0":0,who:[],spam:[22,26],aho86:25,ignore_environ:5,cole:23,specifi:[10,26,17,3,19,22,25,6,11],ten:24,"__libc_start_main":19,necessari:[15,16,26,3,7,22,8,11],good:[10,26,3,4,19,5,7,22,24,8,9,6,11,12,14],serra:25,csu:19,fleme:23,csv:18,scope:[25,9,19,16],divers:11,august:23,report:[],shall:5,given:[15,16,18,0,5,22,23,24,25,28],singl:[],py27:11,allison:23,lukasz:18,auto_fil:0,instead:[],aris:[6,0,16],option:[15,16,10,26,17,27,0,19,5,22,25,9,6,11],"0x00000000004cd1e6":0,carefulli:22,"0x6d72c0":0,synopsi:22,nntp:20,section:[],wait:[0,5],"0x0c327fff8840":19,approv:[9,11,23,28],hopefulli:[5,14],proper:[10,26,4,5,24,25,9,6,11],backward:[9,10,26,3],"0x7fffd00024a0":0,setup:[],buggi:19,meant:[16,10,26,18,4,22],circumst:16,mean:[16,10,26,5,22,25,11,12,14],uniform:10,ubsan:19,"0xad4730":0,dbm:18,gregorlingl:18,dure:[6,22,15,16,19],virtu:10,module2:11,tend:10,forth:22,copyright:[9,22,26,14],omit:[6,22,11,26],getpass:18,mode:[15,16,2,17,22,24],"0x7ffff7fe2700":0,subsubsect:22,unifi:26,"0x0000000000440d1b":0,foord:[23,18],closur:25,besid:22,defenc:0,last:[],under:[15,16,1,10,26,17,19,22,9,6,11,14,28],respect:[26,3,22,25,9,11],than:[],verifi:[9,6,11,14,17],devguid:[18,11,12,3],ma_tabl:0,schuppeni:23,ncoghlan:18,"enum":[25,18],sourceforg:[25,23],versa:[16,26],plain:22,zero:25,unprocess:26,neworsavedgameselector:0,appl:16,tarfil:[23,18],"0x984b464":0,groupbi:22,preserv:16,reason:[26,3,4,21,5,22,9,11],hmac:18,slightli:[22,11,16],myriad:20,test_urllibnet:5,cut:[22,15,26,5],josiahcarlson:[23,18],header:[25,22,16],nntplib:18,winreg:18,path_convert:28,va_copi:28,repositori:[],lead:[25,6,22,10],version_requir:11,suddenli:25,xemac:[22,2],can:[],environ:[7,11,16,22],distinct:5,runpi:18,socketserv:18,raymond:23,"0x0000000000446647":0,differ:[],lorem:22,renam:11,tie:25,idlelib:[18,3],februari:23,pyspecif:22,rej:[11,26],addop_i:25,proceed:25,put:[15,26,7,22,8,9,14],frank:[23,18],fortun:27,alexand:23,upper:8,gcc:[6,19,5],pass:[],transform:25,few:9,stackoverflow:11,joel:11,deili:[23,18],leav:[22,11,12,13],excel:11,signific:[22,11,10,26],schlawack:23,c99:[16,28],essenti:25,bug:[],carri:4,word:[22,26,24,18],whitespac:[],sanction:10,sent:[9,11,12,23,20],"_modulesetupfail":0,linux:[16,18,0,19,5,28],noindex:22,ronaldoussoren:18,nosi:[],how:[],whatev:22,turn:[16,10,3,5,25,6,13,14],plai:[25,0,17],advanc:16,unconvert:22,"__block":0,done:[15,16,10,3,22,23,24,25,6,13,14],tailor:17,benediktsson:23,specul:27,collaps:26,pub:11,retain:[9,14],meth:22,store:[25,22,11,16],foundat:[9,14],occur:[15,4,19,20,22,8,25],dino:23,queri:25,yuri:23,"22ae2b002865":5,belopolski:[23,18],sign:[],msvcrt:18,support:[],overal:[6,11,10,14],freenod:[27,11,20],gpolo:18,cleanup:[25,17],ob_refcnt:0,bytes_warn:5,"0x0c327fff87e0":19,kdiff3:11,advis:27,cond:0,pytypeobject:22,basi:[19,26],pycodegen:25,across:[27,10,24],seek:27,sqlite3:18,maupin:23,assumpt:22,attach:[10,3,23,24,9,14],decim:[23,18],encourag:[7,11,27,17],"throw":[7,11],compat:[15,10,26,2,3,7,23,9],qualifi:[],acquaint:[6,5],bang:21,paul:23,surpris:[22,14],demonstr:[25,22],dialog:[22,0,11,26],qdelet:11,launchpad:2,friendli:2,subscrib:[12,14,20],somework:11,timeit:18,paragraph:[],"0xd80260":0,dare:6,jeroen:23,van:[22,23],meet:[10,14],dep:16,beta:[],intern:[],"__version__":25,boolop:25,failfast:0,highlight:22,nomenclatur:15,customarili:[22,26],selector:18,close:[15,26,3,0,22,24,11,13],fine:8,makefil:[22,19,5,18],gave:[24,8],clear:[26,3],aspect:[22,11,28],field:[],futur:[15,18,4,22,23,14],bandwidth:26,serious:4,writabl:0,indent:22,typedef:25,process:[],stderr:16,easili:[7,22,16,26],your:[16,10,2,26,17,4,0,21,27,5,7,22,24,8,25,9,6,11,12,14,28],"_is_own":0,combin:[25,11,19,5,28],hotshot:23,buildbot:[15,16,3,18,5,7,8],slowdown:25,delic:5,logo:[11,24],express:[],andrew:[25,23],earlier:[],keygen:11,framework:3,ironpython:[7,23],bell:22,peterson:[15,23,18],zephyr:25,symtable_exit_block:25,product:[],batchfil:22,conflict:[],faster:[22,11,26,5],eglibc:19,count_own:0,clutter:[22,11],"try":[16,1,26,17,27,0,5,22,24,9,6,11,12,13],tool:[],pydictobject:0,appreci:[9,12],enjoy:14,checkin:[28,23,26,14,20],forgot:11,"0x7fffb8001c40":0,releas:[],announc:[24,14,20],help:[],reserv:3,signal:[5,18],extend:[26,18,0,22,23,14],legal:14,built:[16,17,3,0,7,22,8,11,12],unladen:23,fit:3,poison:19,grammar:[],sep:23,dialog_swallow:0,adapt:23,rebas:26,foo:22,ma_mask:0,getopt:18,cstringio:0,chm:22,judgment:22,rpartit:22,institut:23,wierzbicki:[23,18],kelsei:23,florent:23,too:[26,17,3,22,23,24,14,28],descript:[25,22,24,3],arena:25,jan:23,"2to3":[23,3],jafo:18,drawback:6,sajip:18,lurk:12,adventur:13,challeng:[7,13],overflow:[19,28],obtain:[11,16],furthermor:5,batch_siz:0,secur:[],ob_typ:0,deal:[22,5],user:[15,10,26,4,19,22,23,24,11],cprofil:18,realm:[15,5],msvc:16,edit:[],breakpoint:2,seealso:22,glob:18,"true":[25,22,0],mimetyp:[22,18],detect:28,jvm:[7,18],agre:[11,10,14],pdbtrack:2,recip:10,org:[16,10,2,3,26,19,5,20,7,22,23,25,9,6,11,12,14,28],adjunct:22,alias_for_import_nam:25,diverg:10,channel:[],burden:[10,24],randse:5,"_gc_head":19,yet:[16,26,27,24,28,14],temp_cwd:[0,26],compiler_new_block:25,like:[15,16,26,17,0,19,21,7,22,24,25,9,6,11,14,28],sub:22,rais:[22,11,26],base:[15,16,10,26,4,22,23,24,25,6,11,28],said:22,test_unicod:5,memcpi:28,befor:[15,16,10,26,3,21,5,20,22,23,24,8,25,9,6,11,14],realiz:[25,6,4,16,24],forgeot:23,dictionari:[22,0],declin:11,"0x0c327fff8850":19,ground:[9,28],absolut:[25,6,5],ronald:23,readabl:[22,26],cleanli:24,throughout:[25,22,17],were:[16,26,3,27,23,24,25,6,11],reid:23,dark:6,text:[26,17,5,22,6,11],uuid:18,confer:25,skip:[],"__future__":18,shadow:19,first:[15,10,26,17,3,4,27,5,22,23,24,25,9,6,11,14,28],dndebug:19,rossum:[22,23],nest:22,lwp:0,caption:22,felt:16,oldest:[15,26],some:[],well:[16,26,3,27,0,21,22,24,9,11,12,14],similar:[25,22,0,11],rel:[25,22,26,5],neg:[25,4,19,28],object:[],been:[15,16,1,10,3,26,17,4,21,5,7,22,23,24,8,25,6,11,13,14],trent:23,idea:[10,4,19,27,20,8,11],"0xd7ff40":0,backtrack:7,jack:23,quiet:[0,16,5],benefit:[4,13],dai:[26,16,3,9,12,13,28],bin:[19,16],infrastructur:[10,26,28],submenu:22,whitebox:6,collect:[11,21,18],chri:[25,23,26],"_rlock__count":0,thei:[15,10,26,17,3,18,0,19,5,20,7,22,23,24,25,9,6,11,12],respons:[],clarifi:[22,15],test:[],mutabl:22,tutor:11,latex:22,ask:[],habit:11,implement:[],tew:23,startup:[6,11,16],einat:23,giampaolo:[23,18],steven:23,changelog:26,indic:[15,16,26,18,3,22,11],data:[10,18,22,25,6,11,28],excess:22,consid:[15,10,26,2,3,4,22,25,9,11,12,13,14,28],ellipsi:22,c17d7772c638:11,restructuredtext:[],seriou:3,feel:[18,27,7,22,11,13],align:[22,19],"0x7fffac001640":0,sysconfig:[19,18],sticki:11,config:11,furman:[23,18],mind:22,"\u00e9ric":23,feedback:10,collabor:26,share:[11,16,10,26],overview:[22,16],strictli:11,gentoo:5,wget:19,tortoisehg:[11,16,26],becaus:[10,26,3,4,19,21,22,24,8,25,9,6,11,13,28],jit:[7,23],api:[22,10,3],differenti:[22,11],enabl:[26,16,17,3,0,19,5,22,24,11,28],py_ssize_t:22,predict:22,each:[15,16,26,17,18,5,7,22,24,8,25,9,6,11,12],rlcomplet:18,role:[],reflect:[22,11],"0x5c2b8d":0,selen:11,runtim:[7,19],etc:[15,16,10,26,3,19,5,20,22,24,8,25,6,11,12],pyarg_parsetupleandkeyword:28,noth:3,target:[25,22,16,3],appel:25,snip:0,note:[16,26,3,0,19,7,22,23,8,9,6,11],intend:[16,10,18,21,22,11],experienc:[9,7,11,27],exec:25,init:[11,19],place:[15,16,10,26,18,21,20,22,25,6,11],test_trac:6,vassalotti:[23,18],off:[25,22,14],machineri:18,ma_fil:0,onlin:[7,11,10,22,8],pypi:[7,22,23],legend:19,realli:[26,28],"null":[],abl:[26,3,0,24,6,14,28],hyphen:22,fpectl:18,dalk:23,buildarea:5,cov:28,jónsson:23,handler:[25,18],knowledg:[22,16,24],ceval:[25,0],have_argu:25,claim:28,quit:[9,22,0,11,13],defin:[25,22,11,26],themselv:[25,26],"0x858860":0,test_bool:5,some_machine_integ:0,python32:8,index:[],"0x4e6894":19,anywher:11,spolski:11,color:11,symtable_enter_block:25,amazon:25,macpath:18,"import":[],start_gam:0,viehland:23,approxim:[22,26],devel:11,yield:25,impact:[9,3],explicitli:[22,11,28],emphas:22,monti:[22,26],"break":[15,26,25,9,12,14],tip:[22,11,28],profile_m:0,despit:22,second:[10,26,22,25,9,11,14,28],letter:22,notat:22,expertis:18,msan:19,insensit:[16,3],maximum:[22,28],again:[15,10,17,4,5,22,8,11,14],compress:[11,16],reject:[],svetlov:23,uall:[11,5,17],cell:25,iinclud:19,referenc:[25,22],shortest:17,"0x7fffdf5fe710":0,content:[],lineno:25,writer:22,shortli:22,quickest:5,ham:22,repr:0,variant:28,dfn:22,puttygen:11,explain:[16,10,26,4,5,22,24,25,28],down:[17,0,20,5,22,25,14],symbol:[25,22,21,18],customari:26,synthet:11,filter:22,presum:22,rebuild:8,produc:[26,19,5,22,8,11],wipe:8,"const":[25,22],until:[26,3,19,21,5,22,24,9,11],understand:[26,7,22,25,14,28],thousand:19,unfortun:[6,22,11,19,1],against:[9,11,24],"float":0,even:[15,16,10,26,3,19,5,7,22,24,25,9,11,14,28],could:[26,19,22,23,6,13],larg:[25,4,7,10],provid:[16,10,26,3,17,0,19,5,7,22,23,24,25,9,6,11,13],popular:[6,22,16],dealloc:25,tsan:19,nois:19,after:[],ini:26,session:[22,0,11],bat:[],extern:[],reliabl:5,smith:[23,18],offend:[11,16,5],uniniti:28,textwrap:18,liter:[25,22],achiev:[22,11],formatt:18,parti:[10,18,7,8,6,11],suit:[],"0x858770":0,concept:[7,22],complain:22,"0x619000004020":19,netrc:18,doubt:[9,6,3],py3k:[7,11,23],debian:16,complex:[25,22,10],potenti:[22,11,5],impossible_hint:0,lot:[10,26,0,22,11,12],profession:8,yourself:[3,9,6,11,28,14],proport:4,cookbook:10,whichev:9,ubsan_osx:19,vast:16,keyboard:0,parsermodul:21,speed:[7,23,24,17],checkout:[],coverity_model:28,tkinter:[18,3],poplib:18,pygc_head:19,involv:[26,10,18,27,21,5,22,24,25,12,14],keyword:[],simplest:[11,17],silenc:[],rather:[16,26,18,0,20,22,25,9,11],advers:5,tempt:16,errno:18,posit:[],modulefind:18,standalon:22,ochtman:5,mkdef:8,asap:14,dedic:[28,22,26,5,14],local:[],src:19,hexadecim:0,calderon:23,"0x000000000041b7c0":0,libc:19,conveni:[0,11,26],howev:[16,26,0,19,22,8,25,11],portabl:17,aka:[25,19],trim:5,hat:16,longobject:19,intro:22,divid:11,ncn:23,osu:28,terminolog:[7,15,22],ziga:23,bob:[23,18],dolor:22,haypo:18,cost:16,repres:[26,17,0,19,22,25,14],printer:0,asan:19,prefer:[16,26,22,9,6,11],resolv:[16,26,17,3,8,25,11],clees:22,sudoku_mak:0,rukowicz:23,subproject:8,bogu:26,graphlog:11,exampl:[],left:[15,3,19,22,24,6,13],kristján:23,contemporan:23,heiko:23,expectedfailur:0,apr:23,ping:9,ubuntu:16,found:[16,1,10,17,0,19,5,20,7,22,24,8,25,14],virtual:[7,28],label:[22,26],"0xc185a0":0,bracket:22,expr_ti:25,narrow:[11,5,28],unclear:12,shinner:23,intellig:22,octob:23,reindent:26,yum:16,yield_kind:25,fashion:24,more:[15,16,1,2,10,26,17,18,19,21,5,7,22,24,25,9,11,12,14,28],scarlet_pimpernel:0,past:[22,15,26,5],assert:[25,5],"__cached__":0,mail:[],recommend:[26,17,2,5,7,23,11],almost:26,"_stmt":25,histori:[],attack:15,ppk:11,python3:16,compiler_visit_stmt:25,philip:23,versionad:22,owner:[0,28],daili:[7,11],site:[16,18,0,22,6,11],bruynoogh:23,astrand:18,"_acquire_restor":0,littl:[10,3,4,5,6,12,14],core:[],insult:14,gettext:18,graminit:[25,21],pydotorg:11,block:[25,22,8,3],comp:20,"_type_equality_func":0,sparingli:22,brian:23,effort:[23,12,3],due:[22,11,19,17],makeopcodetarget:16,verbatim:22,network:[27,5,18],whether:[15,10,26,3,4,19,22,24,9,11],token:[25,22,21,18],"public":[],moduleauthor:22,pkgutil:18,x64:8,"0x3dbdc7ea70":0,snow:[23,18],folk:26,hale:23,bsddb:23,josiah:23,expert:[],real:[19,16,3],opinion:[11,20,18],pybench:18,newest:26,"int":[25,0,28],ast_for_xx:25,b1ddcb220a7f:11,roughli:[15,12],addop:25,f12ef116dd10:11,afterward:[26,3],analog:0,within:[],along:[16,4,22,25,6,11,12,14,28],bisect:[11,5,18],smtpd:18,unsur:26,mock:18,guard:[25,11],newcom:22,interact:[22,11,5],gaug:10,thorough:17,csid:11,toolchain:[22,12],kipp:23,special:16,john:[22,23],mani:[26,3,19,20,22,24,8,9,6,11,28],node:[25,22,16],weigh:22,grasp:[22,24],whom:22,pythonrun:19,clow:19,freebsd:18,bring:13,active_tim:0,agent:11,no_user_sit:5,hazi:4,especi:[16,26,3,27,22,24,11],still:[],bound:[22,19],graphic:[11,16,26,17],abc:[6,18],math:18,assign:[],code:[],own:[16,17,20,22,23,24,25,6,11,28],jean:23,credenti:11,workshop:[25,22],smooth:17,"_original_stderr":0,compileal:18,eventu:[9,4],statu:[],bugfix:[9,15,10,26,5],"_ios_fmtflag":19,test_augassign:5,hard:3,addop_jrel:25,load_attr:25,satisfactori:9,libpython3:19,unless:[25,16,26,28,18],try2_stmt:22,teach:17,tmp:16,iter:[9,22],magic:25,subsequ:[22,11,26],remain:[7,26],seed:5,awai:[25,22,11],enclos:22,visibl:[6,11],aronach:18,resourcewarn:1,rdh:23,test_functool:5,element:[22,26],xxx:19,"__lltrace__":0,inject:22,opt:8,current:[],sit:22,"0x7fffb8001a10":0,loop:[25,22,0,16],normal:[16,26,17,3,19,22,12],percentag:4,nullabl:28,intermediari:28,rarer:7,send:[22,10,26,14,20],specialbuild:16,endian:5,"_start":19,pylib:6,wiki:[22,11,24],just:[16,26,27,19,21,5,22,25,9,6,11],lose:[11,12],alexi:[23,18],macro:[25,22],montanaro:[25,23,18],definit:[16,3,7,22,25,6,11],valid:[6,22,12,26,24],shown:[25,22,0,24,17],mulich:23,profile_io:19,timeout:[0,5],python:[],heavi:22,obido:25,region:19,client:[20,11,16,5,8],fdrake:18,sysv:0,choos:[16,7,22,25,9,6,11],runner:[17,5,3],amauri:[23,18],blog:[],pyast_compil:25,"3rd":[6,7],parrot:[22,23],imposs:5,"_mirroroutput":0,floor:21,doe:[],jesu:23,gregor:23,categori:[6,22],nadeem:[23,18],openssl:8,verbos:[5,17],length:[25,22,0,28],instrument:[6,19],"char":[0,28],arg:[25,28],accident:16,distinguish:0,month:[9,15,23],newsread:20,sibl:15,batista:23,usr:[22,0,16,19],save:[22,11,26,24],unnecessari:16,hellmann:23,linker:19,svn:[22,0,23,3],fnmatch:18,though:[16,19,22,24,25,6,11,13],ma_lookup:0,pyarena_fre:25,expos:22,believ:[9,10],perhap:[26,8],around:[7,19,26,22,24],nelson:23,freeli:[11,14],script:[16,26,17,3,5,22,9,11,28],aggreg:26,upfront:10,figur:[11,12,14,17],refactor:3,develop:[],specif:[],"0x63d0f8":0,problem:[],tide:13,descriptor:[22,28],compil:[],subset:5,capabl:[9,22,26],misinterpret:22,land:26,johnson:23,hhp:22,arch:19,assembl:[25,6],unabl:0,domain:[25,22],xcode:16,"_pyunicode_new":0,contact:[],open:[15,16,1,10,3,26,27,5,20,7,22,24,8,6,11,13,14,28],regist:[25,0,16,11,24],everi:[15,16,26,17,4,0,19,27,20,22,24,25,6,11,28],"_condition__wait":0,lower:[22,0],pstat:[23,18],"0x0c327fff87d0":19,lagerwal:23,unicodedata:18,commit:[],ossaudiodev:18,cover:[],semicolon:22,annot:11,machin:[],feed:20,ob_siz:0,impli:22,fulfil:26,fals:[],spend:20,"0x7f19e0":0,saved_game_model:0,attribut:[25,22,26],balanc:[9,17],view:[15,19,5,22,6,11,12],visual:[6,22,16,5],heap:19,zipfil:[22,18],vindic:22,test_:17,templat:[22,0],line:[],about:[],unexpectedsuccess:0,"void":22,cgitb:18,"0x7e7820":0,altern:[22,23,26],hardi:23,button:[9,22,11,26,3],glossari:22,smtplib:18,last_nam:14,life:14,donald:23,confus:[22,0,8],goodger:23,rodriguez:23,unicodeobject:[0,3],sig:[10,12],buildbottest:5,ptr_to_python_str:0,trick:[11,26],"_rlock__own":0,synchron:[26,5],quopri:18,"2b3":22,ecosystem:7,imghdr:18,github:11,strongli:[27,15,26],visit:25,construct:[],farm:25,aho:25,march:23,redirect:[22,10,20],clr:7,introduc:[],parallel:[1,5,17],concret:22,claus:5,audioop:[19,18],va_list:28,ldl:19,action:[24,28],know:[],emac:[],authorit:22,heim:[23,28,18],opaqu:0,written:[16,10,0,21,7,22,24,28],dict:0,perceiv:3,all:[4,27,8,9,11,10,26,19,21,20,24,6,28,17,5,7,12,14,15,16,0,22,23,25],calendar:18,optim:[25,0,19,23,5],succinct:22,nor:25,assum:[26,17,3,5,7,8,9,6,11],shortcut:[22,11],suitabl:[22,26,17],"switch":[],window:[],"0x984b494":0,conf:22,xml:[18,3],promot:3,frozen:[10,20],arrai:[28,18],abus:22,symtable_visit_xx:25,doubl:0,appeal:[4,10],micro:15,tempfil:18,predecessor:23,pyclass_typ:22,wstrict:19,purpos:[26,22,23,25,9,11],rsa:[11,14],instancemethod:0,took:21,"0x620c00":19,solem:23,domin:22,dump:3,entiti:22,buffer:[2,0,19,22,23,28],push:[],phase:19,upon:[6,10],pdflatex:22,gui:[16,18],test_thread:5,prepar:[],latest:[],confid:22,previous:[11,16],disallow:17,jerdonek:[23,26],cla:26,appli:[],practic:[6,22,16,26,14],mkdir:19,univers:[11,19],minidom:18,"0x7eba00":0,metadata:26,rundown:5,pair:[25,22,5],handl:[],brett:[23,28,18],"0xc9c7f8":0,fcntl:18,chang:[],risk:[22,15],fsanit:19,spark:25,dda1a32748e0:11,possibl:[],sponsor:14,"0x0c327fff8830":19,technic:[25,28,4,20,3],culprit:11,ident:11,autocomplet:3,qunus:16,ensur:[16,26,19,22,9,11],dd12639b82bf:11,revis:[],made:[],mangl:25,"_pyobject_debugmalloc":0,eli:[23,18],"0x7ffff2128500":0,coverage_data:6,"0xd803e0":0,sudo:[19,16],unreleas:26,substanti:22,subtl:[26,24],grp:18,better:[16,3,5,7,22,11],track:[],deserv:[22,15,26,3],compiler_xx:25,scare:22,avoid:[],my_blacklist:19,asdl_c:[25,16],serv:[22,15],build_ext:6,asan_osx_dynam:19,facundo:23,submiss:[9,24],surround:22,far:[21,26],maciej:23,wouldn:26,nptl:0,vulner:22,adjust:[25,16,26],decoratormethod:22,scratch:[11,16,19,8],migrat:3,robust:[5,17],scan:[],cxx:19,impl:22,learn:[],much:[15,17,3,5,7,22,9,11,28],workaround:19,keystrok:22,two:[],keep:[],digest:22,outgo:11,former:[25,11],openid:24,cmd:18,winter:23,url:[16,26,3,22,11,14,28],backtrac:0,lack:[26,3,24,25,9,11,12],occas:[4,19,1],quo:11,pre:[],otherwis:[4,15,16,26,8],suggest:[],eric:[22,23,18],world:[22,0,11],symtabl:[25,21,18],caus:[16,1,26,3,17,19,5,22,8,11],aifc:18,entri:[],facundobatista:18,begin:[4,19,5,7,22,23,25,9],titl:[],locat:[25,22,11,16,5],underlin:22,fail:[],elson:23,amd_athlon:5,"\u0142ukasz":23,pageant:11,signatur:22,lutil:19,subdirectori:[22,8],modul:[],wast:22,column:[22,11],stab:6,ob_digit:0,downsid:5,notic:[16,0,21,24,25,9,11],beyond:[],"0x2b76be018078":19,clearli:[22,24],spuriou:[11,5],right:[15,10,26,19,24,8,25,9,6,11,14],level:[],navig:22,json:18,alter:[25,19],remot:[],postpon:3,integ:[22,0,28],serhii:23,held:25,worth:[10,26,3],ptr_to_char_star:0,transit:18,routin:0,regener:[],app:16,email:[26,10,3,18,20,22,23,9,12,14],minor:[22,15,26],orsenthil:18,addop_o:25,techniqu:25,date:[16,26,18,3,22,24,6,11],immedi:[16,1,26,21,7,22],wasn:22,flatten:25,pertain:22,compon:16,microthread:7,simpler:26,aid:[22,26],hex:3,member:[22,19,14,28],pty:18,overlook:3,antoin:23,"_check_notifi":0,mailman:2,add:[],"_freeze_importlib":19,pickl:18,pimentel:23,"__doc__":0,pete:23,fileinput:18,attr:22,present:[17,4,0,27,5,22,25,9,11,28],hgrc:[11,26],necess:25,engin:[7,22],neal:23,cxxflag:19,regress:[],game:0,refresh:11,preprocessor:22,strateg:25,mywork:[9,26],zlib:[16,18],strongest:15,path:[],accel:19,alex:23,autom:[25,26,28],stalem:11,lingl:23,menuselect:22,wide:[16,10,28],posix:[22,11,19,18],hoxworth:23,multiprocess:[23,10,18],welcom:[7,22,27,24],subentri:22,r45329:23,comput:[6,11,26,3],path_t:28,savedcwd:0,explor:11,test_grammar:21,"0x7e30e0":0,cannon:[23,28,18],entir:[10,26,17,27,19,22,24,25,9,6,12],gustaebel:[23,18],"_stderr_buff":0,asdl_seq:25,profil:[0,19,23,18],coordin:15,py_buildvalu:28,submitt:[26,24,18],thing:[15,16,26,17,4,19,5,7,22,23,24,25,9,14],bnf:22,incomplet:21,form:[16,26,20,7,22,23,24,9,11,14],natur:[22,10],inlin:[],non:[15,26,18,22,25,9],compliment:19,stufft:23,waterfal:5,itself:[],sandbox:[23,5],uniqu:[25,22],hudson:25,lab:[22,28],secondari:[6,22],center:[22,28],cpu:[22,16,17],serwi:[23,18],variou:[16,10,26,3,17,18,4,19,5,20,7,22,23,24,25,9,6,11,12],"0xd7ee60":0,bernardo:23,prevent:[9,11,10,5],make:[],openindiana:18,discret:[15,28],gnome_sudoku:0,truli:[6,4,13],codeop:18,araujo:[23,18],"_stdout_buff":0,apt:16,busi:14,"var":[22,19],anyth:[22,16,24,14],"0xcb5380":0,veiw:19,choic:[10,26],union:[25,19],input:22,receiv:[10,26,4,19,20,24,25,9,11,14],chunk:[25,6,22,18],mirror:[11,20],offset:25,obmalloc:[0,19],concern:[],"default":[15,16,26,17,3,0,5,22,9,11,14],latter:[25,11,20],applic:[22,19,16,26,14],simpli:[26,17,3,5,20,22,9,6,11,12,14],suffici:[9,16],discrep:[9,5],html:[18,3,22,23,25,6,12],ideal:6,access:[],free:[17,18,5,22,8,25,11,13,14,28],summer:23,imp:18,"0x98fad24":0,importlib:18,incompat:[15,26],strip:22,nbyte:0,subitem:22,waiter:0,solut:[16,10,3,7,24,8,9,11],kumaran:23,mainli:[22,11],eval:[25,16],dead:[22,28],http:[16,26,2,3,18,19,5,20,7,22,23,25,6,11,12,14],stai:6,builtin:[22,0,18],model:[],correspond:[15,26,3,0,5,22,25],run:[],global:[0,19,22,25,6,11],pyarena_addpyobject:25,zen:4,"0x948e82c":0,extens:[16,10,26,3,4,0,7,22,24,6,11,14],ghaer:18,charact:[22,28],jump:25,difficult:[4,22,10,1],warrant:[9,3],wild:19,onc:[15,16,10,26,3,4,7,24,25,9,6,11,12,14],longer:[15,10,3,22,23,24,13,14],breed:10,cflag:[19,16],"8ff33af017ef":11,"0x98fa6e4":0,modulenam:22,restrict:[22,15,28],"0x98fab44":0,guido:[4,22,23],remaind:22,issu:[],run_swallowed_dialog:0,happi:26,permiss:[],tty:18,impress:22,testresult:0,ftp:11,edelsohn:18,fraction:18,undon:11,systemat:9,buildpython:19,usual:[15,26,3,23,24,25,11],unittest:[18,3],fork:26,addresssanit:19,ubsan_cxx:19,seilnacht:23,statement:[25,6,22,11],pile:26,"0xd750e0":0,david:[0,23,18],basic:[16,10,26,7,22,25,9],argument:[16,17,3,0,22,25,9,6,11,28],sync:[],consensu:[11,13],interpret:[],terri:[23,18],tar:[22,19],familiar:[7,24],autostart:11,breakag:[26,3],patchcheck:[9,26],decis:[18,3],tabl:[],fundament:22,spent:14,scheme:26,unit:[],assur:22,seutter:23,workload:[10,24],qimport:11,pje:18,common:[],"0x9420b04":0,attest:11,test_notifi:0,"0x858a90":0,envvar:22,recent:[],flovi:23,repli:[20,3],wherea:[27,0],offer:14,chdir:26,gdbinit:[0,11],consist:[10,26,17,22,24,25,14],clock:24,weakref:18,"__name__":[22,0],talk:22,complet:[16,26,17,3,19,20,22,25,6,11,12,14],hidden:25,vari:[0,16,12],critic:[25,16,28,3],pyc:25,"0x7fffefa18710":0,stringprep:18,lee:23,sidebar:24,okai:26,tell:[],expat:18,usag:[],hereaft:0,incom:11,featur:[],changeset:[],unresolv:11,syslog:18,"0x0000000000584abd":0,convent:[22,16,26],regular:[22,0,19,5,3],sectionauthor:22,docutil:22,ebnf:16,week:[28,18],hgaccount:[11,23,14],pgen:[25,21],test_sometest:11,anymor:3,often:[15,26,17,3,5,22,25,9,11],pydict_getitemstr:0,pprint:18,pathlib:18,would:[10,3,4,19,5,20,7,22,25,9,6,11,14],constructor:[25,22],account:[16,4,5,22,24,14,28],dens:26,mistak:22,rietveld:24,onli:[15,16,10,26,3,17,18,4,0,5,20,22,24,25,9,6,11,14,28],wno:[19,16],interfac:[20,22,11,5,17],ronach:23,unconvinc:11,preced:[25,7,22],highlightlang:22,libari:6,ital:22,duplain:23,rough:25,shlex:18,format:[10,26,18,3,19,22,9,11,28],dir:3,aim:[22,15,21],ned:[6,23,18],test_pars:21,ansi:28,"0x4e664c":19,yoshida:23,epub:22,queue:[22,11,26,18],"_sre":3,fresh:8,discuss:[15,10,26,2,4,19,27,20,22,23,24,25,9,11,12,13,14],relev:[9,22,0,16,24],builddep:16,darwin:19,effbot:18,"__builtins__":0,comprehens:[25,7,22],danger:22,particularli:26,"_condit":0,difficulti:13,sphinx:[22,12,26],libcrypto:19,stackless:7,eol:26,regularli:10,brought:3,most:[16,10,26,3,17,4,20,7,22,8,25,9,6,11,12],see:[],retriev:[25,11],new_block:25,wither:23,stand:[22,11],sure:[],functool:18,emit:[25,22,0],resourc:[],nnn:3,wrong:[6,22,21,26,3],further:[15,4,27,22,9,11],lai:22,pybuilddir:19,constraint:26,master:[25,11],"0xd751e0":0,backport:[9,15,23],python331:8,mentor:[27,7,23,24,11,14],guilherm:23,guidelin:[9,11,3],dont_write_bytecod:5,smart:22,colorsi:18,host:[11,15,19,5],syscal:0,shouldn:[11,16],walker:23,lehtinen:[11,23,18],janssen:[23,18],util:[11,16,19,8,3],taken:[4,22,10,24,5],finish:[25,7,12],pyarena_new:25,individu:[28,22,8,17],toc:22,notion:6,box:[22,11,24,3],behavior:[9,22,19,24,3],separ:[],backpatch:25,escal:15,formal:[9,22,26],"0x3dad3a95a0":0,publish:[11,12,15,8,26],amongst:11,awar:[9,7,11,22,3],fact:[25,22,3],ongo:7,motiv:[9,22],updat:[],without:[],map:11,cast:0,give:[16,26,0,22,23,25,6,14],datetim:18,amk:23,tortoiseplink:11,mutual:11,came:[6,26],plug:7,cmdoption:22,senthil:23,rush:23,socket:[11,23,18],rodola:18,test_support:0,primarili:[6,23],grati:16,contrast:22,trivial:[9,26,5,28],slave:5,"0xc191e0":0,rewrit:14,unobtrus:22,pyeval_evalframeex:[25,0],hgtest:14,reanim:22,disappoint:11,manag:[],larger:[11,26],redistribut:26,probabl:[26,17,21,5,7,9,14],pipe:[22,19,18],nch:25,wave:18,grant:[23,26],"0x7e7d20":0,attende:23,libssl:19,offici:[15,16,26,3,4,25,11,14],jinja:22,high:[25,7,0,12,3],unexecut:6,"0x928310":0,colon:[25,22],standard:[],elsewher:16,book:[25,4,11],"__file__":0,backout:11,acquir:0,xmlrpc:18,oliph:23,hello:[22,0],varieti:27,mark:[],peopl:[16,10,26,3,18,4,21,20,22,24,9,12,14],worri:[16,26,22,25,9,6,12],"0xd7fd10":0,type:16,nick:23,novemb:23,propos:[],benefici:4,delet:[],greatli:11,lessen:24,volunt:[27,14],msg:3,kept:[25,22,19,16],execut:[1,17,0,19,22,8,25,6,11],review:[],incorpor:4,bill:23,docstr:[0,26],somehow:3,sp1:16,relat:[],pitrou:[23,18],precaut:17,import_init:19,expr:25,prompt:[22,14],dfsan:19,rst:[25,22,11,26],zipimport:18,bdb:18,pylong_from:28,fill:[9,7,22,28,3],openssh:11,"_resultfordocleanup":0,expand:23,configur:[],amend:22,armin:23,backslash:22,steve:23,ezio:[23,18],"_dummy_thread":18,py_compil:18,condit:[1,17,27,5,8,25],similarli:22,cpythondir:6,abort:[],murrai:[23,18],jnoller:18,vice:[16,26],veri:[15,16,10,26,3,27,5,22,24,25,6,11,14],vawda:[23,18],tupleobject:19,grow:10,archiv:[22,23,20],imaplib:18,nativ:[22,11],call_attr:25,either:[10,26,3,0,5,22,24,8,25,9,11,14,28],eprintf:19,universalsdk:19,suppress:5,"_rlock__block":0,heapq:18,mvl:23,smoothli:26,unknown:[9,19],context:[25,22,0,18],necessarili:[22,11,16,10],typo:12,"_verbose__verbos":0,"_io":3,stmt:25,accur:6,brandl:[15,23,18],"52ec6a3eeda5":11,code_dealloc:19,perfect:5,revers:[22,26],pointer:[25,0,19,28],backtick:26,classifi:[],count:[25,22,0,17,28],pyunicodeucs2_fromstr:0,asdl:[25,21],power:6,certain:[16,18,3,4,19,21,22,6,14],seen:22,visit_seq:25,full:[],dickinson:[23,18],djg:23,maverick:16,file:[],"0x7ffff7fd5ee8":0,larri:[15,23],fix:[],simplifi:[25,24],seemingli:5,random:[18,24,1,5,17],swallow:[0,23],easiest:[22,11,16,26],gather:[6,22,20],tim:[23,18],reachabl:22,evalu:22,best:[],"0x7a2141":19,broader:18,task:[15,16,3,0,7,22,25,11],output:[0,19,5,22,25,6,11],asid:[26,24],period:[22,18],baker:23,jcea:18,prioriti:[],blackbox:6,petri:[11,23,18],which:[],polo:23,me_hash:0,resolut:[],exclud:[6,16,17],comfort:[7,27,13,24],care:[16,26,22,24,25,11,12],arc:23,saniti:[9,16],guarante:[26,17],jim:23,browser:[6,22,24,20],promis:[6,10],regardless:[9,16,13],lock_test:0,moment:[11,3],kwarg:28,accordingli:[25,26],control:[],travi:23,stinner:23,lightli:[4,10,5],libzma:16,nasm:8,shoe:9,norwitz:23,try1_stmt:22,don:[16,26,17,3,27,19,20,22,24,25,9,6,11,12,28],sole:6,rss:20,"0x7fffc8002090":0,weinen:23,correct:[25,12,26,8],barri:18,schedul:[11,12,5],emphasi:22,pleas:[16,10,3,27,22,23,9,6,11,14,28],log:[],osx:19,undefin:19,regexp:22,fno:19,stick:[9,6],peter:[23,18],mercuri:[],stabl:[5,8],cea:23,commerci:28,xvf:19,fetch:11,cygwin:18,subprocess:[5,18],gladli:22,mmap:18,appropri:[15,16,10,26,0,22,24,25,6,11],benjamin:[15,23,18],area:[16,18,3,27,0,24,25,14],alt:11,suppli:[22,0,5],had:[11,24,5,8],"_release_sav":0,rolenam:22,san:19,spell:22,mod:22,top:[16,10,26,0,22,23,24],simultan:[12,17],greater:[25,23],detail:[16,26,17,4,0,19,27,22,23,24,25,9,11,12],jeff:[25,23],vertic:5,gvr:23,new_game_model:0,"0x4ed4b1":19,needn:3,stmt_ty:25,cpython:[],ani:[15,16,10,26,3,17,18,4,0,5,20,22,23,24,8,25,9,6,11,14,28],marker:22,strenuou:[1,5,17],dragon:25,goe:[25,22],hack:[6,21],hunk:11,txt:[22,19,16,5,14],checker:19,improv:[15,26,3,4,19,27,7,22,23,9,6],pyimport_importfrozenmodul:19,idl:[22,23,16,17,3],amd64:[7,16,5,8],"544b654d000c":11,traceback:18,duplic:3,part:[16,10,3,0,19,7,22,9,6,11,12],border:22,lib:[16,17,3,0,19,21,5,22,25,6],do_nasm:8,author:[22,26],xmlreader:18,jenvei:23,recreat:25,compiler_visit_expr:25,"new":[],befit:11,marshal:[25,19,18],coveragedir:6,dash:22,pipermail:23,deadlock:0,pccuild:8,succeed:[11,5],tinker:0,unicod:[18,22,3],distribut:[9,11,16,8,14],question:[],"0xd75060":0,withdrawn:11,ref:22,henceforth:16,fall:[6,10],keychain:11,"0x7fffff7fefe8":0,"0x4ed4b2":19,particular:[],jeffrei:[25,23],tp_base:22,coupl:[6,10],hierarchi:22,advantag:[26,24],them:[16,26,17,3,18,0,19,5,7,22,24,8,25,9,11,14],bz2:18,delin:25,vocal:22,interfer:[9,5,17],makevar:22,never:[26,18,3,4,19,7,22,6,11,28],aix:18,whatsnew:[23,26],trail:22,decid:[10,1,18,4,24,6,12],sprint:23,feb:23,bytecodehack:25,richard:23,doc:[16,26,3,22,23,25,11,12],tag:[],enhanc:[3,4,0,7,22,23],instal:[],faq:[],prettifi:11,launch:16,emx:18,insert:[22,26],"_thread":[0,18],justif:26,concurr:[10,18],tutori:[22,11],goal:[6,10],ordinari:[22,17],kbd:22,known:[],backquot:22,hetting:23,quiver:23,pyunicodeucs2_decodeutf8:0,game_selector:0,among:22,number:[16,26,17,3,18,27,0,19,5,22,23,24,25,6,11,28],"0x2abf9a525eac":19,answer:[27,26,14],profile_osx:19,hold:[9,15,16,3],unsuccess:23,frame:0,debug:[],filenam:11,upstream:26,root:[16,17,0,22,8,11],bbreport:5,rule:[15,16,18,19,5,22,24,25,6],hone:27,fromfil:5,curs:[22,18],collin:23,draft:[11,26],aug:23,dsa:11,histor:[25,8],py_main:19,"0xaace60":0,debat:15,english:22,rebuilt:12,partial:19,sndhdr:18,oudkerk:23,our:[22,26,28],"_testemb":19,mention:[22,27,16,26],"__main__":[22,0,18],red:[22,16],june:23,"0x0c327fff87b0":19,although:[11,12,13,15,28],accord:[9,16],expect:[],somewher:[6,12,26,2],next_block:25,pdf:22,stupid:22,uncommit:11,gud:2,"_build":12,click:[26,3,5,24,8,11],won:[11,16,19,24,3],gmane:20,variat:22,mathemat:[23,18],stefan:23,ctype:[18,0,16,3],per:[],enter:[],www:[25,23,16],termin:[22,0,11,5],strength:[6,19],exist:[],think:[3,5,24,9,12,13,14,28],desktop:17,menu:[22,16,28],abov:[16,26,2,3,17,27,5,7,22,25,6,11,14],media:[22,11],htmlhelp:22,materi:[7,22],overlin:22,pep:[],get_small_int:28,hand:[22,19,26,8],fragment:25,weak:19,tri:[22,0,17],sbt:18,toler:11,replac:[7,11,16,22,17],asdl_seq_new:25,remov:[10,26,18,19,22,23,25,9,6,11,14],easier:[0,22,6,11,14,28],saxutil:18,mid:19,pcbuild:[7,16,8,17],editor:[],test_runpi:6,subtler:5,somewhat:[0,10],cach:[11,28],should:[],advic:15,golden:[23,18],get:[],both:[15,16,26,2,17,19,7,22,23,25,6,11,28],superflu:16,tech:23,werven:23,dealt:[1,17,3],prematur:28,gtk:0,bolz:23,"0x7ffff7fc6340":0,"0x0000000000440d94":0,sethi:25,codec:[18,22,3],str:[25,18,22,0,3],languag:[],obviou:11,point:[15,26,17,27,19,22,25,14],carl:23,avail:[],seamlessli:26,togeth:[22,11],pydoc:[22,18],inspect:[23,5,18],race:11,quirk:6,autoconf:[11,18],manner:22,petursson:23,allow:[],fullcoverag:6,third:[10,26,8,9,6,11,14],korn:25,test_abc:[6,17],prototyp:19,particip:[11,24,18],keyboardinterrupt:0,listen:10,plaintext:22,"0x63fd07":19,ipaddress:[23,18],compiler_mod:25,hare:23,classic:25,septemb:23,functiondef_kind:25,hover:22,tricki:[9,10],"_original_stdout":0,januari:23,ruigrok:23,crypto:8,bookkeep:25,yamamoto:23,robert:23,small:[15,17,4,22,6,12,28],isol:[17,11,5,8],"_previoustestclass":0,yacc:25,cvar:22,crypt:18,"__absolute_start_time__":0,studi:17,tal:23,temporarili:[9,5],"0x0":0,msilib:18,base64:18,runar:23,yourkei:11,algorithm:18,three:[25,22,19,8,18],implicit:[6,19],req:25,main_pag:0,manual:[6,22,11,26,21],suppos:19,outsid:[22,10,5,17],sem_wait:0,difflib:18,stem:5,els:[25,22,11,12,26],yuck:0,boldfac:22,mainten:[],tarek:[23,18],ron:23,xx_ty:25,authorship:23,sort:28,"byte":[25,19,3],fourth:9,leak:[17,28],list:[],alanmcintyr:18,"0x7fffac001c90":0,sudokumak:0,ssl:[22,19,23,8,18],conditiontest:0,moodi:23,step:16,delai:9,unus:[22,19,16],triag:[],lemburg:18,pristin:[26,5],nondist:23,other:[],matt:23,programm:[4,22,2],reproduc:[24,5,3],seem:[9,11,26],cosmet:26,print:[9,6,0,16],stdlib:[],linecach:18,ext:[28,3],compiler_nameop:25,document:[],"0x9aead74":0,below:[15,16,19,20,22,25,6,11],quinlan:23,françoi:23,reli:[6,22,11,5,17],traffic:20,py_va_copi:28,lva:28,vtabl:19,work:[],gzip:18,ob_bas:0,métaireau:23,"0xaacd80":0,wai:[],usernam:[26,14,3],impedi:22,addit:[],"0x7ffff7fb1868":0,let:[8,6,22,5,3],"__package__":0,zadka:23,guidanc:[4,11,24],rest:[16,10,26,27,22,25,6,11],thi:[3,4,27,8,9,11,10,26,19,21,20,24,6,28,17,5,7,12,14,15,16,18,0,22,23,25],offlin:22,command:[16,17,0,5,22,9,6,11],submit:[],cppflag:6,def:22,group:[7,11,22,14],info:0,mostli:[25,20],listinfo:2,stumbl:27,pure:[6,22,16],system:[],readlin:18,summerfield:23,pysymtable_build:25,directori:[],farawai:11,regard:[22,15,20,28],"while":[],binari:[11,26],htmlcov:6,usabl:22,post:[10,26,3,19,20,22,25,9,11],why:[],lar:[23,18],mechan:[22,27,26],casual:11,pyassem:25,finn:23,set:[],melotti:[23,18],interrupt:0,wit:5,tripl:22,correctli:[11,26],bullet:22,test_importlib:6,ldflag:19,utf:[22,23],attent:3,coghlan:23,pyunicodeobject:0,ross:23,compliant:16,psf:[26,23,9,11,14,28],processor:[22,8],shouldstop:0,aren:[11,26],sched:18,pyast_fromnod:25,sphinxext:22,patient:9,test_compileal:5,prohibit:26,show:[],main:[],constantli:[],graft:26,valu:[16,3,0,19,22,24,25,9,28],dictobject:0,kind:[15,16,10,17,5,7,22,25,6,11],escap:22,low:[0,3],whatsnew25:23,request:[],represent:[25,0],explicit:[],friedrich:23,statist:18,quick:[],arguments_ti:25,deem:15,os2:18,progress:26,vet:10,encod:[],take:[],fun:[19,14],puzzl:0,nth:25,kbk:18,page:[26,2,3,22,24,8,9,6,11],atexit:18,matter:15,walk:25,obj:25,malcolm:23,subvers:[22,11,8,3],ma_us:0,watch:[25,14],heavili:26,easi:[],intuit:22,memori:[],pygment:22,blocker:3,recogn:[22,28],focu:[6,7],temp:6,telnetlib:18,unaryneg:22,hynek:[23,18],protocol:[22,23],asynchat:[23,18],mar:[23,5],doctest:[18,3],wsgiref:18,unpredict:5,toctre:22,myfix:5,gnu:[22,19,2],rubric:22,oper:[26,18,3,19,21,5,7,22,24,11],sound:[22,14,17],juli:23,natali:23,"_py_initializeex_priv":19,prepend:[22,26],mosh:23,pytype_genericalloc:22,forget:[9,12,14],manheim:23,defer:[15,3],direct:[],brief:22,start:[],pyunicodeucs2_fromstringands:0,strong:22,"0x620d5c":19,old:[25,15,16,26,24],accompani:6,sysdep:0,"case":[],actual:[15,26,19,22,25,11],addremov:11,troubleshoot:[],technolog:7,samp:22,ps2:22,binhex:18,asterisk:[22,26],versatil:22,kleckner:23,akheron:11,benderski:[23,18],hirokazu:23,emiss:25,april:[22,23],autoreconf:11,octal:22,christian:[23,28,18],while_stmt:25,"64bit":28,via:[22,11,20],digit:3,unhelp:11,invok:[9,19,16],alon:[22,11],noller:23,webbrows:18,punctuat:22,caveat:22,bethard:[23,18],shorthand:[],ing:[23,18],anonym:24,sake:5,lzma:18,vital:5,evolv:7,inform:[],tismer:23,saved_gam:0,empti:[22,11,16],blank:22,prefix:[16,17,19,22,8,11],bock:23,central:[22,11],war:19,less:[22,15,24,5],disclos:28,judgement:[6,18],tree:[],enterpris:16,rhetting:18,state:[16,10,26,3,0,22,23,24,25,9,6,13,14],chanc:[4,11,26,24,14],codeobject:[25,19],x86:11,flip:14,rev:3,method:[22,11,10,19],inaccur:13,repeatedli:11,refer:[],rare:[25,22,15,5,8]},envversion:43,titleterms:{statu:3,troubleshoot:16,continu:5,appli:11,help:[27,12,24],kei:[7,11],miscellan:18,sure:11,proofread:12,cross:22,handl:26,blacklist:19,credit:9,within:26,grammar:[22,21],chang:[4,7,11,26,21],mail:[27,14,20],platform:18,candid:15,histori:23,possibl:11,alia:11,custom:5,load:11,minim:26,licens:[9,26],debug:16,addit:[7,22],interpret:7,intention:28,revis:11,core:[27,11,14],write:[14,17],gcov:6,meta:[22,24],inact:11,stabil:5,branch:[6,11,15,26],when:11,track:24,silenc:1,made:11,fals:28,from:[11,1],earli:6,secur:[22,15],result:[6,5],insid:11,workflow:28,"public":11,edit:11,resourc:7,rational:21,what:[4,11,19,14],out:11,accept:10,cpython:[25,11,21],expect:11,file:[16,27,25,6,11,12],disagre:11,scan:28,faq:11,learn:11,contributor:[26,14],auto:[11,16],channel:11,two:26,keep:11,"import":[25,6],unexpect:17,git:11,per:11,enter:11,know:11,messag:[11,26],remot:11,compar:11,style:[22,26],audienc:22,pass:26,quot:22,pre:[15,10],exist:[10,24],run:[11,17],fail:11,password:11,separ:11,"abstract":[25,21],pep:4,everyon:11,special:3,allow:11,titl:3,who:11,updat:11,without:22,recent:11,editor:16,modul:[6,22,10],skip:17,stage:[15,3],get:[27,16],need:11,head:11,code:[25,6,22,16,26],safe:11,copi:11,report:[11,24,28],structur:16,level:22,singl:26,object:25,entri:26,instead:11,approach:26,languag:[4,11],known:[25,28],alpha:15,design:25,manag:25,upload:[26,28],regener:11,after:23,request:23,section:22,changeset:[11,26],between:[11,26],footnot:22,test:[6,26,1,17],capit:22,compon:3,standard:11,increas:6,admin:23,ask:[27,11],control:[25,11,16],project:23,implement:7,sanit:19,displai:22,alreadi:[11,24],gdb:0,regrtest:6,posit:28,add:11,shorthand:11,type:[10,3],restructuredtext:22,dev:27,propos:[7,10],suggest:11,delet:11,current:11,instal:19,review:[9,26,24],last:11,lcov:6,configur:[11,26],pars:25,relat:25,regress:11,split:11,python:[26,4,19,27,20,7,22,11],submit:9,"new":[25,11,10,26],come:11,role:24,path:11,mainten:15,back:11,than:11,assign:3,hyperlink:22,refer:25,major:26,markup:22,abort:11,limit:28,step:8,initi:23,triag:[24,3],"long":26,repositori:[11,3],avoid:[11,16],requir:10,isn:11,blog:20,same:26,releas:[11,15],stdlib:[10,18],doe:26,unix:[11,16],syntax:25,later:0,llvm:19,failur:5,fix:13,patch:[9,11,26,24],should:11,revert:11,work:[11,26],"null":11,inlin:22,flow:25,clang:[19,16],have:11,beyond:13,loss:23,respons:14,itself:7,tell:11,link:[7,11,22,3],graph:[25,11],classifi:24,sever:11,where:[27,11],primer:22,commun:11,warn:1,index:[22,18],substitut:22,read:14,make:[22,11],system:11,"final":15,develop:[15,26,20,7,23,24,11,12,14],specif:[22,11],full:7,directori:[11,16],problem:11,dynam:19,compil:[25,16],"while":11,comment:[22,3],ast:25,why:11,some:11,follow:20,best:11,document:[22,12],whitespac:22,set:[16,8],contact:[23,28],nosi:3,how:[11,14],prioriti:3,access:28,checklist:[21,26],gotcha:[6,22],drop:23,intent:28,advanc:8,tone:22,resolut:[11,3],machin:11,tracker:[11,12,24,14],readi:26,analysi:[19,28],builder:5,sourc:[22,16],equival:22,bug:[27,11,24],affirm:22,model:28,see:11,express:22,main:15,constantli:11,visual:8,list:[3,27,20,22,11,14],sign:14,differ:26,support:[0,2],agreement:[26,14],setup:[19,16,26],becom:14,explicit:22,mark:11,line:11,about:11,studio:8,quick:7,experi:25,tag:11,bat:22,extern:22,content:[7,22],contribut:[7,11],behaviour:11,encod:22,issu:[3,24,6,11,12,13,14,28],cycl:15,privileg:14,measur:6,log:[11,23],suit:[26,1],summari:15,mercuri:[11,26,3],version:[11,16,26,3],introduct:22,coverag:6,xyz:11,easi:13,memori:25,supersed:3,guid:[7,22,12],merg:[11,26],gener:[9,22,11,16,3],port:26,clone:26,sync:11,build:[22,19,16,5,28],term:26,construct:22,cfg:25,checkout:14,activ:26,want:11,wai:11,keyword:3,paragraph:22,sentenc:22,can:[11,24],expert:18,find:[11,19,24],tabl:[7,22],introduc:[25,11],mentorship:27,direct:22,unit:22,depend:[16,5,3],start:[7,16],common:6,check:[11,24,5],beta:15,intern:22,emac:2,multipl:26,bytecod:25,"case":22,lifecycl:9,local:11,you:24,avail:11,modifi:11,hook:26,order:[26,5],"switch":11,window:[11,16,8],ignor:19,reject:9,field:3,other:[7,11,26,22],ssh:[11,14],show:22,automat:5,integr:5,qualifi:4,"transient":5,creat:[9,11,16],process:[4,10],permiss:23,question:11,concern:22,inform:22,still:26,exampl:22,earlier:0,consider:22,irc:20,particular:11,take:14,which:11,flag:5,undo:11,download:19,tree:25,solv:11,test_gdb:11,gain:[24,14],got:11,commit:[9,11,26,14],product:22,push:[11,26],economi:22,conflict:11,cover:28,prepar:9,latest:11,usag:9,tool:[9,16,18],featur:[11,26]},objtypes:{}}) \ No newline at end of file diff -r 85f290e474e2 build/setup.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/setup.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,424 @@ + + + + + + + + 1. Getting Started — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      1. Getting Started

      +

      These instructions cover how to get a working copy of the source code and a +compiled version of the CPython interpreter (CPython is the version of Python +available from http://www.python.org/). It also gives an overview of the +directory structure of the CPython source code.

      +

      OpenHatch also has a great setup guide for Python for people who are +completely new to contributing to open source.

      +
      +

      1.1. Getting Set Up

      +
      +

      1.1.1. Version Control Setup

      +

      CPython is developed using Mercurial. The Mercurial +command line program is named hg; this is also used to refer to Mercurial +itself. Mercurial is easily available for common Unix systems by way of the +standard package manager; under Windows, you might want to use the +TortoiseHg graphical client.

      +
      +
      +

      1.1.2. Getting the Source Code

      +

      One should always work from a working copy of the CPython source code. +While it may +be tempting to work from the copy of Python you already have installed on your +machine, it is very likely that you will be working from out-of-date code as +the Python core developers are constantly updating and fixing things in their +VCS. It also means you will have better tool +support through the VCS as it will provide a diff tool, etc.

      +

      To get a working copy of the in-development branch of +CPython (core developers use a different URL as outlined in How to Become a Core Developer), +run:

      +
      hg clone http://hg.python.org/cpython
+
      +
      +

      If you want a working copy of an already-released version of Python, +i.e., a version in maintenance mode, you can update your +working copy. For instance, to update your working copy to Python 3.3, do:

      +
      hg update 3.3
+
      +
      +

      You will need to re-compile CPython when you do such an update.

      +

      Do note that CPython will notice that it is being run from a working copy. +This means that if you edit CPython’s source code in your working copy, +changes to Python code will be picked up by the interpreter for immediate +use and testing. (If you change C code, you will need to recompile the +affected files as described below.)

      +

      Patches for the documentation can be made from the same repository; see +Documenting Python.

      +
      +
      +

      1.1.3. Compiling (for debugging)

      +

      CPython provides several compilation flags which help with debugging various +things. While all of the known flags can be found in the +Misc/SpecialBuilds.txt +file, the most critical one is the Py_DEBUG flag which creates what is +known as a “pydebug” build. This flag turns on +various extra sanity checks which help catch common issues. The use of the flag +is so common that turning on the flag is a basic compile option.

      +

      You should always +develop under a pydebug build of CPython (the only instance of when you +shouldn’t is if you are taking performance measurements). Even when working +only on pure Python code the pydebug build provides several useful checks that +one should not skip.

      +
      +

      1.1.3.1. Build dependencies

      +

      The core CPython interpreter only needs a C compiler to be built; if +you get compile errors with a C89 or C99-compliant compiler, please open a +bug report. +However, some of the extension modules will need development headers +for additional libraries (such as the zlib library for compression). +Depending on what you intend to work on, you might need to install these +additional requirements so that the compiled interpreter supports the +desired features.

      +

      For UNIX based systems, we try to use system libraries whenever available. +This means optional components will only build if the relevant system headers +are available. The best way to obtain the appropriate headers will vary by +distribution, but the appropriate commands for some popular distributions +are below.

      +

      Fedora, Red Hat Enterprise Linux and other yum based systems:

      +
      $ sudo yum install yum-utils
+$ sudo yum-builddep python3
+
      +
      +

      Debian, Ubuntu and other apt based systems:

      +
      $ sudo apt-get build-dep python3
+
      +
      +

      For Mac OS X systems, it is generally easiest to use the C compiler and other +development utilities provided by Apple’s Xcode Developer Tools. There are +specific versions supported by Apple for each major release of OS X. For +current releases, Xcode is available as a no-cost download from Apple’s App +Store. Xcode versions for older releases are available through +the Apple Developer web site. +Note that while the Xcode IDE application itself is not needed to build Python, +the development components packaged inside it may be. You should also install +the Xcode Command Line Tools component to ensure build tools and system header +files are installed in their conventional locations (/usr/bin and +/usr/include). How the command line tools are installed varies by OS X +and Xcode release. In earlier releases, there may be a separate installer +download. For OS X 10.7 and 10.8, there is an option in the Xcode app +Preferences menu. For OS X 10.9 (Mavericks), run the following:

      +
      $ xcode-select --install
+
      +
      +

      Also note that OS X does not include several libraries used by the Python +standard library, including libzma, so expect to see some extension module +build failures unless you install local copies of them.

      +

      There will sometimes be optional modules added for a new release which +won’t yet be identified in the OS level build dependencies. In those cases, +just ask for assistance on the core-mentorship list. If working on bug +fixes for Python 2.7, use python in place of python3 in the above +commands.

      +

      Explaining how to build optional dependencies on a UNIX based system without +root access is beyond the scope of this guide.

      +
      +

      Note

      +

      While you need a C compiler to build CPython, you don’t need any +knowledge of the C language to contribute! Vast areas of CPython are +written completely in Python: as of this writing, CPython contains slightly +more Python code than C.

      +
      +
      +
      +

      1.1.3.2. UNIX

      +

      The basic steps for building Python for development is to configure it and +then compile it.

      +

      Configuration is typically:

      +
      ./configure --with-pydebug
+
      +
      +

      More flags are available to configure, but this is the minimum you should +do to get a pydebug build of CPython.

      +

      Once configure is done, you can then compile CPython with:

      +
      make -s -j2
+
      +
      +

      This will build CPython with only warnings and errors being printed to +stderr and utilize up to 2 CPU cores. If you are using a multi-core machine +with more than 2 cores (or a single-core machine), you can adjust the number +passed into the -j flag to match the number of cores you have.

      +

      Do take note of what modules were not built as stated at the end of your +build. More than likely you are missing a dependency for the module(s) that +were not built, and so you can install the dependencies and re-run both +configure and make (if available for your OS). +Otherwise the build failed and thus should be fixed (at least with a bug being +filed on the issue tracker).

      +

      Once CPython is done building you will then have a working build +that can be run in-place; ./python on most machines (and what is used in +all examples), ./python.exe wherever a case-insensitive filesystem is used +(e.g. on OS X by default), in order to avoid conflicts with the Python +directory. There is normally no need to install your built copy +of Python! The interpreter will realize where it is being run from +and thus use the files found in the working copy. If you are worried +you might accidentally install your working copy build, you can add +--prefix=/tmp/python to the configuration step. When running from your +working directory, it is best to avoid using the --enable-shared flag +to configure; unless you are very careful, you may accidentally run +with code from an older, installed shared Python library rather than from +the interpreter you just built.

      +
      +
      1.1.3.2.1. Clang
      +

      If you are using clang to build CPython, some flags you might want to set to +quiet some standard warnings which are specifically superfluous to CPython are +-Wno-unused-value -Wno-empty-body -Qunused-arguments. You can set your +CFLAGS environment variable to these flags when running configure.

      +

      If you are using LLVM 2.8, also use the -no-integrated-as flag in order to +build the ctypes module (without the flag the rest of CPython will +still build properly).

      +
      +
      +
      +

      1.1.3.3. Windows

      +

      The readme included in the solution has more details, especially on the +software needed to resolve the below mentioned build errors.

      +

      Python 3.3 and later use Microsoft Visual Studio 2010. You can +download Microsoft Visual C++ 2010 Express from Microsoft’s site. +To use it for more than 28 days, one must register through a +Windows Live account.

      +

      Most Python versions prior to 3.3 use Microsoft Visual Studio 2008. You can +download Microsoft Visual C++ 2008 Express Edition with SP1 +from a new location yet to be determined.

      +

      Regardless of Visual Studio version, the PCbuild directory of a source +checkout contains the build files for the Python version you are building. +The full version of Visual Studio is not necessary for common tasks with +32-bit builds; the gratis C++ Express versions linked above are sufficient. +Their limitations are given here (2008) +and here (2010).

      +

      To build from the Visual Studio GUI, open the pcbuild.sln solution file +with Visual Studio. If you are using C++ Express, you may get an error message +indicating solution files are not supported, you can ignore it. Choose the +Build Solution option under the Build or +Debug menu (depending on your version of Visual Studio). +Be sure that “Debug” was chosen as the active solution configuration +(e.g. under Build ‣ Configuration Manager...)

      +

      When building you may see a number of build errors related to missing +files or directories. These do not necessarily mean that Python failed +to build. If you prefer, you can exclude the offending projects from +the build process by unchecking them inside the +Build ‣ Configuration Manager... settings. You can +also use the script Tools\buildbot\external.bat or +Tools\buildbot\external-amd64.bat (as applicable) to download and +compile missing dependencies.

      +

      Once built you might want to set Python as a startup project. Pressing F5 in +Visual Studio, or choosing Start Debugging from the Debug menu, will launch +the interpreter.

      +

      If you want to launch the compiled interpreter from the command-line, the +path varies according to the build. For a 32-bit build in debug mode, you +have to invoke PCBuild\python_d.exe, for a 64-bit build in debug mode, +PCBuild\amd64\python_d.exe. If you are compiling in release mode (which +you shouldn’t, in general), replace python_d.exe with python.exe.

      +

      For additional help for Windows see Setting Up Windows - Advanced

      +
      +
      +
      +

      1.1.4. Troubleshooting the build

      +

      This section lists some of the common problems that may arise during the +compilation of Python, with proposed solutions.

      +
      +

      1.1.4.1. Avoiding re-creating auto-generated files

      +

      Under some circumstances you may encounter Python errors in scripts like +Parser/asdl_c.py or Python/makeopcodetargets.py while running make. +Python auto-generates some of its own code, and a full build from scratch needs +to run the auto-generation scripts. However, this makes the Python build require +an already installed Python interpreter; this can also cause version mismatches +when trying to build an old (2.x) Python with a new (3.x) Python installed, or +vice versa.

      +

      To overcome this problem, auto-generated files are also checked into the +Mercurial repository. So if you don’t touch the auto-generation scripts, there’s +no real need to auto-generate anything. However, as Mercurial doesn’t preserve +timestamps well, a special build target touch was added. Run:

      +
      make touch
+
      +
      +

      Before running the compilation make. This will tweak the timestamps of the +auto-generated files in a way that makes it unnecessary to create them anew and +henceforth the compilation should not require an installed Python interpreter.

      +
      +
      +
      +
      +

      1.2. Editors and Tools

      +

      Python is used widely enough that practically all code editors have some form +of support for writing Python code. Various coding tools also include Python +support.

      +

      For editors and tools which the core developers have felt some special comment +is needed for coding in Python, see Additional Resources.

      +
      +
      +

      1.3. Directory Structure

      +

      There are several top-level directories in the CPython source tree. Knowing what +each one is meant to hold will help you find where a certain piece of +functionality is implemented. Do realize, though, there are always exceptions to +every rule.

      +
      +
      Doc
      +
      The official documentation. This is what http://docs.python.org/ uses. +See also Building the documentation.
      +
      Grammar
      +
      Contains the EBNF grammar file for +Python.
      +
      Include
      +
      Contains all interpreter-wide header files.
      +
      Lib
      +
      The part of the standard library implemented in pure Python.
      +
      Mac
      +
      Mac-specific code (e.g., using IDLE as an OS X application).
      +
      Misc
      +
      Things that do not belong elsewhere. Typically this is varying kinds of +developer-specific documentation.
      +
      Modules
      +
      The part of the standard library (plus some other code) that is implemented +in C.
      +
      Objects
      +
      Code for all built-in types.
      +
      PC
      +
      Windows-specific code along with legacy build files for previously used +versions of MSVC.
      +
      PCbuild
      +
      Build files for the version of MSVC currently used for the Windows +installers provided on python.org.
      +
      Parser
      +
      Code related to the parser. The definition of the AST nodes is also kept +here.
      +
      Python
      +
      The code that makes up the CPython interpreter. This includes the compiler, +eval loop and various built-in modules.
      +
      Tools
      +
      Various tools that are (or have been) used to maintain Python.
      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      Python Developer’s Guide

      +

      Next topic

      +

      2. Where to Get Help

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/setupWindows.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/setupWindows.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,224 @@ + + + + + + + + 2. Setting Up Windows - Advanced — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      2. Setting Up Windows - Advanced

      +

      The online directions for downloading the development version source are fine +and can be found at Windows. There is also +information in the readme file found in the source directory that is helpful.

      +

      Mercurial must be installed on your machine. +Stable released version source is available on the download page.

      +

      Subversion is necessary because some of the third party components for the +windows built are still in a subversion repository.

      +

      Python building/rebuilding assumes the existence of subversion, perl, and a +version of Visual Studio on your system. If you have all three, skip to step +three. Otherwise download and install any of those that are missing.

      +

      If it is necessary to have on hand multiple versions of python built from scratch, you +should isolate them from each other by putting them in a container directory +perhaps of the same name:

      +
      python331/python331, python32/python32
+
      +
      +

      where the subdirectory is the source root directory. Use the upper directory +to isolate the external subprojects created by the buildbots described later. +The buildbots of one version can wipe out required subprojects of another +version of python which can cause confusion.

      +
      +

      2.1. Step 0

      +

      Download and install a subversion client and add the executable to your path.

      +
      +
      +

      2.2. Step 1

      +

      Download and install perl and add the executable to your path.

      +
      +
      +

      2.3. Step 2

      +

      Download and install Visual Studio 2010. Either Express C++ will work or +Visual Studio Professional. Express is free, however, when the solution file +is loaded, an error message is displayed.

      +

      Visual Studio should be in your path.

      +
      +
      +

      2.4. Step 3

      +

      Download and install NASM

      +
      +
      +

      2.5. Step 4

      +

      Download and build the external subprojects with the buildbots using either:

      +
      Tools\buildbot\external.bat         # for 32 bit processors
+Tools\buildbot\external-amd64.bat   # for 64 bit processors
+
      +
      +

      from the root directory or your python distribution. +This step will download the correct versions of the external projects for +this version of python. There are several projects

      +
      +
      +

      2.6. Step 5

      +

      openssl is used for python on windows +ssl rarely succeeds if you proceed to build using pcbuild.sln:

      +

      The following steps will resolve many problems if you executing them +before building with the .sln file:

      +
      cd into the openssl directory created by the buildbots
+perl util\mkdef.pl crypto ssl update
+perl Configure VC-WIN32 --prefix=C:\opt\openssl-1.0.1d
+ms\do_nasm
+
      +
      +

      Compilation errors may occur when you attempt to build the .sln file with +Visual Studio. The errors are typically a forced error contained within a +block of conditional code. Good results have been found by commenting out +the forced error. Most recently commenting out code blocks in +mdc2.h and idea.h produced good results.

      +

      Historically, the openssl build has not had a “clean” function. Cleaning the +project by deleting and letting the buildbot download again gave good results.

      +
      +
      +

      2.7. Step 6

      +

      Finally Build python and its internal subprojects

      +
      +

      Open the solution “pcbuild.sln” in Visual Studio +If you have an express version, then ignore the warning +Select the configuration (Release or Debug)

      +
      "Release" builds python.exe
+"Debug" builds python_d.exe
+Select the platform   Win32 or x64
+Build the solution.
+Right click "Solution 'pccuild'"  and select
+   build - for fresh build
+   clean - to delete all files created for build , i.e. objects,
+   libraries, executable, etc.
+   rebuild - clean and build everything
+
      +
      +
      +

      Note that you can clean and build individual subprojects by right clicking +on the subproject and selecting build, clean, or rebuild for that project

      +
      +

      2.7.1. Using Visual Studio

      +

      There is Python Tools for Visual Studio an addon published +by Microsoft for many versions of Visual Studio except the Express editions.

      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      1. Getting Started

      +

      Next topic

      +

      3. Where to Get Help

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/silencewarnings.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/silencewarnings.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,120 @@ + + + + + + + + 9. Silence Warnings From the Test Suite — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      9. Silence Warnings From the Test Suite

      +

      When running Python’s test suite, no warnings should result when you run it +under strenuous testing conditions (you can ignore +the extra flags passed to test that cause randomness and parallel execution +if you want). Unfortunately new warnings are added to Python on occasion which +take some time to eliminate (e.g., ResourceWarning). Typically the easy +warnings are dealt with quickly, but the more difficult ones that require some +thought and work do not get fixed immediately.

      +

      If you decide to tackle a warning you have found, open an issue on the issue +tracker (if one has not already been opened) and say you are going to try and +tackle the issue, and then proceed to fix the issue.

      +
      + + +
      +
      +
      +
      +
      +

      Previous topic

      +

      8. Documenting Python

      +

      Next topic

      +

      10. Fixing “easy” Issues (and Beyond)

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/stdlibchanges.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/stdlibchanges.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,244 @@ + + + + + + + + 20. Adding to the Stdlib — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      20. Adding to the Stdlib

      +

      While the stdlib contains a great amount of useful code, sometimes you want +more than is provided. This document is meant to explain how you can get either +a new addition to a pre-existing module in the stdlib or add an entirely new +module.

      +

      Changes to pre-existing code is not covered as that is considered a bugfix and +thus is treated as a bug that should be filed on the issue tracker.

      +
      +

      20.1. Adding to a pre-existing module

      +

      If you have found that a function, method, or class is useful and you believe +it would be useful to the general Python community, there are some steps to go +through in order to see it added to the stdlib.

      +

      First is you should gauge the usefulness of the code. Typically this is done +by sharing the code publicly. You have a couple of options for this. One is to +post it online at the Python Cookbook. Based on feedback or reviews of the +recipe you can see if others find the functionality as useful as you do. +A search of the issue tracker for previous suggestions related to the proposed +addition may turn up a rejected issue that explains why the suggestion will not +be accepted. +Another is to do a blog post about the code and see what kind of responses you +receive. Posting to python-list (see Following Python’s Development for where to find the +list and other mailing lists) to discuss your code also works. Finally, asking +on a specific SIG from mail.python.org or +python-ideas is also acceptable. This is not a required step but it is +suggested.

      +

      If you have found general acceptance and usefulness for your code from people, +you can open an issue on the issue tracker with the code attached as a +patch. If possible, also submit a +contributor agreement.

      +

      If a core developer decides that your code would be useful to the general +Python community, they will then commit your code. If your code is not picked +up by a core developer and committed then please do not take this personally. +Through your public sharing of your code in order to gauge community support +for it you at least can know that others will come across it who may find it +useful.

      +
      +
      +

      20.2. Adding a new module

      +

      It must be stated upfront that getting a new module into the stdlib is very +difficult. Adding any significant amount of code to the stdlib increases the +burden placed upon core developers. It also means that the module somewhat +becomes “sanctioned” by the core developers as a good way to do something, +typically leading to the rest of the Python community to using the new module +over other available solutions. All of this means that additions to the stdlib +are not taken lightly.

      +
      +

      20.2.1. Acceptable Types of Modules

      +

      Typically two types of modules get added to the stdlib. One type is a module +which implements something that is difficult to get right. A good example of +this is the multiprocessing package. Working out the various OS +issues, working through concurrency issues, etc. are all very difficult to get +right.

      +

      The second type of module is one that implements something that people +re-implement constantly. The itertools module is a good example of +this type as its constituent parts are not necessarily complex, but are used +regularly in a wide range of programs and can be a little tricky to get right. +Modules that parse widely used data formats also fall under this type of module +that the stdlib consists of.

      +

      While a new stdlib module does not need to appeal to all users of Python, it +should be something that a large portion of the community will find useful. +This makes sure that the developer burden placed upon core developers is worth +it.

      +
      +
      +

      20.2.2. Requirements

      +

      In order for a module to even be considered for inclusion into the stdlib, a +couple of requirements must be met.

      +

      The most basic is that the code must meet +standard patch requirements. For code that has +been developed outside the stdlib typically this means making sure the coding +style guides are followed and that the proper tests have been written.

      +

      The module needs to have been out in the community for at least a year. Because +of Python’s conservative nature when it comes to backwards-compatibility, when +a module is added to the stdlib its API becomes frozen. This means that a module +should only enter the stdlib when it is mature and gone through its +“growing pains”.

      +

      The module needs to be considered best-of-breed. When something is included in +the stdlib it tends to be chosen first for products over other third-party +solutions. By virtue of having been available to the public for at least a +year, a module needs to have established itself as (one of) the top choices by +the community for solving the problem the module is intended for.

      +

      The development of the module must move into Python’s +infrastructure (i.e., the module is no longer directly maintained outside of +Python). This prevents a divergence between the code that is included in the +stdlib and that which is released outside the stdlib (typically done to provide +the module to older versions of Python). It also removes the burden of forcing +core developers to have to redirect bug reports or patches to an external issue +tracker and VCS.

      +

      Someone involved with the development of the +module must promise to help maintain the module in the stdlib for two years. +This not only helps out other core developers by alleviating workload from bug +reports that arrive from the first Python release containing the module, but +also helps to make sure that the overall design of the module continues to be +uniform.

      +
      +
      +

      20.2.3. Proposal Process

      +

      If the module you want to propose adding to the stdlib meets the proper +requirements, you may propose its inclusion. To start, you should email +python-list or python-ideas to make sure the community in general would support +the inclusion of the module (see Following Python’s Development).

      +

      If the feedback from the community is positive overall, you will need to write +a PEP for the module’s inclusion. It +should outline what the module’s overall goal is, why it should be included in +the stdlib, and specify the API of the module. See the PEP index for PEPs +that have been accepted before that proposed a module for inclusion.

      +

      Once your PEP is written, send it to python-ideas for basic vetting. Be +prepared for extensive feedback and lots of discussion (not all of it +positive). This will help make the PEP be of good quality and properly +formatted.

      +

      When you have listened to, responded, and integrated as appropriate the +feedback from python-ideas into your PEP, you may send it to python-dev. You +will once again receive a large amount of feedback and discussion. A PEP +dictator will be assigned who makes the final call on whether the PEP will be +accepted or not. If the PEP dictator agrees to accept your PEP (which typically +means that the core developers end up agreeing in general to accepting +your PEP) then the module +will be added to the stdlib once the creators of the module sign +contributor agreements.

      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      19. Continuous Integration

      +

      Next topic

      +

      21. Changing the Python Language

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/tracker.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/tracker.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,286 @@ + + + + + + + + 11. Issue Tracking — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      11. Issue Tracking

      +
      +

      11.1. Using the Issue Tracker

      +

      If you think you found a bug in Python, you can report it to the +issue tracker. Documentation bugs can also be reported there. +Issues about the tracker should be reported to the meta tracker.

      +
      +

      11.1.1. Checking if a bug already exists

      +

      The first step in filing a report is to determine whether the problem has +already been reported. The advantage in doing so, aside from saving the +developers time, is that you learn what has been done to fix it; it may be that +the problem has already been fixed for the next release, or additional +information is needed (in which case you are welcome to provide it if you can!).

      +

      To do this, search the bug database using the search box on the top of the page. +An advanced search is also available by clicking on “Search” in +the sidebar.

      +
      +
      +

      11.1.2. Reporting an issue

      +

      If the problem you’re reporting is not already in the issue tracker, you +need to log in by entering your user and password in the form on the left. +If you don’t already have a tracker account, select the “Register” link or, +if you use OpenID, one of the OpenID provider logos in the sidebar.

      +

      It is not possible to submit a bug report anonymously.

      +

      Being now logged in, you can submit a bug by clicking on the “Create New” link +in the sidebar.

      +

      The submission form has a number of fields, and they are described in detail +in the Triaging an Issue page. This is a short summary:

      +
        +
      • in the Title field, enter a very short description of the problem; +less than ten words is good;
        • +
      • in the Type field, select the type of your problem (usually behavior);
        • +
      • if you know which Components and Versions are affected by the issue, +you can select these too;
        • +
      • if you have JavaScript enabled, you can use the Nosy List field to search +developers that can help with the issue by entering the name of the affected +module, operating system, or interest area.
        • +
      • last but not least, you have to describe the problem in detail, including +what you expected to happen and what did happen, in the Comment field. +Be sure to include whether any extension modules were involved, and what +hardware and software platform you were using (including version information +as appropriate).
        • +
      +

      The triaging team will take care of setting other fields, and possibly assign +the issue to a specific developer. You will automatically receive an update +each time an action is taken on the bug.

      +
      +
      +
      +

      11.2. Helping Triage Issues

      +

      Once you know your way around how Python’s source files are +structured and you are comfortable working with patches, a great way to +participate is to help triage issues. Do realize, though, that experience +working on Python is needed in order to effectively help triage.

      +

      Around the clock, new issues are being opened on the issue tracker and +existing issues are being updated. Every +issue needs to be triaged to make sure various things are in proper order. Even +without special privileges you can help with this process.

      +
      +

      11.2.1. Classifying Reports

      +

      For bugs, an issue needs to:

      +
        +
      • clearly explain the bug so it can be reproduced
        • +
      • include all relevant platform details
        • +
      • state what version(s) of Python are affected by the bug.
        • +
      +

      These are things you can help with once you have experience developing for +Python. For instance, if a bug is not clearly explained enough for you to +reproduce it then there is a good chance a core developer won’t be able to +either. And it is always helpful to know if a bug not only affects the +in-development version of Python, but whether it also affects other versions in +maintenance mode. And if the bug lacks a unit test that should end up in +Python’s test suite, having that written can be very helpful.

      +

      This is all helpful as it allows triagers (i.e., +people with the Developer role on the issue tracker) to +properly classify an issue so it can be handled by the right core developers in +a timely fashion.

      +
      +
      +

      11.2.2. Reviewing Patches

      +

      If an issue has a patch attached that has not been reviewed, you can help by +making sure the patch:

      +
        +
      • follows the style guides
        • +
      • applies cleanly to an up-to-date clone
        • +
      • is a good solution to the problem it is trying to solve
        • +
      • includes proper tests
        • +
      • includes proper documentation changes
        • +
      • submitter is listed in Misc/ACKS, either already or the patch adds them
        • +
      +

      Doing all of this allows core developers and triagers to more +quickly look for subtle issues that only people with extensive experience +working on Python’s code base will notice.

      +
      +
      +

      11.2.3. Finding an Issue You Can Help With

      +

      If you want to help triaging issues, you might also want to search for issues +that you are knowledgeable about. An easy way to do it, is to search for +the name of a module you are familiar with. You can also use the +advanced search and search for specific components (e.g. “Windows” if you +are a Windows developer, “Extension Modules” if you are familiar with C, etc.). +Finally you can use the “Random issue” link in the sidebar to pick random +issues until you find an issue that you like. Is not so uncommon to find old +issues that can be closed, either because they are no longer valid, or +because they have a patch that is ready to be committed, but no one had +time to do it yet.

      +

      In the sidebar you can also find links to summaries for easy issues and +issues with a patch.

      +
      +
      +
      +

      11.3. Gaining the “Developer” Role on the Issue Tracker

      +

      When you have consistently shown the ability to properly +help triage issues without guidance, you may request that you +be given the “Developer” role on the issue tracker. You can make the request +of any person who already has the Developer role. If they decide you are ready +to gain the extra privileges on the tracker they will then act as a mentor to +you until you are ready to do things entirely on your own. There is no set rule +as to how many issues you need to have helped with before or how long you have +been participating. The key requirements are that you show the desire to +help, you are able to work well with others (especially those already with the +Developer role), and that have a firm grasp of how to do things on the issue +tracker properly on your own.

      +

      Gaining the Developer role will allow you to set any value on any issue in the +tracker, releasing you from the burden of having to ask others to set values on +an issue for you in order to properly triage something. This will not only help +speed up and simplify your work in helping out, but also help lessen the +workload for everyone by gaining your help.

      +
      +
      +

      11.4. The Meta Tracker

      +

      If you find an issue with the issue tracker, you can report it to the +meta tracker. The meta tracker is where you file issues against anything +you come across when working with the issue tracker itself (e.g you can’t +attach a file, the layout is broken on your browser, Rietveld gave you an +error, etc.).

      +

      If you want to contribute to the tracker you can get a checkout of the source +and install a local instance where to experiment. You can find detailed +instructions on the Tracker Development page.

      +
      +

      See also

      +
      +
      The Python issue tracker
      +
      Where to report issues about Python.
      +
      The New-bugs-announce mailing list
      +
      Where all the new issues created on the tracker are reported.
      +
      The Python-bugs-list mailing list
      +
      Where all the changes to issues are reported.
      +
      The meta tracker
      +
      Where to report issues about the tracker itself.
      +
      The Tracker development wiki page
      +
      Instructions about setting up a local instance of the bug tracker.
      +
      The Tracker-discuss mailing list
      +
      Discussions about the bug tracker.
      +
      +
      +
      +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      10. Fixing “easy” Issues (and Beyond)

      +

      Next topic

      +

      12. Triaging an Issue

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 build/triaging.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/build/triaging.html Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,427 @@ + + + + + + + + 12. Triaging an Issue — Python Developer's Guide + + + + + + + + + + + + + +
      +

      Navigation

      + +
      + +
      +
      +
      +
      + +
      +

      12. Triaging an Issue

      +

      When you have the Developer role on the issue tracker you are able to triage +issues directly without any assistance.

      +
      +

      12.1. Fields

      +
      +

      12.1.1. Title

      +

      Should be properly descriptive of what the issue is about. Occasionally +people file an issue that either has too generic of a title or end up thinking +they filed about X but in fact it turns out to be about Y and thus the +title is now wrong.

      +
      +
      +

      12.1.2. Type

      +

      Describes the type of issue. If something does not fit within any +specific type then simply do not set it.

      +
      +
      behavior
      +
      Wrong or unexpected behavior, result, or exception. This includes most of +the bugs.
      +
      crash
      +
      Hard crashes of the Python interpreter – possibly with a core +dump or a Windows error box.
      +
      compile error
      +
      Errors reported by the compiler while compiling Python.
      +
      resource usage
      +
      Situations where too many resources (e.g. memory) are used.
      +
      security
      +
      Issues that might have security implications. If you think the issue +should not be made public, please report it to security@python.org instead.
      +
      performance
      +
      Situations where too much time is necessary to complete the task.
      +
      enhancement
      +
      Issues that propose the addition of new functionality, such as new +functions, classes, modules, or even new arguments for existing functions. +Also used for improvements in the documentation and test suite and for +other refactorings.
      +
      +
      +
      +

      12.1.3. Stage

      +

      What is needed next to advance the issue. The stage needn’t be set until +it is clear that the issue warrants fixing.

      +
      +
      test needed
      +
      The bug reporter should post a script or instructions to let a triager or +developer reproduce the issue.
      +
      needs patch
      +
      The issue lacks a patch to solve the problem (i.e. fixing the bug, or +adding the requested improvement).
      +
      patch review
      +
      There is a patch, but it needs reviewing or is in the process of being +reviewed. This can be done by any triager as well as a core developer.
      +
      commit review
      +
      A triager performed a patch review and it looks good to them, but a core +developer needs to commit the patch (and do a quick once-over to make sure +nothing was overlooked).
      +
      committed/rejected
      +
      The issue is considered closed and dealt with.
      +
      +
      +
      +

      12.1.4. Components

      +

      What part of Python is affected by the issue. This is a multi-select field. +Be aware that what component is chosen may cause the issue to be auto-assigned, +i.e. the issue tracker may automatically fill in the Assigned To field +after you press Submit changes.

      +

      The following component(s) should be selected if the issue applies to:

      +
      +
      2to3 (2.x to 3.0 conversion tool)
      +
      The 2to3 conversion tool in Lib/lib2to3.
      +
      Benchmarks
      +
      The benchmarks in the benchmarks repo.
      +
      Build
      +
      The build process.
      +
      ctypes
      +
      The ctypes package in Lib/ctypes.
      +
      Demos and Tools
      +
      The files in Tools and Tools/demo.
      +
      Devguide
      +
      The Developer’s guide.
      +
      Distutils
      +
      The distutils package in Lib/distutils.
      +
      Distutils2
      +
      The packaging module in Lib/packaging.
      +
      Documentation
      +
      The documentation in Doc (used to build the HTML doc at http://docs.python.org/).
      +
      email
      +
      The email package and related modules.
      +
      Extension Modules
      +
      C modules in Modules.
      +
      IDLE
      +
      The Lib/idlelib package.
      +
      Installation
      +
      The installation process.
      +
      Interpreter Core
      +
      The interpreter core, the built-in objects in Objects, the Python, +Grammar and Parser dirs.
      +
      IO
      +
      The I/O system, Lib/io.py and Modules/_io.
      +
      Library (Lib)
      +
      Python modules in Lib.
      +
      Macintosh
      +
      The Mac OS X operating system.
      +
      Regular Expressions
      +
      The Lib/re.py and Modules/_sre.c modules.
      +
      Tests
      +

      The unittest and doctest frameworks in Lib/unittest and +Lib/doctest.py.

      +

      The CPython tests in Lib/test, the test runner in Lib/test/regrtest.py +and the Lib/test/support.py module.

      +
      +
      Tkinter
      +
      The Lib/tkinter package.
      +
      Unicode
      +
      Unicode, codecs, str vs bytes, Objects/unicodeobject.c.
      +
      Windows
      +
      The Windows operating system.
      +
      XML
      +
      The Lib/xml package.
      +
      +
      +
      +

      12.1.5. Versions

      +

      The known versions of Python that the issue affects and should be fixed for. +Thus if an issue for a new feature is assigned for e.g., Python 3.3 but is not +applied before Python 3.3.0 is released, this field should be updated to say +Python 3.4 as the version and drop Python 3.3.

      +
      +
      +

      12.1.6. Priority

      +

      How important is this issue?

      +
      +
      low
      +
      This is for low-impact bugs, or feature requests of little utility.
      +
      normal
      +
      The default value for most issues, which deserve fixing but without +any urgency to do so.
      +
      high
      +
      Make some effort to fix the issue before the next final release.
      +
      critical
      +
      This issue should definitely be fixed before the next final release.
      +
      deferred blocker
      +
      The issue will not hold up the next release, but will be promoted to a +release blocker for the following release, e.g., won’t block the next +release of a1 but will block a2.
      +
      release blocker
      +
      The issue must be fixed before any release is made, e.g., will block the +next release even if it is an alpha release.
      +
      +

      As a guideline, critical and above are usually reserved for crashes, +serious regressions or breakage of very important APIs. Whether a bug +is a release blocker is a decision better left to the release manager so, +in any doubt, add him or her to the nosy list.

      +
      +
      +

      12.1.7. Keywords

      +

      Various flags about the issue. Multiple values are possible.

      +
      +
      buildbot
      +
      A buildbot triggered the issue being reported.
      +
      easy
      +
      Fixing the issue should not take longer than a day for someone new to +contributing to Python to solve.
      +
      gsoc
      +
      The issue would fit as, or is related to, a GSoC project.
      +
      needs review
      +
      The patch attached to the issue is in need of a review.
      +
      patch
      +
      There is a patch attached to the issue.
      +
      3.3regression
      +
      The issue is a regression in 3.3.
      +
      +
      +
      +

      12.1.8. Nosy List

      +

      A list of people who may be interested in an issue. It is acceptable to add +someone to the nosy list if you think the issue should be brought to their +attention. Use the Experts Index to know who wants to be added to the nosy +list for issues targeting specific areas.

      +

      If you are logged in and have JavaScript enabled, you can use the [+] +button to add yourself to the nosy list (remember to click on +“Submit Changes” afterwards). Note that you are added to the nosy +automatically when you submit a message. +The nosy list also has an autocomplete that lets you search from the lists of +developers and Experts Index. The search is case-insensitive and +works for real names, modules, interest areas, etc., and only adds the +username(s) to the nosy once an entry is selected.

      +
      +
      +

      12.1.9. Assigned To

      +

      Who is expected to take the next step in resolving the issue. It is acceptable +to assign an issue to someone if the issue cannot move forward without their +help, e.g., they need to make a technical decision to allow the issue to move +forward. Also consult the Experts Index as certain stdlib modules should +always be assigned to a specific person.

      +
      +
      +

      12.1.10. Dependencies

      +

      The issue requires the listed issue(s) to be resolved first before it can move +forward.

      +
      +
      +

      12.1.11. Superseder

      +

      The issue is a duplicate of the listed issue(s).

      +
      +
      +

      12.1.12. Status

      +
      +
      open
      +
      Issue is not resolved.
      +
      languishing
      +
      The issue has no clear solution , e.g., no agreement on a technical +solution or if it is even a problem worth fixing.
      +
      pending
      +
      The issue is blocked until someone (often the +OP) provides some critical information; +the issue will be closed after a set amount of time if no reply comes in. +Useful when someone opens an issue that lacks enough information to +reproduce the bug reported. Requesting additional information and setting +status to pending indicates that the issue should be closed if the +necessary information is never provided.
      +
      closed
      +
      The issue has been resolved (somehow).
      +
      +
      +
      +

      12.1.13. Resolution

      +

      Why the issue is in its current state (not usually used for “open”).

      +
      +
      duplicate
      +
      Duplicate of another issue; should have the Superseder field filled out.
      +
      fixed
      +
      A fix for the issue was committed.
      +
      invalid
      +
      For some reason the issue is invalid (e.g. the perceived problem is not +a bug in Python).
      +
      later
      +
      Issue is to be worked on at a later date.
      +
      out of date
      +
      The issue has already been fixed, or the problem doesn’t exist anymore +for other reasons.
      +
      postponed
      +
      Issue will not be worked on at the moment.
      +
      rejected
      +
      Issue was rejected (especially for feature requests).
      +
      remind
      +
      The issue is acting as a reminder for someone.
      +
      wont fix
      +
      Issue will not be fixed, typically because it would cause a +backwards-compatibility problem.
      +
      works for me
      +
      Bug cannot be reproduced.
      +
      +
      +
      +

      12.1.14. Mercurial Repository

      +

      HTTP link to a Mercurial repository that contains a patch for the issue. +A Create Patch button will appear that computes a diff for the +head revision of the remote branch and attaches it to the issue. The button +supports only CPython patches.

      +

      If you don’t indicate a remote branch, default is used. You can +indicate a remote branch by adding #BRANCH to the end of the URL.

      +
      +
      + +
      + + +
      +
      +
      +
      +
      +

      Table Of Contents

      + + +

      Previous topic

      +

      11. Issue Tracking

      +

      Next topic

      +

      13. Following Python’s Development

      +

      This Page

      + + + +
      +
      +
      +
      +
      +

      Navigation

      + +
      +
      + © Copyright 2011-2012, Python Software Foundation. + Created using Sphinx 1.2.2. +
      + + \ No newline at end of file diff -r 85f290e474e2 index.rst --- a/index.rst Mon Mar 17 21:35:56 2014 -0500 +++ b/index.rst Wed Mar 19 13:46:42 2014 -0500 @@ -187,6 +187,7 @@ :numbered: setup + setupwindows help patch runtests diff -r 85f290e474e2 setup.rst --- a/setup.rst Mon Mar 17 21:35:56 2014 -0500 +++ b/setup.rst Wed Mar 19 13:46:42 2014 -0500 @@ -49,9 +49,9 @@ If you want a working copy of an already-released version of Python, i.e., a version in :ref:`maintenance mode `, you can update your -working copy. For instance, to update your working copy to Python 3.4, do:: +working copy. For instance, to update your working copy to Python 3.3, do:: - hg update 3.4 + hg update 3.3 You will need to re-compile CPython when you do such an update. @@ -216,7 +216,6 @@ Windows ''''''' - The readme included in the solution has more details, especially on the software needed to resolve the below mentioned build errors. @@ -240,11 +239,12 @@ `_. To build from the Visual Studio GUI, open the ``pcbuild.sln`` solution file -with Visual Studio. Choose the :menuselection:`Build Solution` option -under the :menuselection:`Build` or :menuselection:`Debug` menu -(depending on your version of Visual Studio). Be sure that "Debug" was -chosen as the active solution configuration (e.g. under -:menuselection:`Build --> Configuration Manager...`). +with Visual Studio. If you are using C++ Express, you may get an error message +indicating solution files are not supported, you can ignore it. Choose the +:menuselection:`Build Solution` option under the :menuselection:`Build` or +:menuselection:`Debug` menu (depending on your version of Visual Studio). +Be sure that "Debug" was chosen as the active solution configuration +(e.g. under :menuselection:`Build --> Configuration Manager...`) When building you may see a number of build errors related to missing files or directories. These do not necessarily mean that Python failed @@ -267,6 +267,8 @@ ``PCBuild\amd64\python_d.exe``. If you are compiling in release mode (which you shouldn't, in general), replace ``python_d.exe`` with ``python.exe``. +For additional help for Windows see :ref:`windows-advanced` + .. _build_troubleshooting: Troubleshooting the build diff -r 85f290e474e2 setupwindows.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/setupwindows.rst Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,126 @@ +.. _windows-advanced: + +============================= +Setting Up Windows - Advanced +============================= + +The online directions for downloading the development version source are fine +and can be found at :ref:`Windows `. There is also +information in the readme file found in the source directory that is helpful. + +Mercurial must be installed on your machine. +Stable released version source is available on the download page. + +Subversion is necessary because some of the third party components for the +windows built are still in a subversion repository. + +Python building/rebuilding assumes the existence of subversion, perl, and a +version of Visual Studio on your system. If you have all three, skip to step +three. Otherwise download and install any of those that are missing. + +If it is necessary to have on hand multiple versions of python built from scratch, you +should isolate them from each other by putting them in a container directory +perhaps of the same name:: + + python331/python331, python32/python32 + +where the subdirectory is the source root directory. Use the upper directory +to isolate the external subprojects created by the buildbots described later. +The buildbots of one version can wipe out required subprojects of another +version of python which can cause confusion. + +------ +Step 0 +------ + +Download and install a subversion client and add the executable to your path. + +------ +Step 1 +------ + +Download and install perl and add the executable to your path. + +------ +Step 2 +------ + +Download and install Visual Studio 2010. Either Express C++ will work or +Visual Studio Professional. Express is free, however, when the solution file +is loaded, an error message is displayed. + +Visual Studio should be in your path. + +------ +Step 3 +------ + +Download and install `NASM `_ + +------ +Step 4 +------ + +Download and build the external subprojects with the buildbots using either:: + + Tools\buildbot\external.bat # for 32 bit processors + Tools\buildbot\external-amd64.bat # for 64 bit processors + +from the root directory or your python distribution. +This step will download the correct versions of the external projects for +this version of python. There are several projects + +------ +Step 5 +------ + + +openssl is used for python on windows +ssl rarely succeeds if you proceed to build using pcbuild.sln: + +The following steps will resolve many problems if you executing them +before building with the .sln file:: + + cd into the openssl directory created by the buildbots + perl util\mkdef.pl crypto ssl update + perl Configure VC-WIN32 --prefix=C:\opt\openssl-1.0.1d + ms\do_nasm + +Compilation errors may occur when you attempt to build the .sln file with +Visual Studio. The errors are typically a forced error contained within a +block of conditional code. Good results have been found by commenting out +the forced error. Most recently commenting out code blocks in +mdc2.h and idea.h produced good results. + +Historically, the openssl build has not had a "clean" function. Cleaning the +project by deleting and letting the buildbot download again gave good results. + + +------ +Step 6 +------ + +Finally Build python and its internal subprojects + + Open the solution "pcbuild.sln" in Visual Studio + If you have an express version, then ignore the warning + Select the configuration (Release or Debug) :: + + "Release" builds python.exe + "Debug" builds python_d.exe + Select the platform Win32 or x64 + Build the solution. + Right click "Solution 'pccuild'" and select + build - for fresh build + clean - to delete all files created for build , i.e. objects, + libraries, executable, etc. + rebuild - clean and build everything + +Note that you can clean and build individual subprojects by right clicking +on the subproject and selecting build, clean, or rebuild for that project + +Using Visual Studio +=================== + +There is `Python Tools for Visual Studio `_ an addon published +by Microsoft for many versions of Visual Studio except the Express editions. \ No newline at end of file diff -r 85f290e474e2 windows.patch --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/windows.patch Wed Mar 19 13:46:42 2014 -0500 @@ -0,0 +1,23270 @@ +diff -r 85f290e474e2 build/.buildinfo +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/.buildinfo Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,4 @@ ++# Sphinx build info version 1 ++# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. ++config: ff002fe3fb4d67cf9f7514eb72352e1d ++tags: 645f666f9bcd5a90fca523b33c5a78b7 +diff -r 85f290e474e2 build/.doctrees/buildbots.doctree +Binary file build/.doctrees/buildbots.doctree has changed +diff -r 85f290e474e2 build/.doctrees/clang.doctree +Binary file build/.doctrees/clang.doctree has changed +diff -r 85f290e474e2 build/.doctrees/committing.doctree +Binary file build/.doctrees/committing.doctree has changed +diff -r 85f290e474e2 build/.doctrees/communication.doctree +Binary file build/.doctrees/communication.doctree has changed +diff -r 85f290e474e2 build/.doctrees/compiler.doctree +Binary file build/.doctrees/compiler.doctree has changed +diff -r 85f290e474e2 build/.doctrees/coredev.doctree +Binary file build/.doctrees/coredev.doctree has changed +diff -r 85f290e474e2 build/.doctrees/coverage.doctree +Binary file build/.doctrees/coverage.doctree has changed +diff -r 85f290e474e2 build/.doctrees/coverity.doctree +Binary file build/.doctrees/coverity.doctree has changed +diff -r 85f290e474e2 build/.doctrees/devcycle.doctree +Binary file build/.doctrees/devcycle.doctree has changed +diff -r 85f290e474e2 build/.doctrees/developers.doctree +Binary file build/.doctrees/developers.doctree has changed +diff -r 85f290e474e2 build/.doctrees/docquality.doctree +Binary file build/.doctrees/docquality.doctree has changed +diff -r 85f290e474e2 build/.doctrees/documenting.doctree +Binary file build/.doctrees/documenting.doctree has changed +diff -r 85f290e474e2 build/.doctrees/emacs.doctree +Binary file build/.doctrees/emacs.doctree has changed +diff -r 85f290e474e2 build/.doctrees/environment.pickle +Binary file build/.doctrees/environment.pickle has changed +diff -r 85f290e474e2 build/.doctrees/experts.doctree +Binary file build/.doctrees/experts.doctree has changed +diff -r 85f290e474e2 build/.doctrees/faq.doctree +Binary file build/.doctrees/faq.doctree has changed +diff -r 85f290e474e2 build/.doctrees/fixingissues.doctree +Binary file build/.doctrees/fixingissues.doctree has changed +diff -r 85f290e474e2 build/.doctrees/gdb.doctree +Binary file build/.doctrees/gdb.doctree has changed +diff -r 85f290e474e2 build/.doctrees/grammar.doctree +Binary file build/.doctrees/grammar.doctree has changed +diff -r 85f290e474e2 build/.doctrees/help.doctree +Binary file build/.doctrees/help.doctree has changed +diff -r 85f290e474e2 build/.doctrees/index.doctree +Binary file build/.doctrees/index.doctree has changed +diff -r 85f290e474e2 build/.doctrees/langchanges.doctree +Binary file build/.doctrees/langchanges.doctree has changed +diff -r 85f290e474e2 build/.doctrees/patch.doctree +Binary file build/.doctrees/patch.doctree has changed +diff -r 85f290e474e2 build/.doctrees/runtests.doctree +Binary file build/.doctrees/runtests.doctree has changed +diff -r 85f290e474e2 build/.doctrees/setup.doctree +Binary file build/.doctrees/setup.doctree has changed +diff -r 85f290e474e2 build/.doctrees/setupWindows.doctree +Binary file build/.doctrees/setupWindows.doctree has changed +diff -r 85f290e474e2 build/.doctrees/silencewarnings.doctree +Binary file build/.doctrees/silencewarnings.doctree has changed +diff -r 85f290e474e2 build/.doctrees/stdlibchanges.doctree +Binary file build/.doctrees/stdlibchanges.doctree has changed +diff -r 85f290e474e2 build/.doctrees/tracker.doctree +Binary file build/.doctrees/tracker.doctree has changed +diff -r 85f290e474e2 build/.doctrees/triaging.doctree +Binary file build/.doctrees/triaging.doctree has changed +diff -r 85f290e474e2 build/_sources/buildbots.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/buildbots.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,208 @@ ++.. _buildbots: ++ ++Continuous Integration ++====================== ++ ++To assert that there are no regressions in the :doc:`development and maintenance ++branches `, Python has a set of dedicated machines (called *buildbots* or ++*build slaves*) used for continuous integration. They span a number of ++hardware/operating system combinations. Furthermore, each machine hosts ++several *builders*, one per active branch: when a new change is pushed ++to this branch on the public Mercurial repository, all corresponding builders ++will schedule a new build to be run as soon as possible. ++ ++The build steps run by the buildbots are the following: ++ ++* Checkout of the source tree for the changeset which triggered the build ++* Compiling Python ++* Running the test suite using :ref:`strenuous settings ` ++* Cleaning up the build tree ++ ++It is your responsibility, as a core developer, to check the automatic ++build results after you push a change to the repository. It is therefore ++important that you get acquainted with the way these results are presented, ++and how various kinds of failures can be explained and diagnosed. ++ ++Checking results of automatic builds ++------------------------------------ ++ ++There are two ways of visualizing recent build results: ++ ++* The Web interface for each branch at http://python.org/dev/buildbot/, ++ where the so-called "waterfall" view presents a vertical rundown of recent ++ builds for each builder. When interested in one build, you'll have to ++ click on it to know which changesets it corresponds to. ++ ++* The command-line ``bbreport.py`` client, which you can get from ++ http://code.google.com/p/bbreport/. Installing it is trivial: just add ++ the directory containing ``bbreport.py`` to your system path so that ++ you can run it from any filesystem location. For example, if you want ++ to display the latest build results on the development ("default") branch, ++ type:: ++ ++ bbreport.py -q 3.x ++ ++Some buildbots are much faster than others. Over time, you will learn which ++ones produce the quickest results after a build, and which ones take the ++longest time. ++ ++Also, when several changesets are pushed in a quick succession in the same ++branch, it often happens that a single build is scheduled for all these ++changesets. ++ ++Stability ++--------- ++ ++A subset of the buildbots are marked "stable". They are taken into account ++when making a new release. The rule is that all stable builders must be free of ++persistent failures when the release is cut. It is absolutely **vital** ++that core developers fix any issue they introduce on the stable buildbots, ++as soon as possible. ++ ++This does not mean that other builders' test results can be taken lightly, ++either. Some of them are known for having platform-specific issues that ++prevent some tests from succeeding (or even terminating at all), but ++introducing additional failures should generally not be an option. ++ ++Flags-dependent failures ++------------------------ ++ ++Sometimes, while you have run the :doc:`whole test suite ` before ++committing, you may witness unexpected failures on the buildbots. One source ++of such discrepancies is if different flags have been passed to the test runner ++or to Python itself. To reproduce, make sure you use the same flags as the ++buildbots: they can be found out simply by clicking the **stdio** link for ++the failing build's tests. For example:: ++ ++ ./python.exe -Wd -E -bb ./Lib/test/regrtest.py -uall -rwW ++ ++.. note:: ++ Running ``Lib/test/regrtest.py`` is exactly equivalent to running ++ ``-m test``. ++ ++Ordering-dependent failures ++--------------------------- ++ ++Sometimes even the failure is subtler, as it relies on the order in which ++the tests are run. The buildbots *randomize* test order (by using the ``-r`` ++option to the test runner) to maximize the probability that potential ++interferences between library modules are exercised; the downside is that it ++can make for seemingly sporadic failures. ++ ++The ``--randseed`` option makes it easy to reproduce the exact randomization ++used in a given build. Again, open the ``stdio`` link for the failing test ++run, and check the beginning of the test output proper. ++ ++Let's assume, for the sake of example, that the output starts with:: ++ ++ ./python -Wd -E -bb Lib/test/regrtest.py -uall -rwW ++ == CPython 3.3a0 (default:22ae2b002865, Mar 30 2011, 13:58:40) [GCC 4.4.5] ++ == Linux-2.6.36-gentoo-r5-x86_64-AMD_Athlon-tm-_64_X2_Dual_Core_Processor_4400+-with-gentoo-1.12.14 little-endian ++ == /home/buildbot/buildarea/3.x.ochtman-gentoo-amd64/build/build/test_python_29628 ++ Testing with flags: sys.flags(debug=0, inspect=0, interactive=0, optimize=0, dont_write_bytecode=0, no_user_site=0, no_site=0, ignore_environment=1, verbose=0, bytes_warning=2, quiet=0) ++ Using random seed 2613169 ++ [ 1/353] test_augassign ++ [ 2/353] test_functools ++ ++You can reproduce the exact same order using:: ++ ++ ./python -Wd -E -bb -m test -uall -rwW --randseed 2613169 ++ ++It will run the following sequence (trimmed for brevity):: ++ ++ [ 1/353] test_augassign ++ [ 2/353] test_functools ++ [ 3/353] test_bool ++ [ 4/353] test_contains ++ [ 5/353] test_compileall ++ [ 6/353] test_unicode ++ ++If this is enough to reproduce the failure on your setup, you can then ++bisect the test sequence to look for the specific interference causing the ++failure. Copy and paste the test sequence in a text file, then use the ++``--fromfile`` (or ``-f``) option of the test runner to run the exact ++sequence recorded in that text file:: ++ ++ ./python -Wd -E -bb -m test -uall -rwW --fromfile mytestsequence.txt ++ ++In the example sequence above, if ``test_unicode`` had failed, you would ++first test the following sequence:: ++ ++ [ 1/353] test_augassign ++ [ 2/353] test_functools ++ [ 3/353] test_bool ++ [ 6/353] test_unicode ++ ++And, if it succeeds, the following one instead (which, hopefully, shall ++fail):: ++ ++ [ 4/353] test_contains ++ [ 5/353] test_compileall ++ [ 6/353] test_unicode ++ ++Then, recursively, narrow down the search until you get a single pair of ++tests which triggers the failure. It is very rare that such an interference ++involves more than **two** tests. If this is the case, we can only wish you ++good luck! ++ ++.. note:: ++ You cannot use the ``-j`` option (for parallel testing) when diagnosing ++ ordering-dependent failures. Using ``-j`` isolates each test in a ++ pristine subprocess and, therefore, prevents you from reproducing any ++ interference between tests. ++ ++ ++Transient failures ++------------------ ++ ++While we try to make the test suite as reliable as possible, some tests do ++not reach a perfect level of reproducibility. Some of them will sometimes ++display spurious failures, depending on various conditions. Here are common ++offenders: ++ ++* Network-related tests, such as ``test_poplib``, ``test_urllibnet``, etc. ++ Their failures can stem from adverse network conditions, or imperfect ++ thread synchronization in the test code, which often has to run a ++ server in a separate thread. ++ ++* Tests dealing with delicate issues such as inter-thread or inter-process ++ synchronization, or Unix signals: ``test_multiprocessing``, ++ ``test_threading``, ``test_subprocess``, ``test_threadsignals``. ++ ++When you think a failure might be transient, it is recommended you confirm by ++waiting for the next build. Still, even if the failure does turn out sporadic ++and unpredictable, the issue should be reported on the bug tracker; even ++better if it can be diagnosed and suppressed by fixing the test's implementation, ++or by making its parameters - such as a timeout - more robust. ++ ++ ++Custom builders ++--------------- ++ ++When working on a long-lived feature branch, or on a bugfix branch which ++enables issue-specific debugging, you will probably want to test your ++work on one or several buildbots. Since your work is hosted in a distinct ++repository, you can't trigger builds on the regular builders. Instead, ++you have to use one of the `custom builders ++`_. ++ ++When creating ("forcing") a build on a custom builder, you have to provide ++at least two parameters: ++ ++* The repository path, relative to http://hg.python.org. For example, ++ ``sandbox/myfixes`` if ``http://hg.python.org/sandbox/myfixes`` is the ++ full path to the repository. ++ ++* The Mercurial id of the changeset you want to build. To make things less ++ tedious, we suggest you do your changes in a separate named branch: you can ++ then supply the branch name instead of a specific changeset id. ++ ++If you are interested in the results of a specific test file only, we ++recommend you change (temporarily, of course) the contents of the ++``buildbottest`` clause in ``Makefile.pre.in``; or, for Windows builders, ++the ``Tools/buildbot/test.bat`` and ``Tools/buildbot/test-amd64.bat`` ++scripts. ++ ++.. note:: ++ For security reasons, it is impossible to build repositories from outside ++ the http://hg.python.org realm. +diff -r 85f290e474e2 build/_sources/clang.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/clang.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,338 @@ ++********************************** ++ Dynamic Analysis with Clang ++********************************** ++ ++This document describes how to use Clang to perform analysis on Python and its ++libraries. In addition to performing the analysis, the document will cover ++downloading, building and installing the the latest Clang/LLVM combination ++(which is currently 3.4). ++ ++This document does not cover interpreting the findings. For a discussion of ++interpreting results, see Marshall Clow's `Testing libc++ with ++-fsanitize=undefined `_. The ++blog posting is a detailed examinations of issues uncovered by Clang in ++``libc++``. ++ ++What is Clang? ++============== ++ ++Clang is the C, C++ and Objective C front-end for the LLVM compiler. The ++front-end provides access to LLVM's optimizer and code generator. The ++sanitizers - or checkers - are hooks into the code generation phase to ++instrument compiled code so suspicious behavior is flagged. ++ ++What are Sanitizers? ++==================== ++ ++Clang sanitizers are runtime checkers used to identify suspicious and undefined ++behavior. The checking occurs at runtime with actual runtime parameters so false ++positives are kept to a minimum. ++ ++There are a number of sanitizers available, but two that should be used on a ++regular basis are the Address Sanitizer (or ASan) and the Undefined Behavior ++Sanitizer (or UBSan). ASan is invoked with the compiler option ++``-fsanitize=address``, and UBSan is invoked with ``-fsanitize=undefined``. The ++flags are passed through ``CFLAGS`` and ``CXXFLAGS``, and sometimes through ++``CC`` and ``CXX`` (in addition to the compiler). ++ ++A complete list of sanitizers can be found at `Controlling Code Generation ++`_. ++ ++.. note:: ++ ++ Because sanitizers operate at runtime on real program parameters, its ++ important to provide a complete set of positive and negative self tests. ++ ++Clang and its sanitizers have strengths (and weaknesses). Its just one tool in ++the war chest to uncovering bugs and improving code quality. Clang should be ++used to compliment other methods, including Code Reviews, Valgrind, Coverity, ++etc. ++ ++Clang/LLVM Setup ++================ ++ ++This portion of the document covers downloading, building and installing Clang ++and LLVM. There are three components to download and build. They are the LLVM ++compiler, the compiler front end and the compiler runtime library. ++ ++In preparation you should create a scratch directory. Also ensure you are using ++Python 2 and not Python 3. Python 3 will cause the build to fail. ++ ++Download, Build and Install ++--------------------------- ++ ++Perform the following to download, build and install the Clang/LLVM 3.4. :: ++ ++ # Download ++ wget http://llvm.org/releases/3.4/llvm-3.4.src.tar.gz ++ wget http://llvm.org/releases/3.4/clang-3.4.src.tar.gz ++ wget http://llvm.org/releases/3.4/compiler-rt-3.4.src.tar.gz ++ ++ # LLVM ++ tar xvf llvm-3.4.src.tar.gz ++ cd llvm-3.4/tools ++ ++ # Clang Front End ++ tar xvf ../../clang-3.4.src.tar.gz ++ mv clang-3.4 clang ++ ++ # Compiler RT ++ cd ../projects ++ tar xvf ../../compiler-rt-3.4.src.tar.gz ++ mv compiler-rt-3.4/ compiler-rt ++ ++ # Build ++ cd .. ++ ./configure --enable-optimized --prefix=/usr/local ++ make -j4 ++ sudo make install ++ ++.. note:: ++ ++ If you receive an error ``'LibraryDependencies.inc' file not found``, then ++ ensure you are utilizing Python 2 and not Python 3. If you encounter the ++ error after switching to Python 2, then delete everything and start over. ++ ++After ``make install`` executes, the compilers will be installed in ++``/usr/local/bin`` and the various libraries will be installed in ++``/usr/local/lib/clang/3.4/lib/linux/``: :: ++ ++ $ ls /usr/local/lib/clang/3.4/lib/linux/ ++ libclang_rt.asan-x86_64.a libclang_rt.profile-x86_64.a ++ libclang_rt.dfsan-x86_64.a libclang_rt.san-x86_64.a ++ libclang_rt.full-x86_64.a libclang_rt.tsan-x86_64.a ++ libclang_rt.lsan-x86_64.a libclang_rt.ubsan_cxx-x86_64.a ++ libclang_rt.msan-x86_64.a libclang_rt.ubsan-x86_64.a ++ ++On Mac OS X, the libraries are installed in ++``/usr/local/lib/clang/3.3/lib/darwin/``: :: ++ ++ $ ls /usr/local/lib/clang/3.3/lib/darwin/ ++ libclang_rt.10.4.a libclang_rt.ios.a ++ libclang_rt.asan_osx.a libclang_rt.osx.a ++ libclang_rt.asan_osx_dynamic.dylib libclang_rt.profile_ios.a ++ libclang_rt.cc_kext.a libclang_rt.profile_osx.a ++ libclang_rt.cc_kext_ios5.a libclang_rt.ubsan_osx.a ++ libclang_rt.eprintf.a ++ ++.. note:: ++ ++ You should never have to add the libraries to a project. Clang will handle ++ it for you. If you find you cannot pass the ``-fsanitize=XXX`` flag through ++ ``make``'s implicit variables (``CFLAGS``, ``CXXFLAGS``, ``CC``, ++ ``CXXFLAGS``, ``LDFLAGS``) during ``configure``, then you should modify the ++ makefile after configuring to ensure the flag is passed through the ++ compiler. ++ ++The installer does not install all the components needed on occasion. For ++example, you might want to run a ``scan-build`` or examine the results with ++``scan-veiw``. You can copy the components by hand with: :: ++ ++ sudo mkdir /usr/local/bin/scan-build ++ sudo cp -r llvm-3.4/tools/clang/tools/scan-build /usr/local/bin ++ sudo mkdir /usr/local/bin/scan-view ++ sudo cp -r llvm-3.4/tools/clang/tools/scan-view /usr/local/bin ++ ++.. note:: ++ ++ Because the installer does not install all the components needed on ++ occasion, you should not delete the scratch directory until you are sure ++ things work as expected. If a library is missing, then you should search for ++ it in the Clang/LLVM build directory. ++ ++Python Build Setup ++================== ++ ++This portion of the document covers invoking Clang and LLVM with the options ++required so the sanitizers analyze Python with under its test suite. Two ++checkers are used - ASan and UBSan. ++ ++Because the sanitizers are runtime checkers, its best to have as many positive ++and negative self tests as possible. You can never have enough self tests. ++ ++The general idea is to compile and link with the sanitizer flags. At link time, ++Clang will include the needed runtime libraries. However, you can't use ++``CFLAGS`` and ``CXXFLAGS`` to pass the options through the compiler to the ++linker because the makefile rules for ``BUILDPYTHON``, ``_testembed`` and ++``_freeze_importlib`` don't use the implicit variables. ++ ++As a workaround to the absence of flags to the linker, you can pass the ++sanitizer options by way of the compilers - ``CC`` and ``CXX``. Passing the ++flags though the compiler is used below, but passing them through ``LDFLAGS`` is ++also reported to work. ++ ++Building Python ++--------------- ++ ++To begin, export the variables of interest with the desired sanitizers. Its OK ++to specify both sanitizers: :: ++ ++ # ASan ++ export CC="/usr/local/bin/clang -fsanitize=address" ++ export CXX="/usr/local/bin/clang++ -fsanitize=address -fno-sanitize=vptr" ++ ++Or: :: ++ ++ # UBSan ++ export CC="/usr/local/bin/clang -fsanitize=undefined" ++ export CXX="/usr/local/bin/clang++ -fsanitize=undefined -fno-sanitize=vptr" ++ ++The ``-fno-sanitize=vptr`` removes vtable checks that are part of UBSan from C++ ++projects due to noise. Its not needed with Python, but you will likely need it ++for other C++ projects. ++ ++After exporting ``CC`` and ``CXX``, ``configure`` as normal: :: ++ ++ $ ./configure ++ checking build system type... x86_64-unknown-linux-gnu ++ checking host system type... x86_64-unknown-linux-gnu ++ checking for --enable-universalsdk... no ++ checking for --with-universal-archs... 32-bit ++ checking MACHDEP... linux ++ checking for --without-gcc... no ++ checking for gcc... /usr/local/bin/clang -fsanitize=undefined ++ checking whether the C compiler works... yes ++ ... ++ ++Next is a standard ``make`` (formatting added for clarity): :: ++ ++ $ make ++ /usr/local/bin/clang -fsanitize=undefined -c -Wno-unused-result ++ -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes -I. ++ -IInclude -I./Include -DPy_BUILD_CORE -o Modules/python.o ++ ./Modules/python.c ++ /usr/local/bin/clang -fsanitize=undefined -c -Wno-unused-result ++ -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes -I. ++ -IInclude -I./Include -DPy_BUILD_CORE -o Parser/acceler.o ++ Parser/acceler.c ++ ... ++ ++Finally is ``make test`` (formatting added for clarity): :: ++ ++ Objects/longobject.c:39:42: runtime error: index -1 out of bounds ++ for type 'PyLongObject [262]' ++ Objects/tupleobject.c:188:13: runtime error: member access within ++ misaligned address 0x2b76be018078 for type 'PyGC_Head' (aka ++ 'union _gc_head'), which requires 16 byte alignment ++ 0x2b76be018078: note: pointer points here ++ 00 00 00 00 40 53 5a b6 76 2b 00 00 60 52 5a b6 ... ++ ^ ++ ... ++ ++If you are using the address sanitizer, its important to pipe the output through ++``asan_symbolize.py`` to get a good trace. For example, from Issue 20953 during ++compile (formatting added for clarity): :: ++ ++ $ make test 2>&1 | asan_symbolize.py ++ ... ++ ++ /usr/local/bin/clang -fsanitize=address -Xlinker -export-dynamic ++ -o python Modules/python.o libpython3.3m.a -ldl -lutil ++ /usr/local/ssl/lib/libssl.a /usr/local/ssl/lib/libcrypto.a -lm ++ ./python -E -S -m sysconfig --generate-posix-vars ++ ================================================================= ++ ==24064==ERROR: AddressSanitizer: heap-buffer-overflow on address ++ 0x619000004020 at pc 0x4ed4b2 bp 0x7fff80fff010 sp 0x7fff80fff008 ++ READ of size 4 at 0x619000004020 thread T0 ++ #0 0x4ed4b1 in PyObject_Free Python-3.3.5/./Objects/obmalloc.c:987 ++ #1 0x7a2141 in code_dealloc Python-3.3.5/./Objects/codeobject.c:359 ++ #2 0x620c00 in PyImport_ImportFrozenModuleObject ++ Python-3.3.5/./Python/import.c:1098 ++ #3 0x620d5c in PyImport_ImportFrozenModule ++ Python-3.3.5/./Python/import.c:1114 ++ #4 0x63fd07 in import_init Python-3.3.5/./Python/pythonrun.c:206 ++ #5 0x63f636 in _Py_InitializeEx_Private ++ Python-3.3.5/./Python/pythonrun.c:369 ++ #6 0x681d77 in Py_Main Python-3.3.5/./Modules/main.c:648 ++ #7 0x4e6894 in main Python-3.3.5/././Modules/python.c:62 ++ #8 0x2abf9a525eac in __libc_start_main ++ /home/aurel32/eglibc/eglibc-2.13/csu/libc-start.c:244 ++ #9 0x4e664c in _start (Python-3.3.5/./python+0x4e664c) ++ ++ AddressSanitizer can not describe address in more detail (wild ++ memory access suspected). ++ SUMMARY: AddressSanitizer: heap-buffer-overflow ++ Python-3.3.5/./Objects/obmalloc.c:987 PyObject_Free ++ Shadow bytes around the buggy address: ++ 0x0c327fff87b0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa ++ 0x0c327fff87c0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa ++ 0x0c327fff87d0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa ++ 0x0c327fff87e0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa ++ 0x0c327fff87f0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa ++ =>0x0c327fff8800: fa fa fa fa[fa]fa fa fa fa fa fa fa fa fa fa fa ++ 0x0c327fff8810: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa ++ 0x0c327fff8820: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa ++ 0x0c327fff8830: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa ++ 0x0c327fff8840: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa ++ 0x0c327fff8850: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa ++ Shadow byte legend (one shadow byte represents 8 application bytes): ++ Addressable: 00 ++ Partially addressable: 01 02 03 04 05 06 07 ++ Heap left redzone: fa ++ Heap right redzone: fb ++ Freed heap region: fd ++ Stack left redzone: f1 ++ Stack mid redzone: f2 ++ Stack right redzone: f3 ++ Stack partial redzone: f4 ++ Stack after return: f5 ++ Stack use after scope: f8 ++ Global redzone: f9 ++ Global init order: f6 ++ Poisoned by user: f7 ++ ASan internal: fe ++ ==24064==ABORTING ++ make: *** [pybuilddir.txt] Error 1 ++ ++.. note:: ++ ++ ``asan_symbolize.py`` is supposed to be installed during ``make install``. ++ If its not installed, then look in the Clang/LLVM build directory for it and ++ copy it to ``/usr/local/bin``. ++ ++Blacklisting (Ignoring) Findings ++-------------------------------- ++ ++Clang allows you to alter the behavior of sanitizer tools for certain ++source-level by providing a special blacklist file at compile-time. The ++blacklist is needed because it reports every instance of an issue, even if the ++issue is reported 10's of thousands of time in un-managed library code. ++ ++You specify the blacklist with ``-fsanitize-blacklist=XXX``. For example: :: ++ ++ -fsanitize-blacklist=my_blacklist.txt ++ ++``my_blacklist.txt`` would then contain entries such as the following. The entry ++will ignore a bug in ``libc++``'s ``ios`` formatting functions: :: ++ ++ fun:_Ios_Fmtflags ++ ++As an example with Python 3.4.0, ``audioop.c`` will produce a number of ++findings: :: ++ ++ ./Modules/audioop.c:422:11: runtime error: left shift of negative value -1 ++ ./Modules/audioop.c:446:19: runtime error: left shift of negative value -1 ++ ./Modules/audioop.c:476:19: runtime error: left shift of negative value -1 ++ ./Modules/audioop.c:504:16: runtime error: left shift of negative value -1 ++ ./Modules/audioop.c:533:22: runtime error: left shift of negative value -128 ++ ./Modules/audioop.c:775:19: runtime error: left shift of negative value -70 ++ ./Modules/audioop.c:831:19: runtime error: left shift of negative value -70 ++ ./Modules/audioop.c:881:19: runtime error: left shift of negative value -1 ++ ./Modules/audioop.c:920:22: runtime error: left shift of negative value -70 ++ ./Modules/audioop.c:967:23: runtime error: left shift of negative value -70 ++ ./Modules/audioop.c:968:23: runtime error: left shift of negative value -70 ++ ... ++ ++One of the function of interest is ``audioop_getsample_impl`` (flagged at line ++422), and the blacklist entry would include: :: ++ ++ fun:audioop_getsample_imp ++ ++Or, you could ignore the entire file with: :: ++ ++ src:Modules/audioop.c ++ ++Unfortunately, you won't know what to blacklist until you run the sanitizer. ++ ++The documentation is available at `Sanitizer special case list ++`_. +diff -r 85f290e474e2 build/_sources/committing.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/committing.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,577 @@ ++.. _committing: ++ ++Committing and Pushing Changes ++============================== ++ ++Is the change ready for committing? ++----------------------------------- ++ ++Before a change is committed, you must make sure it is ready to enter the ++public source tree. Draft commits are prohibited. Therefore, you must ++ensure your changes fulfill several mandatory criteria. ++ ++.. note:: ++ If you want to share your work-in-progress code on a feature or bugfix, ++ either publish patches or create a public fork of the repository. ++ ++ ++Does the test suite still pass? ++''''''''''''''''''''''''''''''' ++ ++You must :ref:`run the whole test suite ` to ensure that it ++passes before pushing any code changes. ++ ++.. note:: ++ You really need to run the **entire** test suite. Running a single test ++ is not enough as your changes may have unforeseen effects on other tests ++ or library modules. ++ ++ Running the entire test suite doesn't guarantee that your changes ++ will pass the :ref:`continuous integration ` tests, as those ++ will exercise more possibilities still (such as different platforms or ++ build options). But it will at least catch non-build specific, ++ non-platform specific errors, therefore minimizing the chance for ++ breakage. ++ ++Patch checklist ++''''''''''''''' ++ ++Apart from running the tests, there's a simple patch checklist that ++``make patchcheck`` (or ``./python.exe Tools/scripts/patchcheck.py`` on ++Windows) will run through: ++ ++* Are there any whitespace problems in Python files? ++ (using ``Tools/scripts/reindent.py``) ++* Are there any whitespace problems in C files? ++* Are there any whitespace problems in the documentation? ++ (using ``Tools/scripts/reindent-rst.py``) ++* Has the documentation been updated? ++* Has the test suite been updated? ++* Has ``Misc/NEWS`` been updated? ++* Has ``Misc/ACKS`` been updated? ++* Has ``configure`` been regenerated, if necessary? ++* Has ``pyconfig.h.in`` been regenerated, if necessary? ++ ++Note that the automated patch check can't actually *answer* all of these ++questions, and even if it could, it still wouldn't know whether or not ++those answers were appropriate. Aside from the whitespace checks, it is just ++a memory aid to help with remembering the various elements that can go into ++making a complete patch. ++ ++ ++Commit Style ++------------ ++ ++Once a change patch is ready and tested, it can be committed to the repository. ++We usually prefer to put a whole feature or bugfix into a single commit, but no ++more. In particular: ++ ++* Do **not** fix more than one issue in the same commit (except, of course, if ++ one code change fixes all of them). ++* Do **not** do cosmetic changes to unrelated code in the same commit as some ++ feature/bugfix. ++ ++It is of course okay to pile up several commits to one branch and merge them ++into another in one merge commit. ++ ++ ++Handling Others' Code ++--------------------- ++ ++As a core developer you will occasionally want to commit a patch created by ++someone else. When doing so you will want to make sure of some things. ++ ++First, make sure the patch is in a good state. Both :ref:`patch` and ++:ref:`helptriage` ++explain what is to be expected of a patch. Typically patches that get cleared by ++triagers are good to go except maybe lacking ``Misc/ACKS`` and ``Misc/NEWS`` ++entries. ++ ++Second, make sure the patch does not break backwards-compatibility without a ++good reason. This means :ref:`running the entire test suite ` to ++make sure everything still passes. It also means that if semantics do change ++there must be a good reason for the breakage of code the change will cause ++(and it **will** break someone's code). If you are unsure if the breakage ++is worth it, ask on python-dev. ++ ++Third, ensure the patch is attributed correctly by adding the contributor's ++name to ``Misc/ACKS`` if they aren't already there (and didn't add themselves ++in their patch) and by mentioning "Patch by " in the ``Misc/NEWS`` entry ++and the checkin message. If the patch has been heavily modified then "Initial ++patch by " is an appropriate alternate wording. ++ ++If you omit correct attribution in the initial checkin, then update ``ACKS`` ++and ``NEWS`` in a subsequent checkin (don't worry about trying to fix the ++original checkin message in that case). ++ ++Finally, especially for larger patches, check if the submitter of the ++patch has a CLA in place (indicated by an asterisk following their username ++in the issue tracker). If the asterisk is missing and the patch is ++non-trivial, direct them to the electronic `Contributor Licensing Agreement`_ ++to ensure the PSF has the appropriate authorizations in place to relicense ++and redistribute their code. ++ ++ ++Contributor Licensing Agreements ++-------------------------------- ++ ++It's unlikely bug fixes will require a `Contributor Licensing Agreement`_ ++unless they touch a *lot* of code. For new features, it is preferable to ++ask that the contributor submit a signed CLA to the PSF as the associated ++comments, docstrings and documentation are far more likely to reach a ++copyrightable standard. ++ ++These days, the CLA can be signed electronically through the form linked ++above, and this process is strongly preferred to the old mechanism that ++involved sending a scanned copy of the signed paper form. ++ ++As discussed on the PSF Contribution_ page, it is the CLA itself that gives ++the PSF the necessary relicensing rights to redistribute contributions under ++the Python license stack. This is an additional permission granted above and ++beyond the normal permissions provided by the chosen open source license. ++ ++Some developers may object to the relicensing permissions granted to the PSF ++by the CLA. They're entirely within their rights to refuse to sign the CLA ++on that basis, but that refusal *does* mean we can't accept their patches ++for inclusion. ++ ++.. _Contribution: http://www.python.org/psf/contrib/ ++.. _Contributor Licensing Agreement: ++ http://www.python.org/psf/contrib/contrib-form/ ++ ++ ++NEWS Entries ++------------ ++ ++Almost all changes made to the code base deserve an entry in ``Misc/NEWS``. ++If the change is particularly interesting for end users (e.g. new features, ++significant improvements, or backwards-incompatible changes), an entry in ++the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added ++as well. There are two notable exceptions to this general principle, and they ++both relate to changes that *already* have a NEWS entry, and have not yet ++been included in any formal release (including alpha and beta releases). ++These exceptions are: ++ ++* If a change is reverted prior to release, then the corresponding entry ++ is simply removed. Otherwise, a new entry must be added noting that the ++ change has been reverted (e.g. when a feature is released in an alpha and ++ then cut prior to the first beta). ++ ++* If a change is a fix (or other adjustment) to an earlier unreleased change ++ and the original NEWS entry remains valid, then no additional entry is ++ needed. ++ ++New NEWS entries are customarily added at or near the top of their ++respective sections, so that entries within a section appear in approximate ++order from newest to oldest. However, this is customary and not a ++requirement. ++ ++The NEWS file is now read by Sphinx to produce the "Changelog" page; accordingly ++it should be valid reStructuredText. The "default role" (single backticks) can ++be used to refer to objects in the documentation. Example NEWS entry:: ++ ++ - Issue #15304: Fix warning message when `os.chdir()` fails inside ++ `test.support.temp_cwd()`. Patch by Chris Jerdonek. ++ ++(In all other ``.rst`` files, the single backticks should not be used. They are ++allowed here because NEWS is meant to be as readable as possible unprocessed.) ++ ++A nice trick to make Mercurial’s automatic file merge work more smoothly is to ++put a new entry after the first or first two entries rather than at the very ++top. This way if you commit, pull new changesets and merge, the merge will ++succeed automatically. ++ ++ ++Commit Messages ++--------------- ++ ++Every commit has a commit message to document why a change was made and to ++communicate that reason to other core developers. Python core developers have ++developed a standard way of formatting commit messages that everyone is ++expected to follow. ++ ++Our usual convention mimics that used in the ``Misc/NEWS`` file. Actually, ++it is common to simply paste the NEWS entry into the commit message. Here ++is an example:: ++ ++ Issue #42: the spam module is now more spammy. ++ The spam module sporadically came up short on spam. This change ++ raises the amount of spam in the module by making it more spammy. ++ Thanks to Monty Python for the patch. ++ ++The first line or sentence is meant to be a dense, to-the-point explanation ++of what the purpose of the commit is. If this is not enough detail for a commit, ++a new paragraph(s) can be added to explain in proper depth what has happened ++(detail should be good enough that a core developer reading the commit message ++understands the justification for the change). Also, if a non-core developer ++contributed to the resolution, it is good practice to credit them. ++ ++Mercurial hooks ++''''''''''''''' ++ ++Special hooks have been added to the Mercurial repository to enable notifying ++the issue tracker of a commit related to an issue. ++ ++A commit message can mention one or several issues in one of the following ++ways:: ++ ++ #12345 ++ issue12345 ++ issue 12345 ++ bug12345 ++ bug 12345 ++ ++where 12345 is the number of the issue. The commit details (including its ++changeset, branch and commit message) will then be posted as a message to the ++issue's page in the tracker, for each mentioned issue. ++ ++If "closes" (or "closed", or "closing") is prepended, the issue is ++automatically closed as "fixed". ++ ++Working with Mercurial_ ++======================= ++ ++As a core developer, the ability to push changes to the official Python ++repositories means you have to be more careful with your workflow: ++ ++* You should not push new named branches to the main repository. You can ++ still use them in clones that you use for development of patches; you can ++ also push these branches to a **separate** public repository that will be ++ dedicated to maintenance of the work before the work gets integrated in the ++ main repository. ++ ++* You should collapse changesets of a single feature or bugfix before pushing ++ the result to the main repository. The reason is that we don't want the ++ history to be full of intermediate commits recording the private history ++ of the person working on a patch. If you are using the rebase_ extension, ++ consider adding the ``--collapse`` option to ``hg rebase``. The collapse_ ++ extension is another choice. ++ ++Because of these constraints, it can be practical to use other approaches ++such as mq_ (Mercurial Queues), in order to maintain patches in a single ++local repository and to push them seamlessly when they are ready. ++ ++It can also be useful to keep a pristine clone of the main repository around, ++as it allows simple reversion of all local changes (even "committed" ones) if ++your local clone gets into a state you aren't happy with. ++ ++ ++.. _Mercurial: http://www.hg-scm.org/ ++.. _mq: http://mercurial.selenic.com/wiki/MqExtension ++.. _rebase: http://mercurial.selenic.com/wiki/RebaseExtension ++.. _collapse: http://mercurial.selenic.com/wiki/CollapseExtension ++ ++ ++Minimal Configuration ++--------------------- ++ ++To use Mercurial as a committer (both of your and others' patches), you should ++set up some basic options in your `configuration file`_. Under Windows, ++TortoiseHg has a graphical settings dialog for most options, meaning you ++don't need to edit the file directly (it is still available in ++``%USERPROFILE%\Mercurial.ini``). Under other platforms, you must edit ++``~/.hgrc``. ++ ++Here are the minimal options you need to activate: ++ ++* your *username*: this setting defines the name that will be used when you ++ :ref:`commit ` changes. The usual convention is to also include ++ an e-mail contact address in there:: ++ ++ [ui] ++ username = Your Name ++ ++* *extended diffing*: this setting enables an `extended diff format`_ ++ which is more useful than the standard unified diff format as it includes ++ metadata about file copies, permission bits, and is able to represent ++ binary files:: ++ ++ [diff] ++ git = on ++ ++Under Windows, you should also enable the `eol extension`_, which will ++fix any Windows-specific line endings your text editor might insert when you ++create or modify versioned files. The public repository has a hook which ++will reject all changesets having the wrong line endings, so enabling this ++extension on your local computer is in your best interest. ++ ++ ++.. _configuration file: http://www.selenic.com/mercurial/hgrc.5.html#files ++.. _extended diff format: http://www.selenic.com/mercurial/hg.1.html#diffs ++.. _eol extension: http://mercurial.selenic.com/wiki/EolExtension ++ ++ ++Clones Setup ++------------ ++ ++There are several possible ways to set up your Mercurial clone(s). If you are ++a core developer, you often need to work on the different branches, so the best ++approach is to have a separate clone/directory for each active branch. If you ++are a contributor, having a single clone might be enough. ++ ++Single Clone Approach ++''''''''''''''''''''' ++ ++This approach has the advantage of being simpler because it requires a single ++clone/directory, but, on the other hand, it requires you to recompile Python ++every time you need to switch branch. For this reason, this approach is not ++suggested to core developers, but it's usually suitable for contributors. ++ ++See :ref:`checkout` to find information about cloning and switching branches. ++ ++.. _multiple-clones: ++ ++Multiple Clones Approach ++'''''''''''''''''''''''' ++ ++This approach requires you to keep a separate clone/directory for each active ++branch, but, on the other hand, it doesn't require you to switch branches and ++recompile Python, so it saves times while merging and testing a patch on the ++different branches. For this reason, this approach is suggested to core ++developers. ++ ++The easiest way to do this is by using the `share extension`_, that can be ++enabled by adding the following lines to your ``~/.hgrc``:: ++ ++ [extensions] ++ share = ++ ++Once you have :ref:`cloned the hg.python.org/cpython repository ` ++you can create the other shared clones using:: ++ ++ $ hg share cpython 2.7 # create a new shared clone ++ $ cd 2.7 # enter the directory ++ $ hg up 2.7 # switch to the 2.7 branch ++ ++You can then repeat the same operation for the other active branches. ++This will create different clones/directories that share the same history. ++This means that once you commit or pull new changesets in one of the clones, ++they will be immediately available in all the other clones (note however that ++while you only need to use ``hg pull`` once, you still need to use ``hg up`` ++in each clone to update its working copy). ++ ++If you don't want to specify ssh://hg@hg.python.org/cpython every time you pull ++or push, you should add to the ``.hg/hgrc`` files of the clones:: ++ ++ [paths] ++ default = ssh://hg@hg.python.org/cpython ++ ++In order to apply a patch, commit, and merge it on all the branches, you can do ++as follow:: ++ ++ $ cd 2.7 ++ $ hg pull ++ $ hg up ++ $ hg import --no-c http://bugs.python.org/url/to/the/patch.diff ++ $ # review, run tests, run `make patchcheck` ++ $ hg ci -m '#12345: fix some issue.' ++ $ # switch to 3.4 and port the changeset using `hg graft` ++ $ cd ../3.4 ++ $ hg up ++ $ hg graft 2.7 ++ $ # switch to 3.x, merge, commit, and push everything ++ $ cd ../3.x ++ $ hg up ++ $ hg merge 3.4 ++ $ hg ci -m '#12345: merge with 3.4.' ++ $ hg push ++ ++Unless noted otherwise, the rest of the page will assume you are using the ++multiple clone approach, and explain in more detail these basic steps. ++ ++For more advanced explanations about :ref:`null merges `, ++:ref:`heads merges `, :ref:`merge conflicts ++`, etc., see the :ref:`FAQs for core developers ++`. ++ ++.. _share extension: http://mercurial.selenic.com/wiki/ShareExtension ++ ++ ++Active branches ++--------------- ++ ++If you do ``hg branches`` you will see a :ref:`list of branches `. ++``default`` is the in-development branch, and is the only branch that receives ++new features. The other branches only receive bug fixes or security fixes. ++Depending on what you are committing (feature, bug fix, or security fix), you ++should commit to the oldest branch applicable, and then forward-port until the ++in-development branch. ++ ++ ++Merging order ++------------- ++ ++There are two separate lines of development: one for Python 2 (the ``2.x`` ++branches) and one for Python 3 (the ``3.x`` branches and ``default``). ++You should *never* merge between the two major versions (2.x and 3.x) --- ++only between minor versions (e.g. 3.x->3.y). The merge always happens from ++the oldest applicable branch to the newest branch within the same major ++Python version. ++ ++ ++.. _branch-merge: ++ ++Merging between different branches (within the same major version) ++------------------------------------------------------------------ ++ ++Assume that Python 3.5 is the current in-development version of Python and that ++you have a patch that should also be applied to Python 3.4. To properly port ++the patch to both versions of Python, you should first apply the patch to ++Python 3.4:: ++ ++ cd 3.4 ++ hg import --no-commit patch.diff ++ # Compile; run the test suite ++ hg ci -m '#12345: fix some issue.' ++ ++Then you can switch to the ``3.5`` clone, merge, run the tests and commit:: ++ ++ cd ../3.5 ++ hg merge 3.4 ++ # Fix any conflicts (e.g. ``hg revert -r default Misc/NEWS``); compile; run the test suite ++ hg ci -m '#12345: merge with 3.4.' ++ ++If you are not using the share extension, you will need to use ++``hg pull ../3.4`` before being able to merge. ++ ++.. note:: ++ Even when porting an already committed patch, you should *still* check the ++ test suite runs successfully before committing the patch to another branch. ++ Subtle differences between two branches sometimes make a patch bogus if ++ ported without any modifications. ++ ++ ++Porting changesets between the two major Python versions (2.x and 3.x) ++---------------------------------------------------------------------- ++ ++Assume you just committed something on ``2.7``, and want to port it to ``3.4``. ++You can use ``hg graft`` as follow:: ++ ++ cd ../3.4 ++ hg graft 2.7 ++ ++This will port the latest changeset committed in the 2.7 clone to the 3.4 clone. ++``hg graft`` always commits automatically, except in case of conflicts, when ++you have to resolve them and run ``hg graft --continue`` afterwards. ++Instead of the branch name you can also specify a changeset id, and you can ++also graft changesets from 3.x to 2.7. ++ ++On older version of Mercurial where ``hg graft`` is not available, you can use:: ++ ++ cd ../3.4 ++ hg export 2.7 | hg import - ++ ++The result will be the same, but in case of conflict this will create ``.rej`` ++files rather than using Mercurial merge capabilities. ++ ++A third option is to apply manually the patch on ``3.4``. This is convenient ++when there are too many differences with ``2.7`` or when there is already a ++specific patch for ``3.4``. ++ ++.. warning:: ++ Never use ``hg merge`` to port changes between 2.x and 3.x (or vice versa). ++ ++ ++Long-term development of features ++--------------------------------- ++ ++If you want to work on a feature long-term (perhaps you're implementing a ++PEP), you will probably want to publish your work in a dedicated repository. ++The following instructions will help you do so on `hg.python.org ++`_'s infrastructure without requiring a lot of upload ++bandwidth. ++ ++Go to the main repository's Web page (http://hg.python.org/cpython/); there ++you find a button labelled "server-side clone", which you can click on to ++display a Web form. Enter the relative path of the repository you want to ++create on the server, for example ``features/mywork``; and press the button. ++A new repository gets created on the server with all the changesets of the ++original repository (it will seem very fast; this is normal). ++ ++You can now do a local clone of this repository on your disk:: ++ ++ $ hg clone ssh://hg@hg.python.org/features/mywork ++ $ cd mywork ++ ++.. commented out: old instructions (without server-side cloning) ++ ++ First create a public (empty) repository on hg.python.org:: ++ ++ $ hg init ssh://hg@hg.python.org/features/mywork ++ ++ And do a local clone of that repository on your disk:: ++ ++ $ hg clone ssh://hg@hg.python.org/features/mywork ++ $ cd mywork ++ ++ There, pull all the contents from the main repository, either from a local ++ clone:: ++ ++ $ hg pull ../cpython ++ $ hg update ++ ++ or directly from the network (which is of course slower):: ++ ++ $ hg pull http://hg.python.org/cpython ++ $ hg update ++ ++It is recommended that you create a new `named branch`_ for your work, so as ++to easily track changes. That named branch will exist in your feature ++repository, but not in the main repository:: ++ ++ $ hg branch mywork ++ $ hg commit -m "Creating branch mywork" ++ $ hg push --new-branch ++ ++You can now work on your feature, commit changes as you will, and push them ++when desired:: ++ ++ $ hg push ++ ++When you push them, they will land in the public repository at ++``ssh://hg@hg.python.org/features/mywork`` (or ++``http://hg.python.org/features/mywork`` for the read-only URL). Other ++people can clone the public repository and work on the code too. ++ ++When you want to synchronize with CPython's upstream changes, you can pull ++from the main repository, either from its remote URL:: ++ ++ $ hg pull http://hg.python.org/cpython ++ ++or from a local clone that you may have on your disk (which is of course ++faster):: ++ ++ $ hg pull ../cpython ++ ++and merge all new changes from branch ``default`` to branch ``mywork``:: ++ ++ $ hg branch ++ mywork ++ $ hg merge default ++ ++Rather than using a clone on ``python.org`` (which isn't particularly useful ++for collaboration with folks that don't already have CPython commit rights), ++Bitbucket_ also maintain an `up to date clone`_ of the main ``cpython`` ++repository that can be used as the basis for a new clone or patch queue. ++ ++.. _named branch: http://mercurial.selenic.com/wiki/NamedBranches ++.. _Bitbucket: http://www.bitbucket.org ++.. _up to date clone: https://bitbucket.org/mirror/cpython/overview ++ ++ ++Uploading a patch for review ++'''''''''''''''''''''''''''' ++ ++In this scheme, your work will probably consist of many commits (some of ++them merges). If you want to upload a patch for review somewhere, you need ++a single aggregate patch. This is where having a dedicated named branch ++``mywork`` gets handy. ++ ++First ensure that you have pulled *and merged* all changes from the main ++repository, as explained above. Then, assuming your :ref:`currently checked ++out branch ` is still ``mywork``, simply do:: ++ ++ $ hg diff -r default > mywork.patch ++ ++This will write to ``mywork.patch`` all the changes between ``default`` and ++``mywork``. +diff -r 85f290e474e2 build/_sources/communication.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/communication.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,81 @@ ++.. _communication: ++ ++Following Python's Development ++============================== ++ ++Python's development is communicated through a myriad of ways, mostly through ++mailing lists, but also other forms. ++ ++.. _mailinglists: ++ ++Mailing Lists ++------------- ++ ++The primary mailing list where discussions about Python's development occur is ++python-dev_. The list is open to the public and is subscribed to by all core ++developers plus many people simply interested in following Python's ++development. Discussion is focused on issues related to Python's development, ++such as how to handle a specific issue, a PEP, etc. Ideas about new ++functionality should **not** start here and instead should be sent to ++python-ideas_. Technical support questions should also not be asked here and ++instead should go to python-list_ or python-help_. ++ ++The python-committers_ mailing list is a private mailing list for core ++developers (the archives are publicly available). ++If something only affects core developers (e.g., the ++tree is frozen for commits, etc.), it is discussed here instead of python-dev ++to keep traffic down on the latter. ++ ++Python-ideas_ is a mailing list open to the public to discuss ideas on changing ++Python. If a new idea does not start here (or python-list_, discussed below), ++it will get redirected here. ++ ++Python-checkins_ sends out an email for every commit to Python's various ++repositories from http://hg.python.org. All core developers ++subscribe to this list and are known to reply to these emails to make comments ++about various issues they catch in the commit. Replies get redirected to ++python-dev. ++ ++There are two mailing lists related to issues on the `issue tracker`_. If you ++only want an email for when a new issue is open, subscribe to ++new-bugs-announce_. If you would rather receive an email for all changes made ++to any issue, subscribe to python-bugs-list_. ++ ++Sometimes people post new ideas to python-list_ to gather community opinion before ++heading to python-ideas_. The list is also sometimes known as comp.lang.python, ++the name of the newsgroup is mirrors (it is also known by the abbreviation ++c.l.py). ++ ++A complete list of Python mailing lists can be found at http://mail.python.org. ++Most lists are also mirrored at http://news.gmane.org/ and can be read and ++posted to in various ways, including via web browsers, NNTP newsreaders, and ++RSS feed readers. ++ ++.. _issue tracker: http://bugs.python.org ++.. _new-bugs-announce: http://mail.python.org/mailman/listinfo/new-bugs-announce ++.. _python-bugs-list: http://mail.python.org/mailman/listinfo/python-bugs-list ++.. _python-checkins: http://mail.python.org/mailman/listinfo/python-checkins ++.. _python-committers: http://mail.python.org/mailman/listinfo/python-committers ++.. _python-dev: http://mail.python.org/mailman/listinfo/python-dev ++.. _python-help: http://mail.python.org/mailman/listinfo/python-help ++.. _python-ideas: http://mail.python.org/mailman/listinfo/python-ideas ++.. _python-list: http://mail.python.org/mailman/listinfo/python-list ++ ++ ++IRC ++--- ++ ++Some core developers enjoy spending time on IRC discussing various issues ++regarding Python's development in the ``#python-dev`` channel on ++``irc.freenode.net``. This is not a place to ask for help with Python, but to ++discuss issues related to Python's own development. You can use freenode's ++`Web interface `_ if you don't have an IRC ++client. ++ ++ ++Blogs ++----- ++ ++Several core developers are active bloggers and discuss Python's development ++that way. You can find their blogs (and various other developers who use Python) ++at http://planet.python.org/. +diff -r 85f290e474e2 build/_sources/compiler.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/compiler.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,562 @@ ++.. _compiler: ++ ++Design of CPython's Compiler ++============================ ++ ++ ++Abstract ++-------- ++ ++Historically (through 2.4), compilation from source code to bytecode ++involved two steps: ++ ++1. Parse the source code into a parse tree (Parser/pgen.c) ++2. Emit bytecode based on the parse tree (Python/compile.c) ++ ++Historically, this is not how a standard compiler works. The usual ++steps for compilation are: ++ ++1. Parse source code into a parse tree (Parser/pgen.c) ++2. Transform parse tree into an Abstract Syntax Tree (Python/ast.c) ++3. Transform AST into a Control Flow Graph (Python/compile.c) ++4. Emit bytecode based on the Control Flow Graph (Python/compile.c) ++ ++Starting with Python 2.5, the above steps are now used. This change ++was done to simplify compilation by breaking it into three steps. ++The purpose of this document is to outline how the latter three steps ++of the process work. ++ ++This document does not touch on how parsing works beyond what is needed ++to explain what is needed for compilation. It is also not exhaustive ++in terms of the how the entire system works. You will most likely need ++to read some source to have an exact understanding of all details. ++ ++ ++Parse Trees ++----------- ++ ++Python's parser is an LL(1) parser mostly based off of the ++implementation laid out in the Dragon Book [Aho86]_. ++ ++The grammar file for Python can be found in Grammar/Grammar with the ++numeric value of grammar rules are stored in Include/graminit.h. The ++numeric values for types of tokens (literal tokens, such as ``:``, ++numbers, etc.) are kept in Include/token.h). The parse tree made up of ++``node *`` structs (as defined in Include/node.h). ++ ++Querying data from the node structs can be done with the following ++macros (which are all defined in Include/node.h): ++ ++``CHILD(node *, int)`` ++ Returns the nth child of the node using zero-offset indexing ++``RCHILD(node *, int)`` ++ Returns the nth child of the node from the right side; use ++ negative numbers! ++``NCH(node *)`` ++ Number of children the node has ++``STR(node *)`` ++ String representation of the node; e.g., will return ``:`` for a ++ COLON token ++``TYPE(node *)`` ++ The type of node as specified in ``Include/graminit.h`` ++``REQ(node *, TYPE)`` ++ Assert that the node is the type that is expected ++``LINENO(node *)`` ++ retrieve the line number of the source code that led to the ++ creation of the parse rule; defined in Python/ast.c ++ ++To tie all of this example, consider the rule for 'while':: ++ ++ while_stmt: 'while' test ':' suite ['else' ':' suite] ++ ++The node representing this will have ``TYPE(node) == while_stmt`` and ++the number of children can be 4 or 7 depending on if there is an 'else' ++statement. To access what should be the first ':' and require it be an ++actual ':' token, `(REQ(CHILD(node, 2), COLON)``. ++ ++ ++Abstract Syntax Trees (AST) ++--------------------------- ++ ++The abstract syntax tree (AST) is a high-level representation of the ++program structure without the necessity of containing the source code; ++it can be thought of as an abstract representation of the source code. The ++specification of the AST nodes is specified using the Zephyr Abstract ++Syntax Definition Language (ASDL) [Wang97]_. ++ ++The definition of the AST nodes for Python is found in the file ++Parser/Python.asdl . ++ ++Each AST node (representing statements, expressions, and several ++specialized types, like list comprehensions and exception handlers) is ++defined by the ASDL. Most definitions in the AST correspond to a ++particular source construct, such as an 'if' statement or an attribute ++lookup. The definition is independent of its realization in any ++particular programming language. ++ ++The following fragment of the Python ASDL construct demonstrates the ++approach and syntax:: ++ ++ module Python ++ { ++ stmt = FunctionDef(identifier name, arguments args, stmt* body, ++ expr* decorators) ++ | Return(expr? value) | Yield(expr value) ++ attributes (int lineno) ++ } ++ ++The preceding example describes three different kinds of statements; ++function definitions, return statements, and yield statements. All ++three kinds are considered of type stmt as shown by '|' separating the ++various kinds. They all take arguments of various kinds and amounts. ++ ++Modifiers on the argument type specify the number of values needed; '?' ++means it is optional, '*' means 0 or more, no modifier means only one ++value for the argument and it is required. FunctionDef, for instance, ++takes an identifier for the name, 'arguments' for args, zero or more ++stmt arguments for 'body', and zero or more expr arguments for ++'decorators'. ++ ++Do notice that something like 'arguments', which is a node type, is ++represented as a single AST node and not as a sequence of nodes as with ++stmt as one might expect. ++ ++All three kinds also have an 'attributes' argument; this is shown by the ++fact that 'attributes' lacks a '|' before it. ++ ++The statement definitions above generate the following C structure type:: ++ ++ typedef struct _stmt *stmt_ty; ++ ++ struct _stmt { ++ enum { FunctionDef_kind=1, Return_kind=2, Yield_kind=3 } kind; ++ union { ++ struct { ++ identifier name; ++ arguments_ty args; ++ asdl_seq *body; ++ } FunctionDef; ++ ++ struct { ++ expr_ty value; ++ } Return; ++ ++ struct { ++ expr_ty value; ++ } Yield; ++ } v; ++ int lineno; ++ } ++ ++Also generated are a series of constructor functions that allocate (in ++this case) a stmt_ty struct with the appropriate initialization. The ++'kind' field specifies which component of the union is initialized. The ++FunctionDef() constructor function sets 'kind' to FunctionDef_kind and ++initializes the 'name', 'args', 'body', and 'attributes' fields. ++ ++ ++Memory Management ++----------------- ++ ++Before discussing the actual implementation of the compiler, a discussion of ++how memory is handled is in order. To make memory management simple, an arena ++is used. This means that a memory is pooled in a single location for easy ++allocation and removal. What this gives us is the removal of explicit memory ++deallocation. Because memory allocation for all needed memory in the compiler ++registers that memory with the arena, a single call to free the arena is all ++that is needed to completely free all memory used by the compiler. ++ ++In general, unless you are working on the critical core of the compiler, memory ++management can be completely ignored. But if you are working at either the ++very beginning of the compiler or the end, you need to care about how the arena ++works. All code relating to the arena is in either Include/pyarena.h or ++Python/pyarena.c . ++ ++PyArena_New() will create a new arena. The returned PyArena structure will ++store pointers to all memory given to it. This does the bookkeeping of what ++memory needs to be freed when the compiler is finished with the memory it used. ++That freeing is done with PyArena_Free(). This needs to only be called in ++strategic areas where the compiler exits. ++ ++As stated above, in general you should not have to worry about memory ++management when working on the compiler. The technical details have been ++designed to be hidden from you for most cases. ++ ++The only exception comes about when managing a PyObject. Since the rest ++of Python uses reference counting, there is extra support added ++to the arena to cleanup each PyObject that was allocated. These cases ++are very rare. However, if you've allocated a PyObject, you must tell ++the arena about it by calling ``PyArena_AddPyObject()``. ++ ++ ++Parse Tree to AST ++----------------- ++ ++The AST is generated from the parse tree (see Python/ast.c) using the ++function ``PyAST_FromNode()``. ++ ++The function begins a tree walk of the parse tree, creating various AST ++nodes as it goes along. It does this by allocating all new nodes it ++needs, calling the proper AST node creation functions for any required ++supporting functions, and connecting them as needed. ++ ++Do realize that there is no automated nor symbolic connection between ++the grammar specification and the nodes in the parse tree. No help is ++directly provided by the parse tree as in yacc. ++ ++For instance, one must keep track of which node in the parse tree ++one is working with (e.g., if you are working with an 'if' statement ++you need to watch out for the ':' token to find the end of the conditional). ++ ++The functions called to generate AST nodes from the parse tree all have ++the name ast_for_xx where xx is what the grammar rule that the function ++handles (alias_for_import_name is the exception to this). These in turn ++call the constructor functions as defined by the ASDL grammar and ++contained in Python/Python-ast.c (which was generated by ++Parser/asdl_c.py) to create the nodes of the AST. This all leads to a ++sequence of AST nodes stored in asdl_seq structs. ++ ++ ++Function and macros for creating and using ``asdl_seq *`` types as found ++in Python/asdl.c and Include/asdl.h: ++ ++``asdl_seq_new()`` ++ Allocate memory for an asdl_seq for the specified length ++``asdl_seq_GET()`` ++ Get item held at a specific position in an asdl_seq ++``asdl_seq_SET()`` ++ Set a specific index in an asdl_seq to the specified value ++``asdl_seq_LEN(asdl_seq *)`` ++ Return the length of an asdl_seq ++ ++If you are working with statements, you must also worry about keeping ++track of what line number generated the statement. Currently the line ++number is passed as the last parameter to each stmt_ty function. ++ ++ ++Control Flow Graphs ++------------------- ++ ++A control flow graph (often referenced by its acronym, CFG) is a ++directed graph that models the flow of a program using basic blocks that ++contain the intermediate representation (abbreviated "IR", and in this ++case is Python bytecode) within the blocks. Basic blocks themselves are ++a block of IR that has a single entry point but possibly multiple exit ++points. The single entry point is the key to basic blocks; it all has ++to do with jumps. An entry point is the target of something that ++changes control flow (such as a function call or a jump) while exit ++points are instructions that would change the flow of the program (such ++as jumps and 'return' statements). What this means is that a basic ++block is a chunk of code that starts at the entry point and runs to an ++exit point or the end of the block. ++ ++As an example, consider an 'if' statement with an 'else' block. The ++guard on the 'if' is a basic block which is pointed to by the basic ++block containing the code leading to the 'if' statement. The 'if' ++statement block contains jumps (which are exit points) to the true body ++of the 'if' and the 'else' body (which may be NULL), each of which are ++their own basic blocks. Both of those blocks in turn point to the ++basic block representing the code following the entire 'if' statement. ++ ++CFGs are usually one step away from final code output. Code is directly ++generated from the basic blocks (with jump targets adjusted based on the ++output order) by doing a post-order depth-first search on the CFG ++following the edges. ++ ++ ++AST to CFG to Bytecode ++---------------------- ++ ++With the AST created, the next step is to create the CFG. The first step ++is to convert the AST to Python bytecode without having jump targets ++resolved to specific offsets (this is calculated when the CFG goes to ++final bytecode). Essentially, this transforms the AST into Python ++bytecode with control flow represented by the edges of the CFG. ++ ++Conversion is done in two passes. The first creates the namespace ++(variables can be classified as local, free/cell for closures, or ++global). With that done, the second pass essentially flattens the CFG ++into a list and calculates jump offsets for final output of bytecode. ++ ++The conversion process is initiated by a call to the function ++``PyAST_Compile()`` in Python/compile.c . This function does both the ++conversion of the AST to a CFG and ++outputting final bytecode from the CFG. The AST to CFG step is handled ++mostly by two functions called by PyAST_Compile(); PySymtable_Build() and ++compiler_mod() . The former is in Python/symtable.c while the latter is in ++Python/compile.c . ++ ++PySymtable_Build() begins by entering the starting code block for the ++AST (passed-in) and then calling the proper symtable_visit_xx function ++(with xx being the AST node type). Next, the AST tree is walked with ++the various code blocks that delineate the reach of a local variable ++as blocks are entered and exited using symtable_enter_block() and ++symtable_exit_block(), respectively. ++ ++Once the symbol table is created, it is time for CFG creation, whose ++code is in Python/compile.c . This is handled by several functions ++that break the task down by various AST node types. The functions are ++all named compiler_visit_xx where xx is the name of the node type (such ++as stmt, expr, etc.). Each function receives a ``struct compiler *`` ++and xx_ty where xx is the AST node type. Typically these functions ++consist of a large 'switch' statement, branching based on the kind of ++node type passed to it. Simple things are handled inline in the ++'switch' statement with more complex transformations farmed out to other ++functions named compiler_xx with xx being a descriptive name of what is ++being handled. ++ ++When transforming an arbitrary AST node, use the VISIT() macro. ++The appropriate compiler_visit_xx function is called, based on the value ++passed in for (so ``VISIT(c, expr, node)`` calls ++``compiler_visit_expr(c, node)``). The VISIT_SEQ macro is very similar, ++but is called on AST node sequences (those values that were created as ++arguments to a node that used the '*' modifier). There is also ++VISIT_SLICE() just for handling slices. ++ ++Emission of bytecode is handled by the following macros: ++ ++``ADDOP()`` ++ add a specified opcode ++``ADDOP_I()`` ++ add an opcode that takes an argument ++``ADDOP_O(struct compiler *c, int op, PyObject *type, PyObject *obj)`` ++ add an opcode with the proper argument based on the position of the ++ specified PyObject in PyObject sequence object, but with no handling of ++ mangled names; used for when you ++ need to do named lookups of objects such as globals, consts, or ++ parameters where name mangling is not possible and the scope of the ++ name is known ++``ADDOP_NAME()`` ++ just like ADDOP_O, but name mangling is also handled; used for ++ attribute loading or importing based on name ++``ADDOP_JABS()`` ++ create an absolute jump to a basic block ++``ADDOP_JREL()`` ++ create a relative jump to a basic block ++ ++Several helper functions that will emit bytecode and are named ++compiler_xx() where xx is what the function helps with (list, boolop, ++etc.). A rather useful one is compiler_nameop(). ++This function looks up the scope of a variable and, based on the ++expression context, emits the proper opcode to load, store, or delete ++the variable. ++ ++As for handling the line number on which a statement is defined, is ++handled by compiler_visit_stmt() and thus is not a worry. ++ ++In addition to emitting bytecode based on the AST node, handling the ++creation of basic blocks must be done. Below are the macros and ++functions used for managing basic blocks: ++ ++``NEW_BLOCK()`` ++ create block and set it as current ++``NEXT_BLOCK()`` ++ basically NEW_BLOCK() plus jump from current block ++``compiler_new_block()`` ++ create a block but don't use it (used for generating jumps) ++ ++Once the CFG is created, it must be flattened and then final emission of ++bytecode occurs. Flattening is handled using a post-order depth-first ++search. Once flattened, jump offsets are backpatched based on the ++flattening and then a PyCodeObject file is created. All of this is ++handled by calling assemble() . ++ ++ ++Introducing New Bytecode ++------------------------ ++ ++Sometimes a new feature requires a new opcode. But adding new bytecode is ++not as simple as just suddenly introducing new bytecode in the AST -> ++bytecode step of the compiler. Several pieces of code throughout Python depend ++on having correct information about what bytecode exists. ++ ++First, you must choose a name and a unique identifier number. The official ++list of bytecode can be found in Include/opcode.h . If the opcode is to take ++an argument, it must be given a unique number greater than that assigned to ++``HAVE_ARGUMENT`` (as found in Include/opcode.h). ++ ++Once the name/number pair ++has been chosen and entered in Include/opcode.h, you must also enter it into ++Lib/opcode.py and Doc/library/dis.rst . ++ ++With a new bytecode you must also change what is called the magic number for ++.pyc files. The variable ``MAGIC`` in Python/import.c contains the number. ++Changing this number will lead to all .pyc files with the old MAGIC ++to be recompiled by the interpreter on import. ++ ++Finally, you need to introduce the use of the new bytecode. Altering ++Python/compile.c and Python/ceval.c will be the primary places to change. ++But you will also need to change the 'compiler' package. The key files ++to do that are Lib/compiler/pyassem.py and Lib/compiler/pycodegen.py . ++ ++If you make a change here that can affect the output of bytecode that ++is already in existence and you do not change the magic number constantly, make ++sure to delete your old .py(c|o) files! Even though you will end up changing ++the magic number if you change the bytecode, while you are debugging your work ++you will be changing the bytecode output without constantly bumping up the ++magic number. This means you end up with stale .pyc files that will not be ++recreated. Running ++``find . -name '*.py[co]' -exec rm -f {} ';'`` should delete all .pyc files you ++have, forcing new ones to be created and thus allow you test out your new ++bytecode properly. ++ ++ ++Code Objects ++------------ ++ ++The result of ``PyAST_Compile()`` is a PyCodeObject which is defined in ++Include/code.h . And with that you now have executable Python bytecode! ++ ++The code objects (byte code) is executed in Python/ceval.c . This file ++will also need a new case statement for the new opcode in the big switch ++statement in PyEval_EvalFrameEx(). ++ ++ ++Important Files ++--------------- ++ +++ Parser/ ++ ++ Python.asdl ++ ASDL syntax file ++ ++ asdl.py ++ "An implementation of the Zephyr Abstract Syntax Definition ++ Language." Uses SPARK_ to parse the ASDL files. ++ ++ asdl_c.py ++ "Generate C code from an ASDL description." Generates ++ Python/Python-ast.c and Include/Python-ast.h . ++ ++ spark.py ++ SPARK_ parser generator ++ +++ Python/ ++ ++ Python-ast.c ++ Creates C structs corresponding to the ASDL types. Also ++ contains code for marshaling AST nodes (core ASDL types have ++ marshaling code in asdl.c). "File automatically generated by ++ Parser/asdl_c.py". This file must be committed separately ++ after every grammar change is committed since the __version__ ++ value is set to the latest grammar change revision number. ++ ++ asdl.c ++ Contains code to handle the ASDL sequence type. Also has code ++ to handle marshalling the core ASDL types, such as number and ++ identifier. used by Python-ast.c for marshaling AST nodes. ++ ++ ast.c ++ Converts Python's parse tree into the abstract syntax tree. ++ ++ ceval.c ++ Executes byte code (aka, eval loop). ++ ++ compile.c ++ Emits bytecode based on the AST. ++ ++ symtable.c ++ Generates a symbol table from AST. ++ ++ pyarena.c ++ Implementation of the arena memory manager. ++ ++ import.c ++ Home of the magic number (named ``MAGIC``) for bytecode versioning ++ ++ +++ Include/ ++ ++ Python-ast.h ++ Contains the actual definitions of the C structs as generated by ++ Python/Python-ast.c . ++ "Automatically generated by Parser/asdl_c.py". ++ ++ asdl.h ++ Header for the corresponding Python/ast.c . ++ ++ ast.h ++ Declares PyAST_FromNode() external (from Python/ast.c). ++ ++ code.h ++ Header file for Objects/codeobject.c; contains definition of ++ PyCodeObject. ++ ++ symtable.h ++ Header for Python/symtable.c . struct symtable and ++ PySTEntryObject are defined here. ++ ++ pyarena.h ++ Header file for the corresponding Python/pyarena.c . ++ ++ opcode.h ++ Master list of bytecode; if this file is modified you must modify ++ several other files accordingly (see "`Introducing New Bytecode`_") ++ +++ Objects/ ++ ++ codeobject.c ++ Contains PyCodeObject-related code (originally in ++ Python/compile.c). ++ +++ Lib/ ++ ++ opcode.py ++ One of the files that must be modified if Include/opcode.h is. ++ ++ compiler/ ++ ++ pyassem.py ++ One of the files that must be modified if Include/opcode.h is ++ changed. ++ ++ pycodegen.py ++ One of the files that must be modified if Include/opcode.h is ++ changed. ++ ++ ++Known Compiler-related Experiments ++---------------------------------- ++ ++This section lists known experiments involving the compiler (including ++bytecode). ++ ++Skip Montanaro presented a paper at a Python workshop on a peephole optimizer ++[#skip-peephole]_. ++ ++Michael Hudson has a non-active SourceForge project named Bytecodehacks ++[#Bytecodehacks]_ that provides functionality for playing with bytecode ++directly. ++ ++An opcode to combine the functionality of LOAD_ATTR/CALL_FUNCTION was created ++named CALL_ATTR [#CALL_ATTR]_. Currently only works for classic classes and ++for new-style classes rough benchmarking showed an actual slowdown thanks to ++having to support both classic and new-style classes. ++ ++ ++ ++References ++---------- ++ ++.. [Aho86] Alfred V. Aho, Ravi Sethi, Jeffrey D. Ullman. ++ `Compilers: Principles, Techniques, and Tools`, ++ http://www.amazon.com/exec/obidos/tg/detail/-/0201100886/104-0162389-6419108 ++ ++.. [Wang97] Daniel C. Wang, Andrew W. Appel, Jeff L. Korn, and Chris ++ S. Serra. `The Zephyr Abstract Syntax Description Language.`_ ++ In Proceedings of the Conference on Domain-Specific Languages, pp. ++ 213--227, 1997. ++ ++.. _The Zephyr Abstract Syntax Description Language.: ++ http://www.cs.princeton.edu/research/techreps/TR-554-97 ++ ++.. _SPARK: http://pages.cpsc.ucalgary.ca/~aycock/spark/ ++ ++.. [#skip-peephole] Skip Montanaro's Peephole Optimizer Paper ++ (http://www.python.org/workshops/1998-11/proceedings/papers/montanaro/montanaro.html) ++ ++.. [#Bytecodehacks] Bytecodehacks Project ++ (http://bytecodehacks.sourceforge.net/bch-docs/bch/index.html) ++ ++.. [#CALL_ATTR] CALL_ATTR opcode ++ (http://www.python.org/sf/709744) +diff -r 85f290e474e2 build/_sources/coredev.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/coredev.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,153 @@ ++.. _coredev: ++ ++How to Become a Core Developer ++============================== ++ ++What it Takes ++------------- ++ ++When you have consistently contributed patches which meet quality standards ++without requiring extensive rewrites prior to being committed, ++you may qualify for ++commit privileges and become a core developer of Python. You must also work ++well with other core developers (and people in general) as you become an ++ambassador for the Python project. ++ ++Typically a core developer will offer you the chance to gain commit privilege. ++The person making the offer will become your mentor and watch your commits for ++a while to make sure you understand the development process. If other core ++developers agree that you should gain commit privileges you are then extended ++an official offer. ++ ++You may request commit privileges yourself, but do not be surprised if your ++request is turned down. Do not take this personally! It simply means that other ++core developers think you need more time contributing patches before you are ++able to commit them without supervision. ++ ++A complete list of core developer usernames can be found at ++http://hg.python.org/committers.txt. :ref:`developers` lists when and why ++someone received commit privileges. ++ ++ ++Gaining Commit Privileges ++------------------------- ++ ++When you have been extended an official offer to become a Python core ++developer, there are several things you must do. ++ ++Mailing Lists ++''''''''''''' ++ ++You are expected to subscribe to python-committers, python-dev, ++python-checkins, and one of new-bugs-announce or python-bugs-list. See ++:ref:`communication` for links to these mailing lists. ++ ++ ++Issue Tracker ++''''''''''''' ++ ++If you did not gain the Developer role in the `issue tracker`_ before gaining ++commit privileges, please say so. This will allow issues to be assigned to you. ++A tracker admin should also flip your "is committer" bit in the tracker's ++account screen. ++ ++It is expected that on the issue tracker you have a username in the form of ++"first_name.last_name". If your initial issue tracker username is not of this ++form, please change it. This is so that it is easier to assign issues to the ++right person. ++ ++ ++SSH ++''' ++ ++You need to generate an SSH 2 RSA key to be able to commit code. You may have ++multiple keys if you wish (e.g., for work and home). Send your key as an ++attachment in an email to hgaccounts@python.org. Help in generating an SSH key ++can be found in the :ref:`faq`. ++ ++Your SSH key will be set to a username in the form of "first_name.last_name". ++This should match your username on the issue tracker. ++ ++You can verify your commit access by looking at ++http://hg.python.org/committers.txt which lists all core developers by ++username. If you want to practice, there is a `test repository ++`_ where you can freely commit and push any ++changes you like:: ++ ++ hg clone ssh://hg@hg.python.org/test/ hgtest ++ ++An entry in the :ref:`developers` should also be entered for you. ++Typically the person who sponsored your application to become a core developer ++makes sure an entry is created for you. ++ ++ ++.. _contributor_agreement: ++ ++Sign a Contributor Agreement ++'''''''''''''''''''''''''''' ++ ++Submitting a `contributor form for Python`_ licenses any code you contribute to ++the Python Software Foundation. While you retain the copyright, giving the PSF ++the ability to license your code means it can be put under the PSF license so ++it can be legally distributed with Python. ++ ++This is a very important step! Hopefully you have already submitted a ++contributor agreement if you have been submitting patches. But if you have not ++done this yet, it is best to do this ASAP, probably before you even do your ++first commit so as to not forget. ++ ++ ++.. _contributor form for Python: http://www.python.org/psf/contrib/ ++ ++ ++ ++Read/Write Checkout ++''''''''''''''''''' ++ ++With your commit privileges working and your contributor form submitted, you ++can now get a read/write checkout of the code. URLs for read/write checkouts ++are different than those for read-only checkouts as SSH is used instead of ++HTTP. ++ ++You can clone the repository (which contains all active branches) with:: ++ ++ hg clone ssh://hg@hg.python.org/cpython ++ ++The default branch in that repository is the current development branch. ++You can of course switch your working copy to one of the maintenance branches, ++for example:: ++ ++ hg update 2.7 ++ ++ ++Responsibilities ++---------------- ++ ++As a core developer, there are certain things that are expected of you. ++ ++First and foremost, be a good person. This might sound melodramatic, but you ++are now a member of the Python project and thus represent the project and your ++fellow core developers whenever you discuss Python with anyone. We have a ++reputation for being a very nice group of people and we would like to keep it ++that way. ++ ++Second, please be prompt in responding to questions. We are all volunteers so ++what little free time one can dedicate to Python should be spent being ++productive. If you have been asked to respond to an issue or answer a question ++and you put it off it ends up stalling other people's work. It is completely ++acceptable to say you are too busy, but you need to say that instead of ++stringing people along. This obviously applies to anything you do on the issue ++tracker as well. ++ ++Third, please list what areas you want to be considered an expert in the ++:ref:`experts`. This allows triagers to direct issues to you which involve ++an area you are an expert in. But, ++as stated in the second point above, if you do not have the time to answer ++questions promptly then please remove yourself as needed from the file so that ++you will not be bothered in the future. Once again, we all understand how life ++gets in the way, so no one will be insulted if you remove yourself from the ++list. ++ ++And finally, enjoy yourself! Contributing to open source software should be fun ++(overall). If you find yourself no longer enjoying the work then either take a ++break or figure out what you need to do to make it enjoyable again. +diff -r 85f290e474e2 build/_sources/coverage.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/coverage.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,260 @@ ++.. _coverage: ++ ++Increase Test Coverage ++====================== ++ ++Python development follows a practice that all semantic changes and additions ++to the language and :abbr:`stdlib (standard library)` are accompanied by ++appropriate unit tests. Unfortunately Python was in existence for a long time ++before the practice came into effect. This has left chunks of the stdlib ++untested which is not a desirable situation to be in. ++ ++A good, easy way to become acquainted with Python's code and to help out is to ++help increase the test coverage for Python's stdlib. Ideally we would like to ++have 100% coverage, but any increase is a good one. Do realize, though, that ++getting 100% coverage is not always possible. There could be platform-specific ++code that simply will not execute for you, errors in the output, etc. You can ++use your judgement as to what should and should not be covered, but being ++conservative and assuming something should be covered is generally a good rule ++to follow. ++ ++Choosing what module you want to increase test coverage for can be done in a ++couple of ways. ++A third-party website at http://coverage.livinglogic.de/ provides an ++overall view of how good coverage is for various modules (you will want to ++focus on those in the ``Lib`` directory as those are the pure Python modules ++from Python's stdlib, and thus easier to work with than the C extension ++modules). But since this is a third-party site we cannot promise that it will ++always be accessible or have useful information (i.e., be working properly). ++ ++Another is to follow the examples below and simply see what ++coverage your favorite module has. This is "stabbing in the dark", though, and ++so it might take some time to find a module that needs coverage help. ++ ++Finally, you can simply run the entire test suite yourself with coverage turned ++on and see what modules need help. This has the drawback of running the entire ++test suite under coverage measuring which takes some time to complete, but you ++will have an accurate, up-to-date notion of what modules need the most work. ++ ++Do make sure, though, that for any module you do decide to work on that you run ++coverage for just that module. This will make sure you know how good the ++explicit coverage of the module is from its own set of tests instead of from ++implicit testing by other code that happens to use the module. ++ ++ ++Common Gotchas ++"""""""""""""" ++ ++Please realize that coverage reports on modules already imported before coverage ++data starts to be recorded will be wrong. Typically you can tell a module falls ++into this category by the coverage report saying that global statements that ++would obviously be executed upon import have gone unexecuted while local ++statements have been covered. In these instances you can ignore the global ++statement coverage and simply focus on the local statement coverage. ++ ++When writing new tests to increase coverage, do take note of the style of tests ++already provided for a module (e.g., whitebox, blackbox, etc.). As ++some modules are primarily maintained by a single core developer they may have ++a specific preference as to what kind of test is used (e.g., whitebox) and ++prefer that other types of tests not be used (e.g., blackbox). When in doubt, ++stick with whitebox testing in order to properly exercise the code. ++ ++ ++Measuring Coverage ++"""""""""""""""""" ++ ++It should be noted that a quirk of running coverage over Python's own stdlib is ++that certain modules are imported as part of interpreter startup. Those modules ++required by Python itself will not be viewed as executed by the coverage tools ++and thus look like they have very poor coverage (e.g., the :py:mod:`stat` ++module). In these instances the module will appear to not have any coverage of ++global statements but will have proper coverage of local statements (e.g., ++function definitions will be not be traced, but the function bodies will). ++Calculating the coverage of modules in this situation will simply require ++manually looking at what local statements were not executed. ++ ++Using coverage.py ++----------------- ++ ++One of the most popular third-party coverage tools is `coverage.py`_ which ++provides very nice HTML output along with advanced features such as ++:ref:`branch coverage `. If you prefer to stay with tools only ++provided by the stdlib then you can by :ref:`using test.regrtest ++`. ++ ++Because the in-development version of Python is bleeding-edge, it is possible ++that the latest release version of coverage.py will not work. In that case you ++should try using the in-development of coverage.py to see if it has been ++updated as needed. To do this you should clone/check out the development version ++of coverage.py:: ++ ++ hg clone https://bitbucket.org/ned/coveragepy ++ ++Another option is to use an installed copy of coverage.py if you already have an ++installed copy. But if you do not already have it installed then it is preferred ++you use a clone of coverage.py for gathering coverage results. ++ ++If you are using a clone of coverage.py, the following should work (substitute ++``COVERAGEDIR`` with the directory where your clone exists, e.g. ++``../coveragepy``):: ++ ++ ./python COVERAGEDIR ++ ++Coverage.py will print out a little bit of helper text verifying that ++everything is working. If you are using an installed copy, you can do the ++following instead:: ++ ++ ./python -m coverage ++ ++The rest of the examples on how to use coverage.py will assume you are using a ++cloned copy, but you can substitute the above and all instructions should still ++be valid. ++ ++To run the test suite under coverage.py, do the following:: ++ ++ ./python COVERAGEDIR run --pylib Lib/test/regrtest.py ++ ++To run only a single test, specify the module/package being tested ++in the ``--source`` flag (so as to prune the coverage reporting to only the ++module/package you are interested in) and then append the name of the test you ++wish to run to the command:: ++ ++ ./python COVERAGEDIR run --pylib --source=abc Lib/test/regrtest.py test_abc ++ ++To see the results of the coverage run, you can view a text-based report with:: ++ ++ ./python COVERAGEDIR report ++ ++You can use the ``--show-missing`` flag to get a list of lines that were not ++executed:: ++ ++ ./python COVERAGEDIR report --show-missing ++ ++But one of the strengths of coverage.py is its HTML-based reports which let ++you visually see what lines of code were not tested:: ++ ++ ./python COVERAGEDIR html -i --include=`pwd`/Lib/* --omit="Lib/test/*,Lib/*/tests/*" ++ ++This will generate an HTML report in a directory named ``htmlcov`` which ++ignores any errors that may arise and ignores modules for which test coverage is ++unimportant (e.g. tests, temp files, etc.). You can then open the ++``htmlcov/index.html`` file in a web browser to view the coverage results along ++with pages that visibly show what lines of code were or were not executed. ++ ++ ++.. _branch_coverage: ++ ++Branch Coverage ++''''''''''''''' ++ ++For the truly daring, you can use another powerful feature of coverage.py: ++branch coverage. Testing every possible branch path through code, while a great ++goal to strive for, is a secondary goal to getting 100% line ++coverage for the entire stdlib (for now). ++ ++If you decide you want to try to improve branch coverage, simply add the ++``--branch`` flag to your coverage run:: ++ ++ ./python COVERAGEDIR run --pylib --branch ++ ++This will lead to the report stating not only what lines were not covered, but ++also what branch paths were not executed. ++ ++ ++Coverage Results For Modules Imported Early On ++'''''''''''''''''''''''''''''''''''''''''''''' ++ ++For the *truly truly* daring, you can use a hack to get coverage.py to include ++coverage for modules that are imported early on during CPython's startup (e.g. ++the encodings module). Do not worry if you can't get this to work or it doesn't ++make any sense; it's entirely optional and only important for a small number of ++modules. ++ ++If you still choose to try this, the first step is to build coverage.py's C ++extension code. Assuming that coverage.py's clone is at ``COVERAGEDIR`` and ++your clone of CPython is at ``CPYTHONDIR``, you execute the following in your ++coverage.py clone:: ++ ++ CPPFLAGS="-I CPYTHONDIR -I CPYTHONDIR/Include" CPYTHONDIR/python setup.py build_ext --inplace ++ ++This will build coverage.py's C extension code in-place, allowing the previous ++instructions on how to gather coverage to continue to work. ++ ++To get coverage.py to be able to gather the most accurate coverage data on as ++many modules as possible ++**with a HORRIBLE HACK that you should NEVER use in your own code**, run the ++following from your CPython clone:: ++ ++ PYTHONPATH=COVERAGEDIR/coverage/fullcoverage ./python COVERAGEDIR run --pylib Lib/test/regrtest.py ++ ++This will give you the most complete coverage possible for CPython's standard ++library. ++ ++.. _coverage.py: http://nedbatchelder.com/code/coverage/ ++ ++ ++.. _coverage_by_regrtest: ++ ++Using test.regrtest ++------------------- ++ ++If you prefer to rely solely on the stdlib to generate coverage data, you can ++do so by passing the appropriate flags to :py:mod:`test.regrtest` (along with ++any other flags you want to):: ++ ++ ./python -m test --coverage -D `pwd`/coverage_data ++ ++Do note the argument to ``-D``; if you do not specify an absolute path to where ++you want the coverage data to end up it will go somewhere you don't expect. ++ ++ ++.. note:: ++ If you are running coverage over the entire test suite, make sure to ++ add ``-x test_importlib test_runpy test_trace`` to exclude those tests as ++ they trigger exceptions during coverage; see ++ http://bugs.python.org/issue10541 and http://bugs.python.org/issue10991. ++ ++Once the tests are done you will find the directory you specified contains ++files for each executed module along with which lines were executed how many ++times. ++ ++ ++Filing the Issue ++"""""""""""""""" ++Once you have increased coverage, you need to ++:ref:`generate the patch ` and submit it to the `issue tracker`_. On the ++issue set the "Components" to "Test" and "Versions" to the version of Python you ++worked on (i.e., the in-development version). ++ ++.. _issue tracker: http://bugs.python.org ++ ++ ++Measuring coverage of C code with gcov and lcov ++""""""""""""""""""""""""""""""""""""""""""""""" ++ ++It's also possible to measure the function, line and branch coverage of ++Python's C code. Right now only GCC with `gcov`_ is supported. In order to ++create an instrumented build of Python with gcov, run:: ++ ++ make coverage ++ ++Then run some code and gather coverage data with the ``gcov`` command. In ++order to create a HTML report you can install `lcov`_. The command:: ++ ++ make coverage-lcov ++ ++assembles coverage data, removes 3rd party and system libaries and finally ++creates a report. You can skip both steps and just run:: ++ ++ make coverage-report ++ ++if you like to generate a coverage report for Python's stdlib tests. It takes ++about 20 to 30 minutes on a modern computer. ++ ++.. note:: ++ ++ Multiple test jobs may not work properly. C coverage reporting has only ++ been tested with a single test process. ++ ++.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html ++.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php +diff -r 85f290e474e2 build/_sources/coverity.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/coverity.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,153 @@ ++============= ++Coverity Scan ++============= ++ ++.. _coverity: ++ ++Coverity Scan is a free service for static code analysis of Open Source ++projects. It is based on Coverity's commercial product and is able to analyze ++C, C++ and Java code. ++ ++Coverity's static code analysis doesn't run the code. Instead of that it uses ++abstract interpretation to gain information about the code's control flow and ++data flow. It's able to follow all possible code paths that a program may ++take. For example the analyzer understands that ``malloc()`` returns a memory ++that must be freed with ``free()`` later. It follows all branches and function ++calls to see if all possible combinations free the memory. The analyzer is ++able to detect all sorts of issues like resource leaks (memory, file ++descriptors), NULL dereferencing, use after free, unchecked return values, ++dead code, buffer overflows, integer overflows, uninitialized variables, and ++many more. ++ ++ ++Access to analysis reports ++========================== ++ ++The results are available on the `Coverity Scan`_ website. In order to ++access the results you have to create an account yourself. Then go to ++*Projects using Scan* and add yourself to the Python project. New members must ++be approved by an admin (see `Contact`_). ++ ++Access is restricted to Python core developers only. Other individuals may be ++given access at our own discretion, too. Every now and then Coverity detects a ++critical issue in Python's code -- new analyzers may even find new bugs in ++mature code. We don't want to disclose issues prematurely. ++ ++ ++Building and uploading analysis ++=============================== ++ ++The process is automated. A script runs ``hg pull``, ``hg update``, ++``cov-build`` and uploads the latest analysis to Coverity. Since Coverity has ++limited the maximum number of builds per week Python is analyzed every second ++day. The build runs on a dedicated virtual machine on PSF's infrastructure at ++OSU Open Source Labs. The process is maintained by Christian Heimes (see ++`Contact`_). At present only the tip is analyzed with the 64bit Linux tools. ++ ++ ++Known limitations ++================= ++ ++Some aspects of Python's C code are not yet understood by Coverity. ++ ++False positives ++--------------- ++ ++``Py_BuildValue("N", PyObject*)`` ++ Coverity doesn't understand that ``N`` format char passes the object along ++ without touching its reference count. On this ground the analyzer detects ++ a resource leak. CID 719685 ++ ++``PyLong_FromLong()`` for negative values ++ Coverity claims that ``PyLong_FromLong()`` and other ``PyLong_From*()`` ++ functions cannot handle a negative value because the value might be used as ++ an array index in ``get_small_int()``. CID 486783 ++ ++``PyLong_FromLong()`` for n in [-5 ... +255] ++ For integers in the range of Python's small int cache the ``PyLong_From*()`` ++ function can never fail and never returns NULL. CID 1058291 ++ ++``PyArg_ParseTupleAndKeywords(args, kwargs, "s#", &data, &length)`` ++ Some functions use the format char combination such as ``s#``, ``u#`` or ++ ``z#`` to get data and length of a character array. Coverity doesn't ++ recognize the relation between data and length. Sometimes it detects a buffer ++ overflow if data is written to a fixed size buffer although ++ ``length <= sizeof(buffer)``. CID 486613 ++ ++``path_converter()`` dereferencing after null check ++ The ``path_converter()`` function in ``posixmodule.c`` makes sure that ++ either ``path_t.narrow`` or ``path_t.wide`` is filled unless ++ ``path_t.nullable`` is explicitly enabled. CID 719648 ++ ++ ++Intentionally ++------------- ++ ++``Py_VA_COPY()`` ++ Python is written in C89 (ANSI C), therefore it can't use C99 features such ++ as ``va_copy()``. Python's own variant ``Py_VA_COPY()`` uses ``memcpy()`` ++ to make a copy of a ``va_list`` variable. Coverity detects two issues in ++ this approach: "Passing argument "lva" of type "va_list" and sizeof(va_list) ++ to function memcpy() is suspicious." CID 486405 and "Uninitialized pointer ++ read" CID 486630. ++ ++ ++Modeling ++======== ++ ++Modeling is explained in the *Coverity Help Center* which is available in ++the help menu of `Coverity Connect`_. `coverity_model.c`_ contains a copy of ++Python's modeling file for Coverity. Please keep the copy in sync with the ++model file in *Analysis Settings* of `Coverity Scan`_. ++ ++ ++Workflow ++======== ++ ++False positive and intentional issues ++------------------------------------- ++ ++If the problem is listed under `Known limitations`_ then please set the ++classification to either "False positive" or "Intentional", the action to ++"Ignore", owner to your own account and add a comment why the issue ++is considered false positive or intentional. ++ ++If you think it's a new false positive or intentional then please contact an ++admin. The first step should be an updated to Python's `Modeling`_ file. ++ ++ ++Positive issues ++--------------- ++ ++You should always create an issue unless it's really a trivial case. Please ++add the full url to the ticket under *Ext. Reference* and add the CID ++(Coverity ID) to both the ticket and the checkin message. It makes it much ++easier to understand the relation between tickets, fixes and Coverity issues. ++ ++ ++Contact ++======= ++ ++Please include both Brett and Christian in any mail regarding Coverity. Mails ++to Coverity should go through Brett or Christian, too. ++ ++Christian Heimes ++ admin, maintainer of build machine, intermediary between Python and Coverity ++ ++Brett Cannon ++ co-admin ++ ++Dakshesh Vyas ++ Technical Manager - Coverity Scan ++ ++ ++.. seealso:: ++ ++ `Coverity Scan FAQ `_ ++ ++ ++.. _Coverity Scan: http://scan.coverity.com/ ++ ++.. _Coverity Connect: http://scan5.coverity.com:8080/ ++ ++.. _coverity_model.c: http://hg.python.org/cpython/file/tip/Misc/coverity_model.c +diff -r 85f290e474e2 build/_sources/devcycle.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/devcycle.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,190 @@ ++.. _devcycle: ++ ++Development Cycle ++================= ++ ++The responsibilities of a core developer shift based on what kind of branch of ++Python a developer is working on and what stage the branch is in. ++ ++To clarify terminology, Python uses a ``major.minor.micro`` nomenclature ++for production-ready releases. So for Python 3.1.2 final, that is a *major ++version* of 3, a *minor version* of 1, and a *micro version* of 2. ++ ++* new *major versions* are exceptional; they only come when strongly ++ incompatible changes are deemed necessary, and are planned very long ++ in advance; ++ ++* new *minor versions* are feature releases; they get released roughly ++ every 18 months, from the current :ref:`in-development ` ++ branch; ++ ++* new *micro versions* are bugfix releases; they get released roughly ++ every 6 months, although they can come more often if necessary; they are ++ prepared in :ref:`maintenance ` branches. ++ ++We also publish non-final versions which get an additional qualifier: ++:ref:`alpha`, :ref:`beta`, :ref:`release candidate `. These versions ++are aimed at testing by advanced users, not production use. ++ ++ ++Branches ++'''''''' ++ ++There is a branch for each *feature version*, whether released or not (e.g. ++2.7, 3.5). Development is handled separately for Python 2 and Python 3: ++no merging happens between 2.x and 3.x branches. ++ ++In each of the 2.x and 3.x realms, the branch for a feature version is always a ++descendant of the previous feature version: for example, the ``3.3`` branch is a ++descendant of the ``3.2`` branch. ++ ++Therefore, each change should be made **first** in the oldest branch to which it ++applies and forward-ported as appropriate: if a bug must be fixed in both Python ++3.4 and 3.5, first fix it in ``3.4`` and then merge ``3.4`` into ``default`` ++(which holds the future 3.5). ++ ++ ++.. _indevbranch: ++ ++In-development (main) branch ++---------------------------- ++ ++The ``default`` branch is the branch for the next feature release; it is ++under active development for all kinds of changes: new features, semantic ++changes, performance improvements, bug fixes. As the name indicates, it ++is the branch :ref:`checked out ` by default by Mercurial. ++ ++Once a :ref:`final` release (say, 3.3) is made from the in-development branch, a ++new :ref:`maintenance branch ` is created to host all bug fixing ++activity for further micro versions (3.3.1, 3.3.2, etc.). ++ ++ ++.. _maintbranch: ++ ++Maintenance branches ++-------------------- ++ ++A branch for a previous feature release, currently being maintained for bug ++fixes. There are usually two maintenance branches at any given time: one for ++Python 3.x and ++one for Python 2.x. At some point in the future, Python 2.x will be closed ++for bug fixes and there will be only one maintenance branch left. ++ ++The only changes allowed to occur in a maintenance branch without debate are ++bug fixes. Also, a general rule for maintenance branches is that compatibility ++must not be broken at any point between sibling minor releases (3.3.1, 3.3.2, ++etc.). For both rules, only rare exceptions are accepted and **must** be ++discussed first. ++ ++Sometime after a new maintenance branch is created (after a new *minor version* ++is released), the old maintenance branch on that major version will go into ++:ref:`security mode `, ++usually after one last maintenance release at the discretion of the ++release manager. For example, the 3.2 maintenance branch was put into ++:ref:`security mode ` after the 3.2.4 final maintenance release ++following the release of 3.3.0. ++ ++.. _secbranch: ++ ++Security branches ++----------------- ++ ++A branch less than 5 years old but no longer in maintenance mode. ++ ++The only changes made to a security branch are those fixing issues exploitable ++by attackers such as crashes, privilege escalation and, optionally, other ++issues such as denial of service attacks. Any other changes are ++**not** considered a security risk and thus not backported to a security branch. ++ ++Commits to security branches are to be coordinated with the release manager ++for the corresponding feature version, as listed below in the Summary_. ++Any release made from a security branch is source-only and done only when actual ++security patches have been applied to the branch. ++ ++ ++.. _listbranch: ++ ++Summary ++------- ++ ++There are 5 open branches right now in the Mercurial repository: ++ ++- the ``default`` branch holds the future 3.5 version and descends from ``3.4`` ++ (future RM: Larry Hastings) ++- the ``3.4`` branch holds bug fixes for future 3.4.x maintenance releases ++ and descends from ``3.3`` (RM: Larry Hastings) ++- the ``3.3`` branch holds security fixes for future 3.3.x maintenance releases ++ and descends from ``3.2`` (RM: Georg Brandl) ++- the ``3.2`` branch holds security fixes for future 3.2.x security releases ++ (RM: Georg Brandl) ++- the ``3.1`` branch holds security fixes for future 3.1.x security releases ++ (RM: Benjamin Peterson) ++- the ``2.7`` branch holds bug fixes for future 2.7.x maintenance releases and ++ descends from ``2.6`` (RM: Benjamin Peterson) ++ ++ ++.. _stages: ++ ++Stages ++'''''' ++ ++Based on what stage the :ref:`in-development ` version of Python ++is in, the responsibilities of a core developer change in regards to commits ++to the :abbr:`VCS (version control system)`. ++ ++ ++Pre-alpha ++--------- ++ ++The branch is in this stage when no official release has been done since ++the latest final release. There are no special restrictions placed on ++commits, although the usual advice applies (getting patches reviewed, avoiding ++breaking the buildbots). ++ ++.. _alpha: ++ ++Alpha ++----- ++ ++Alpha releases typically serve as a reminder to core developers that they ++need to start getting in changes that change semantics or add something to ++Python as such things should not be added during a Beta_. Otherwise no new ++restrictions are in place while in alpha. ++ ++.. _beta: ++ ++Beta ++---- ++ ++After a first beta release is published, no new features are accepted. Only ++bug fixes can now be committed. This is when core developers should concentrate ++on the task of fixing regressions and other new issues filed by users who have ++downloaded the alpha and beta releases. ++ ++Being in beta can be viewed much like being in RC_ but without the extra overhead ++of needing commit reviews. ++ ++.. _rc: ++ ++Release Candidate (RC) ++---------------------- ++ ++A branch preparing for an RC release can only have bugfixes applied that have ++been reviewed by other core developers. Generally, these issues must be ++severe enough (e.g. crashes) that they deserve fixing before the final release. ++All other issues should be deferred to the next development cycle, since stability ++is the strongest concern at this point. ++ ++You **cannot** skip the peer review during an RC, no matter how small! Even if ++it is a simple copy-and-paste change, **everything** requires peer review from ++a core developer. ++ ++.. _final: ++ ++Final ++----- ++ ++When a final release is being cut, only the release manager (RM) can make ++changes to the branch. After the final release is published, the full ++:ref:`development cycle ` starts again for the next minor version. ++ +diff -r 85f290e474e2 build/_sources/developers.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/developers.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,423 @@ ++.. _developers: ++ ++Developer Log ++============= ++ ++This file is a running log of developers given commit privileges for Python. ++ ++The purpose is to provide some institutional memory of who was given access ++and why. ++ ++The first entry starts in April 2005. In keeping with the style of ++Misc/NEWS, newer entries should be added to the top. ++Entries should include the initials of the ++project admin who made the change or granted access. ++ ++Note, when giving new commit permissions, be sure to get a contributor agreement ++from the committer. See http://www.python.org/psf/contrib/ for details. When ++the agreement is signed, please note it in this log. SSH keys of the committer ++should be sent to hgaccounts@python.org. ++ ++This file is encoded in UTF-8. If the usual form for a name is not in ++a Latin or extended Latin alphabet, make sure to include an ASCII ++transliteration too. ++ ++Permissions History ++------------------- ++ ++- Yury Selivanov was given push privileges on Jan 23 2014 by GFB, for "inspect" ++ module and general contributions, on recommendation by Nick Coghlan. ++ ++- Donald Stufft was given push privileges on Aug 14 2013 by BAC, for PEP ++ editing, on the recommendation of Nick Coghlan. ++ ++- Ethan Furman was given push privileges on May 11 2013 by BAC, for PEP 435 ++ work, on the recommendation of Eli Bendersky. ++ ++- Roger Serwy was given push privileges on Mar 21 2013 by GFB, for IDLE ++ contributions, on recommendation by Ned Deily. ++ ++- Serhiy Storchaka was given push privileges on Dec 26 2012 by GFB, for general ++ contributions, on recommendation by Trent Nelson. ++ ++- Chris Jerdonek was given push privileges on Sep 24 2012 by GFB, for general ++ contributions, on recommendation by Ezio Melotti. ++ ++- Daniel Holth was given push privileges on Sep 9 2012 by GFB, for PEP editing. ++ ++- Eric Snow was given push privileges on Sep 5 2012 by Antoine Pitrou for ++ general contributions, on recommendation by Nick Coghlan. ++ ++- Peter Moody was given push privileges on May 20 2012 by Antoine Pitrou for ++ authorship and maintenance of the ipaddress module (accepted in PEP 3144 by ++ Nick Coghlan). ++ ++- Hynek Schlawack was given push privileges on May 14 2012 by Antoine Pitrou ++ for general contributions. ++ ++- Richard Oudkerk was given push privileges on Apr 29 2012 by Antoine Pitrou ++ on recommendation by Charles-François Natali and Jesse Noller, for various ++ contributions to multiprocessing (and original authorship of ++ multiprocessing's predecessor, the processing package). ++ ++- Andrew Svetlov was given push privileges on Mar 13 2012 by MvL at ++ the PyCon sprint. ++ ++- Petri Lehtinen was given push privileges on Oct 22 2011 by GFB, for ++ general contributions, on recommendation by Antoine Pitrou. ++ ++- Meador Inge was given push privileges on Sep 19 2011 by GFB, for ++ general contributions, on recommendation by Mark Dickinson. ++ ++- Sandro Tosi was given push privileges on Aug 1 2011 by Antoine Pitrou, ++ for documentation and other contributions, on recommendation by Ezio ++ Melotti, R. David Murray and others. ++ ++- Charles-François Natali was given push privileges on May 19 2011 by Antoine ++ Pitrou, for general contributions, on recommendation by Victor Stinner, ++ Brian Curtin and others. ++ ++- Nadeem Vawda was given push privileges on Apr 10 2011 by GFB, for ++ general contributions, on recommendation by Antoine Pitrou. ++ ++- Carl Friedrich Bolz was given push privileges on Mar 21 2011 by BAC, for ++ stdlib compatibility work for PyPy. ++ ++- Alexis Métaireau, Elson Rodriguez, Kelsey Hightower, Michael Mulich and ++ Walker Hale were given push privileges on Mar 16 2011 by GFB, for ++ contributions to the packaging module. ++ ++- Jeff Hardy was given push privileges on Mar 14 2011 by BAC, for stdlib ++ compatibility work for IronPython. ++ ++- Alex Gaynor and Maciej Fijalkowski were given push privileges on Mar 13 2011 ++ by BAC, for stdlib compatibility work for PyPy. ++ ++- Ross Lagerwall was given push privileges on Mar 13 2011 by GFB, ++ on recommendation by Antoine Pitrou and Ned Deily. ++ ++- Eli Bendersky was given commit access on Jan 11 2011 by BAC, ++ on recommendation by Terry Reedy and Nick Coghlan. ++ ++- Ned Deily was given commit access on Jan 9 2011 by MvL, ++ on recommendation by Antoine Pitrou. ++ ++- David Malcolm was given commit access on Oct 27 2010 by GFB, ++ at recommendation by Antoine Pitrou and Raymond Hettinger. ++ ++- Tal Einat was given commit access on Oct 4 2010 by MvL, ++ for improving IDLE. ++ ++- Łukasz Langa was given commit access on Sep 08 2010 by GFB, ++ at suggestion of Antoine Pitrou, for general bug fixing. ++ ++- Daniel Stutzbach was given commit access on Aug 22 2010 by MvL, ++ for general bug fixing. ++ ++- Ask Solem was given commit access on Aug 17 2010 by MvL, ++ on recommendation by Jesse Noller, for work on the multiprocessing ++ library. ++ ++- George Boutsioukis was given commit access on Aug 10 2010 ++ by MvL, for work on 2to3. ++ ++- Éric Araujo was given commit access on Aug 10 2010 by BAC, ++ at suggestion of Tarek Ziadé. ++ ++- Terry Reedy was given commit access on Aug 04 2010 by MvL, ++ at suggestion of Nick Coghlan. ++ ++- Brian Quinlan was given commit access on Jul 26 2010 by GFB, ++ for work related to PEP 3148. ++ ++- Reid Kleckner was given commit access on Jul 11 2010 by GFB, ++ for work on the py3k-jit branch, at suggestion of the Unladen ++ Swallow team. ++ ++- Alexander Belopolsky was given commit access on May 25 2010 ++ by MvL at suggestion of Mark Dickinson. ++ ++- Tim Golden was given commit access on April 21 2010 by MvL, ++ at suggestion of Michael Foord. ++ ++- Giampaolo Rodolà was given commit access on April 17 2010 by ++ MvL, at suggestion of R. David Murray. ++ ++- Jean-Paul Calderone was given commit access on April 6 2010 by ++ GFB, at suggestion of Michael Foord and others. ++ ++- Brian Curtin was given commit access on March 24 2010 by MvL. ++ ++- Florent Xicluna was given commit access on February 25 2010 by ++ MvL, based on Antoine Pitrou's recommendation. ++ ++- Dino Viehland was given SVN access on February 23 2010 by Brett ++ Cannon, for backporting tests from IronPython. ++ ++- Larry Hastings was given SVN access on February 22 2010 by ++ Andrew Kuchling, based on Brett Cannon's recommendation. ++ ++- Victor Stinner was given SVN access on January 30 2010 by MvL, ++ at recommendation by Mark Dickinson and Amaury Forgeot d'Arc. ++ ++- Stefan Krah was given SVN access on January 5 2010 by GFB, at ++ suggestion of Mark Dickinson, for work on the decimal module. ++ ++- Doug Hellmann was given SVN access on September 19 2009 by GFB, at ++ suggestion of Jesse Noller, for documentation work. ++ ++- Ezio Melotti was given SVN access on June 7 2009 by GFB, for work on and ++ fixes to the documentation. ++ ++- Paul Kippes was given commit privileges at PyCon 2009 by BAC to work on 3to2. ++ ++- Ron DuPlain was given commit privileges at PyCon 2009 by BAC to work on 3to2. ++ ++- Several developers of alternative Python implementations where ++ given access for test suite and library adaptions by MvL: ++ Allison Randal (Parrot), Michael Foord (IronPython), ++ Jim Baker, Philip Jenvey, and Frank Wierzbicki (all Jython). ++ ++- R. David Murray was given SVN access on March 30 2009 by MvL, after ++ recommendation by BAC. ++ ++- Chris Withers was given SVN access on March 8 2009 by MvL, ++ after recommendation by GvR. ++ ++- Tarek Ziadé was given SVN access on December 21 2008 by NCN, ++ for maintenance of distutils. ++ ++- Hirokazu Yamamoto was given SVN access on August 12 2008 by MvL, ++ for contributions to the Windows build. ++ ++- Antoine Pitrou was given SVN access on July 16 2008, by recommendation ++ from GvR, for general contributions to Python. ++ ++- Jesse Noller was given SVN access on 16 June 2008 by GFB, ++ for work on the multiprocessing module. ++ ++- Gregor Lingl was given SVN access on 10 June 2008 by MvL, ++ for work on the turtle module. ++ ++- Robert Schuppenies was given SVN access on 21 May 2008 by MvL, ++ for GSoC contributions. ++ ++- Rodrigo Bernardo Pimentel was given SVN access on 29 April 2008 by MvL, ++ for GSoC contributions. ++ ++- Heiko Weinen was given SVN access on 29 April 2008 by MvL, ++ for GSoC contributions. ++ ++- Jesus Cea was given SVN access on 24 April 2008 by MvL, ++ for maintenance of bsddb. ++ ++- Guilherme Polo was given SVN access on 24 April 2008 by MvL, ++ for GSoC contributions. ++ ++- Thomas Lee was given SVN access on 21 April 2008 by NCN, ++ for work on branches (ast/optimizer related). ++ ++- Jeroen Ruigrok van der Werven was given SVN access on 12 April 2008 ++ by GFB, for documentation work. ++ ++- Josiah Carlson was given SVN access on 26 March 2008 by GFB, ++ for work on asyncore/asynchat. ++ ++- Benjamin Peterson was given SVN access on 25 March 2008 by GFB, ++ for bug triage work. ++ ++- Jerry Seutter was given SVN access on 20 March 2008 by BAC, for ++ general contributions to Python. ++ ++- Jeff Rush was given SVN access on 18 March 2008 by AMK, for Distutils work. ++ ++- David Wolever was given SVN access on 17 March 2008 by MvL, ++ for 2to3 work. ++ ++- Trent Nelson was given SVN access on 17 March 2008 by MvL, ++ for general contributions to Python. ++ ++- Mark Dickinson was given SVN access on 6 January 2008 by Facundo ++ Batista for his work on mathematics and number related issues. ++ ++- Amaury Forgeot d'Arc was given SVN access on 9 November 2007 by MvL, ++ for general contributions to Python. ++ ++- Christian Heimes was given SVN access on 31 October 2007 by MvL, ++ for general contributions to Python. ++ ++- Chris Monson was given SVN access on 20 October 2007 by NCN, ++ for his work on editing PEPs. ++ ++- Bill Janssen was given SVN access on 28 August 2007 by NCN, ++ for his work on the SSL module and other things related to (SSL) sockets. ++ ++- Jeffrey Yasskin was given SVN access on 9 August 2007 by NCN, ++ for his work on PEPs and other general patches. ++ ++- Mark Summerfield was given SVN access on 1 August 2007 by GFB, ++ for work on documentation. ++ ++- Armin Ronacher was given SVN access on 23 July 2007 by GFB, ++ for work on the documentation toolset. He now maintains the ++ ast module. ++ ++- Senthil Kumaran was given SVN access on 16 June 2007 by MvL, ++ for his Summer-of-Code project, mentored by Skip Montanaro. ++ ++- Alexandre Vassalotti was given SVN access on 21 May 2007 by MvL, ++ for his Summer-of-Code project, mentored by Brett Cannon. ++ ++- Travis Oliphant was given SVN access on 17 Apr 2007 by MvL, ++ for implementing the extended buffer protocol. ++ ++- Ziga Seilnacht was given SVN access on 09 Mar 2007 by MvL, ++ for general maintenance. ++ ++- Pete Shinners was given SVN access on 04 Mar 2007 by NCN, ++ for PEP 3101 work in the sandbox. ++ ++- Pat Maupin and Eric V. Smith were given SVN access on 28 Feb 2007 by NCN, ++ for PEP 3101 work in the sandbox. ++ ++- Steven Bethard (SF name "bediviere") added to the SourceForge Python ++ project 26 Feb 2007, by NCN, as a tracker tech. ++ ++- Josiah Carlson (SF name "josiahcarlson") added to the SourceForge Python ++ project 06 Jan 2007, by NCN, as a tracker tech. He will maintain asyncore. ++ ++- Collin Winter was given SVN access on 05 Jan 2007 by NCN, for PEP ++ update access. ++ ++- Lars Gustaebel was given SVN access on 20 Dec 2006 by NCN, for tarfile.py ++ related work. ++ ++- 2006 Summer of Code entries: SoC developers are expected to work ++ primarily in nondist/sandbox or on a branch of their own, and will ++ have their work reviewed before changes are accepted into the trunk. ++ ++ - Matt Fleming was added on 25 May 2006 by AMK; he'll be working on ++ enhancing the Python debugger. ++ ++ - Jackilyn Hoxworth was added on 25 May 2006 by AMK; she'll be adding logging ++ to the standard library. ++ ++ - Mateusz Rukowicz was added on 30 May 2006 by AMK; he'll be ++ translating the decimal module into C. ++ ++- SVN access granted to the "Need for Speed" Iceland sprint attendees, ++ between May 17 and 21, 2006, by Tim Peters. All work is to be done ++ in new sandbox projects or on new branches, with merging to the ++ trunk as approved: ++ ++ Andrew Dalke ++ Christian Tismer ++ Jack Diederich ++ John Benediktsson ++ Kristján V. Jónsson ++ Martin Blais ++ Richard Emslie ++ Richard Jones ++ Runar Petursson ++ Steve Holden ++ Richard M. Tew ++ ++- Steven Bethard was given SVN access on 27 Apr 2006 by DJG, for PEP ++ update access. ++ ++- Talin was given SVN access on 27 Apr 2006 by DJG, for PEP update ++ access. ++ ++- George Yoshida (SF name "quiver") added to the SourceForge Python ++ project 14 Apr 2006, by Tim Peters, as a tracker admin. See ++ contemporaneous python-checkins thread with the unlikely Subject: ++ r45329 - python/trunk/Doc/whatsnew/whatsnew25.tex ++ ++- Ronald Oussoren was given SVN access on 3 Mar 2006 by NCN, for Mac ++ related work. ++ ++- Bob Ippolito was given SVN access on 2 Mar 2006 by NCN, for Mac ++ related work. ++ ++- Nick Coghlan requested CVS access so he could update his PEP directly. ++ Granted by GvR on 16 Oct 2005. ++ ++- Added two new developers for the Summer of Code project. 8 July 2005 ++ by RDH. Andrew Kuchling will be mentoring Gregory K Johnson for a ++ project to enhance mailbox. Brett Cannon requested access for Flovis ++ Bruynooghe (sirolf) to work on pstats, profile, and hotshot. Both users ++ are expected to work primarily in nondist/sandbox and have their work ++ reviewed before making updates to active code. ++ ++- Georg Brandl was given SF tracker permissions on 28 May 2005 ++ by RDH. Since the beginning of 2005, he has been active in discussions ++ on python-dev and has submitted a dozen patch reviews. The permissions ++ add the ability to change tracker status and to attach patches. On ++ 3 June 2005, this was expanded by RDH to include checkin permissions. ++ ++- Terry Reedy was given SF tracker permissions on 7 Apr 2005 by RDH. ++ ++- Nick Coghlan was given SF tracker permissions on 5 Apr 2005 by RDH. ++ For several months, he has been active in reviewing and contributing ++ patches. The added permissions give him greater flexibility in ++ working with the tracker. ++ ++- Eric Price was made a developer on 2 May 2003 by TGP. This was ++ specifically to work on the new ``decimal`` package, which lived in ++ ``nondist/sandbox/decimal/`` at the time. ++ ++- Eric S. Raymond was made a developer on 2 Jul 2000 by TGP, for general ++ library work. His request is archived here: ++ http://mail.python.org/pipermail/python-dev/2000-July/005314.html ++ ++ ++Permissions Dropped on Request ++------------------------------ ++ ++- Roy Smith, Matt Fleming and Richard Emslie sent drop requests. ++ 4 Aug 2008 GFB ++ ++- Per note from Andrew Kuchling, the permissions for Gregory K Johnson ++ and the Summer Of Code project are no longer needed. 4 Aug 2008 GFB ++ ++- Per note from Andrew Kuchling, the permissions for Gregory K Johnson ++ and the Summer Of Code project are no longer needed. AMK will make ++ any future checkins directly. 16 Oct 2005 RDH ++ ++- Johannes Gijsbers sent a drop request. 27 July 2005 RDH ++ ++- Flovis Bruynooghe sent a drop request. 14 July 2005 RDH ++ ++- Paul Prescod sent a drop request. 30 Apr 2005 RDH ++ ++- Finn Bock sent a drop request. 13 Apr 2005 RDH ++ ++- Eric Price sent a drop request. 10 Apr 2005 RDH ++ ++- Irmen de Jong requested dropping CVS access while keeping tracker ++ access. 10 Apr 2005 RDH ++ ++- Moshe Zadka and Ken Manheimer sent drop requests. 8 Apr 2005 by RDH ++ ++- Steve Holden, Gerhard Haring, and David Cole sent email stating that ++ they no longer use their access. 7 Apr 2005 RDH ++ ++ ++Permissions Dropped after Loss of Contact ++----------------------------------------- ++ ++- Several unsuccessful efforts were made to contact Charles G Waldman. ++ Removed on 8 Apr 2005 by RDH. ++ ++ ++Initials of Project Admins ++-------------------------- ++ ++* TGP: Tim Peters ++* GFB: Georg Brandl ++* BAC: Brett Cannon ++* NCN: Neal Norwitz ++* DJG: David Goodger ++* MvL: Martin v. Loewis ++* GvR: Guido van Rossum ++* RDH: Raymond Hettinger +diff -r 85f290e474e2 build/_sources/docquality.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/docquality.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,100 @@ ++.. _docquality: ++ ++Helping with Documentation ++========================== ++ ++Python is known for having good documentation. But maintaining all of it and ++keeping a high level of quality takes a lot of effort. Help is always ++appreciated with the documentation, and it requires little programming ++experience (with or without Python). ++ ++:ref:`Documenting Python ` covers the details of how Python's documentation works. ++It includes an explanation of the markup used (although you can figure a lot ++out simply by looking at pre-existing documentation) and :ref:`how to build ++` the documentation (which allows you to see how your changes ++will look along with validating that your new markup is correct). ++ ++The documentation built from the :ref:`in-development ` and ++:ref:`maintenance ` branches can be viewed from ++http://docs.python.org/dev/. The in-development and most recent 2.x and 3.x ++maintenance :ref:`branches ` are rebuilt once per day. ++ ++If you care to get more involved with documentation, you may also consider ++subscribing to the ++`docs@python.org mailing list `_. ++Documentation issues reported on the `issue tracker`_ are sent here as well as ++some bug reports being directly emailed to the mailing list. There is also the ++`docs-sig@python.org mailing list ++`_ which discusses the ++documentation toolchain, projects, standards, etc. ++ ++ ++Helping with issues filed on the issue tracker ++---------------------------------------------- ++ ++If you look at `documentation issues`_ on the `issue tracker`_, you ++will find various documentation problems that need work. Issues vary from ++typos, to unclear documentation, to something completely lacking documentation. ++ ++If you decide to tackle a documentation issue, you simply :ref:`create a patch ++` for the issue and upload it. If you are worried that someone else might ++be working simultaneously on the issue, simply leave a comment on the issue ++saying you are going to try and create a patch and roughly how long you think ++you will take to do it (this allows others to take on the issue if you happen ++to forget or lose interest). ++ ++.. _issue tracker: http://bugs.python.org ++.. _documentation issues: http://bugs.python.org/issue?%40search_text=&ignore=file%3Acontent&title=&%40columns=title&id=&%40columns=id&stage=&creation=&creator=&activity=&%40columns=activity&%40sort=activity&actor=&nosy=&type=&components=4&versions=&dependencies=&assignee=&keywords=&priority=&%40group=priority&status=1&%40columns=status&resolution=&nosy_count=&message_count=&%40pagesize=50&%40startwith=0&%40queryname=&%40old-queryname=&%40action=search ++ ++ ++Proofreading ++------------ ++ ++While an issue filed on the `issue tracker`_ means there is a known issue ++somewhere, that does not mean there are not other issues lurking about in the ++documentation. Simply proofreading parts of the documentation is enough to ++uncover problems (e.g., documentation that needs to be updated for Python 3 ++from Python 2). ++ ++If you decide to proofread, then read a section of the documentation from start ++to finish, filing issues in the issue tracker for each problem you find. Don't ++file a single issue for an entire section containing multiple problems as that ++makes it harder to break the work up for multiple people to help with. ++ ++ ++.. _helping-with-the-developers-guide: ++ ++Helping with the Developer's Guide ++---------------------------------- ++ ++.. highlight:: bash ++ ++The Developer's Guide uses the same process as the main Python documentation, ++except for some small differences. The source lives in a `separate ++repository`_. Bug reports and patches should be submitted to the `Python ++bug tracker`_ using the ``devguide`` component. Changes to the devguide ++are normally published within a day, on a schedule that may be different from ++the main documentation. ++ ++.. _separate repository: http://hg.python.org/devguide ++.. _Python bug tracker: http://bugs.python.org ++ ++To clone the Developer's Guide:: ++ ++ $ hg clone http://hg.python.org/devguide ++ ++Core developers should use:: ++ ++ $ hg clone ssh://hg@hg.python.org/devguide ++ ++instead so that they can push back their edits to the server. ++ ++To build the devguide, you must have `Sphinx`_ installed. The devguide HTML ++can be built by running:: ++ ++ $ make html ++ ++in the checkout directory, which will write the files to the ``_build/html`` ++directory. ++ ++.. _Sphinx: http://sphinx.pocoo.org/ +diff -r 85f290e474e2 build/_sources/documenting.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/documenting.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,1528 @@ ++.. _documenting: ++ ++================== ++Documenting Python ++================== ++ ++The Python language has a substantial body of documentation, much of it ++contributed by various authors. The markup used for the Python documentation is ++`reStructuredText`_, developed by the `docutils`_ project, amended by custom ++directives and using a toolset named `Sphinx`_ to post-process the HTML output. ++ ++This document describes the style guide for our documentation as well as the ++custom reStructuredText markup introduced by Sphinx to support Python ++documentation and how it should be used. ++ ++The documentation in HTML, PDF or EPUB format is generated from text files ++written using the :ref:`reStructuredText format ` and contained in the ++:ref:`CPython Mercurial repository `. ++ ++.. _reStructuredText: http://docutils.sf.net/rst.html ++ ++.. note:: ++ ++ If you're interested in contributing to Python's documentation, there's no ++ need to write reStructuredText if you're not so inclined; plain text ++ contributions are more than welcome as well. Send an e-mail to ++ docs@python.org or open an issue on the :ref:`tracker `. ++ ++ ++Introduction ++============ ++ ++Python's documentation has long been considered to be good for a free ++programming language. There are a number of reasons for this, the most ++important being the early commitment of Python's creator, Guido van Rossum, to ++providing documentation on the language and its libraries, and the continuing ++involvement of the user community in providing assistance for creating and ++maintaining documentation. ++ ++The involvement of the community takes many forms, from authoring to bug reports ++to just plain complaining when the documentation could be more complete or ++easier to use. ++ ++This document is aimed at authors and potential authors of documentation for ++Python. More specifically, it is for people contributing to the standard ++documentation and developing additional documents using the same tools as the ++standard documents. This guide will be less useful for authors using the Python ++documentation tools for topics other than Python, and less useful still for ++authors not using the tools at all. ++ ++If your interest is in contributing to the Python documentation, but you don't ++have the time or inclination to learn reStructuredText and the markup structures ++documented here, there's a welcoming place for you among the Python contributors ++as well. Any time you feel that you can clarify existing documentation or ++provide documentation that's missing, the existing documentation team will ++gladly work with you to integrate your text, dealing with the markup for you. ++Please don't let the material in this document stand between the documentation ++and your desire to help out! ++ ++ ++Style guide ++=========== ++ ++Use of whitespace ++----------------- ++ ++All reST files use an indentation of 3 spaces; no tabs are allowed. The ++maximum line length is 80 characters for normal text, but tables, deeply ++indented code samples and long links may extend beyond that. Code example ++bodies should use normal Python 4-space indentation. ++ ++Make generous use of blank lines where applicable; they help grouping things ++together. ++ ++A sentence-ending period may be followed by one or two spaces; while reST ++ignores the second space, it is customarily put in by some users, for example ++to aid Emacs' auto-fill mode. ++ ++Footnotes ++--------- ++ ++Footnotes are generally discouraged, though they may be used when they are the ++best way to present specific information. When a footnote reference is added at ++the end of the sentence, it should follow the sentence-ending punctuation. The ++reST markup should appear something like this:: ++ ++ This sentence has a footnote reference. [#]_ This is the next sentence. ++ ++Footnotes should be gathered at the end of a file, or if the file is very long, ++at the end of a section. The docutils will automatically create backlinks to ++the footnote reference. ++ ++Footnotes may appear in the middle of sentences where appropriate. ++ ++Capitalization ++-------------- ++ ++.. sidebar:: Sentence case ++ ++ Sentence case is a set of capitalization rules used in English ++ sentences: the first word is always capitalized and other words are ++ only capitalized if there is a specific rule requiring it. ++ ++In the Python documentation, the use of sentence case in section titles is ++preferable, but consistency within a unit is more important than ++following this rule. If you add a section to a chapter where most ++sections are in title case, you can either convert all titles to ++sentence case or use the dominant style in the new section title. ++ ++Sentences that start with a word for which specific rules require ++starting it with a lower case letter should be avoided. ++ ++.. note:: ++ ++ Sections that describe a library module often have titles in the ++ form of "modulename --- Short description of the module." In this ++ case, the description should be capitalized as a stand-alone ++ sentence. ++ ++Many special names are used in the Python documentation, including the names of ++operating systems, programming languages, standards bodies, and the like. Most ++of these entities are not assigned any special markup, but the preferred ++spellings are given here to aid authors in maintaining the consistency of ++presentation in the Python documentation. ++ ++Other terms and words deserve special mention as well; these conventions should ++be used to ensure consistency throughout the documentation: ++ ++CPU ++ For "central processing unit." Many style guides say this should be ++ spelled out on the first use (and if you must use it, do so!). For ++ the Python documentation, this abbreviation should be avoided since ++ there's no reasonable way to predict which occurrence will be the ++ first seen by the reader. It is better to use the word "processor" ++ instead. ++ ++POSIX ++ The name assigned to a particular group of standards. This is always ++ uppercase. ++ ++Python ++ The name of our favorite programming language is always capitalized. ++ ++reST ++ For "reStructuredText," an easy to read, plaintext markup syntax ++ used to produce Python documentation. When spelled out, it is ++ always one word and both forms start with a lower case 'r'. ++ ++Unicode ++ The name of a character coding system. This is always written ++ capitalized. ++ ++Unix ++ The name of the operating system developed at AT&T Bell Labs in the early ++ 1970s. ++ ++Affirmative Tone ++---------------- ++ ++The documentation focuses on affirmatively stating what the language does and ++how to use it effectively. ++ ++Except for certain security risks or segfault risks, the docs should avoid ++wording along the lines of "feature x is dangerous" or "experts only". These ++kinds of value judgments belong in external blogs and wikis, not in the core ++documentation. ++ ++Bad example (creating worry in the mind of a reader): ++ ++ Warning: failing to explicitly close a file could result in lost data or ++ excessive resource consumption. Never rely on reference counting to ++ automatically close a file. ++ ++Good example (establishing confident knowledge in the effective use of the language): ++ ++ A best practice for using files is use a try/finally pair to explicitly ++ close a file after it is used. Alternatively, using a with-statement can ++ achieve the same effect. This assures that files are flushed and file ++ descriptor resources are released in a timely manner. ++ ++Economy of Expression ++--------------------- ++ ++More documentation is not necessarily better documentation. Err on the side ++of being succinct. ++ ++It is an unfortunate fact that making documentation longer can be an impediment ++to understanding and can result in even more ways to misread or misinterpret the ++text. Long descriptions full of corner cases and caveats can create the ++impression that a function is more complex or harder to use than it actually is. ++ ++Security Considerations (and Other Concerns) ++-------------------------------------------- ++ ++Some modules provided with Python are inherently exposed to security issues ++(e.g. shell injection vulnerabilities) due to the purpose of the module ++(e.g. :mod:`ssl`). Littering the documentation of these modules with red ++warning boxes for problems that are due to the task at hand, rather than ++specifically to Python's support for that task, doesn't make for a good ++reading experience. ++ ++Instead, these security concerns should be gathered into a dedicated ++"Security Considerations" section within the module's documentation, and ++cross-referenced from the documentation of affected interfaces with a note ++similar to ``"Please refer to the :ref:`security-considerations` section ++for important information on how to avoid common mistakes."``. ++ ++Similarly, if there is a common error that affects many interfaces in a ++module (e.g. OS level pipe buffers filling up and stalling child processes), ++these can be documented in a "Common Errors" section and cross-referenced ++rather than repeated for every affected interface. ++ ++Code Examples ++------------- ++ ++Short code examples can be a useful adjunct to understanding. Readers can often ++grasp a simple example more quickly than they can digest a formal description in ++prose. ++ ++People learn faster with concrete, motivating examples that match the context of ++a typical use case. For instance, the :func:`str.rpartition` method is better ++demonstrated with an example splitting the domain from a URL than it would be ++with an example of removing the last word from a line of Monty Python dialog. ++ ++The ellipsis for the :attr:`sys.ps2` secondary interpreter prompt should only be ++used sparingly, where it is necessary to clearly differentiate between input ++lines and output lines. Besides contributing visual clutter, it makes it ++difficult for readers to cut-and-paste examples so they can experiment with ++variations. ++ ++Code Equivalents ++---------------- ++ ++Giving pure Python code equivalents (or approximate equivalents) can be a useful ++adjunct to a prose description. A documenter should carefully weigh whether the ++code equivalent adds value. ++ ++A good example is the code equivalent for :func:`all`. The short 4-line code ++equivalent is easily digested; it re-emphasizes the early-out behavior; and it ++clarifies the handling of the corner-case where the iterable is empty. In ++addition, it serves as a model for people wanting to implement a commonly ++requested alternative where :func:`all` would return the specific object ++evaluating to False whenever the function terminates early. ++ ++A more questionable example is the code for :func:`itertools.groupby`. Its code ++equivalent borders on being too complex to be a quick aid to understanding. ++Despite its complexity, the code equivalent was kept because it serves as a ++model to alternative implementations and because the operation of the "grouper" ++is more easily shown in code than in English prose. ++ ++An example of when not to use a code equivalent is for the :func:`oct` function. ++The exact steps in converting a number to octal doesn't add value for a user ++trying to learn what the function does. ++ ++Audience ++-------- ++ ++The tone of the tutorial (and all the docs) needs to be respectful of the ++reader's intelligence. Don't presume that the readers are stupid. Lay out the ++relevant information, show motivating use cases, provide glossary links, and do ++your best to connect-the-dots, but don't talk down to them or waste their time. ++ ++The tutorial is meant for newcomers, many of whom will be using the tutorial to ++evaluate the language as a whole. The experience needs to be positive and not ++leave the reader with worries that something bad will happen if they make a ++misstep. The tutorial serves as guide for intelligent and curious readers, ++saving details for the how-to guides and other sources. ++ ++Be careful accepting requests for documentation changes from the rare but vocal ++category of reader who is looking for vindication for one of their programming ++errors ("I made a mistake, therefore the docs must be wrong ..."). Typically, ++the documentation wasn't consulted until after the error was made. It is ++unfortunate, but typically no documentation edit would have saved the user from ++making false assumptions about the language ("I was surprised by ..."). ++ ++ ++reStructuredText Primer ++======================= ++ ++This section is a brief introduction to reStructuredText (reST) concepts and ++syntax, intended to provide authors with enough information to author documents ++productively. Since reST was designed to be a simple, unobtrusive markup ++language, this will not take too long. ++ ++.. seealso:: ++ ++ The authoritative `reStructuredText User ++ Documentation `_. ++ ++ ++Paragraphs ++---------- ++ ++The paragraph is the most basic block in a reST document. Paragraphs are simply ++chunks of text separated by one or more blank lines. As in Python, indentation ++is significant in reST, so all lines of the same paragraph must be left-aligned ++to the same level of indentation. ++ ++ ++Inline markup ++------------- ++ ++The standard reST inline markup is quite simple: use ++ ++* one asterisk: ``*text*`` for emphasis (italics), ++* two asterisks: ``**text**`` for strong emphasis (boldface), and ++* backquotes: ````text```` for code samples. ++ ++If asterisks or backquotes appear in running text and could be confused with ++inline markup delimiters, they have to be escaped with a backslash. ++ ++Be aware of some restrictions of this markup: ++ ++* it may not be nested, ++* content may not start or end with whitespace: ``* text*`` is wrong, ++* it must be separated from surrounding text by non-word characters. Use a ++ backslash escaped space to work around that: ``thisis\ *one*\ word``. ++ ++These restrictions may be lifted in future versions of the docutils. ++ ++reST also allows for custom "interpreted text roles"', which signify that the ++enclosed text should be interpreted in a specific way. Sphinx uses this to ++provide semantic markup and cross-referencing of identifiers, as described in ++the appropriate section. The general syntax is ``:rolename:`content```. ++ ++ ++Lists and Quotes ++---------------- ++ ++List markup is natural: just place an asterisk at the start of a paragraph and ++indent properly. The same goes for numbered lists; they can also be ++automatically numbered using a ``#`` sign:: ++ ++ * This is a bulleted list. ++ * It has two items, the second ++ item uses two lines. ++ ++ 1. This is a numbered list. ++ 2. It has two items too. ++ ++ #. This is a numbered list. ++ #. It has two items too. ++ ++ ++Nested lists are possible, but be aware that they must be separated from the ++parent list items by blank lines:: ++ ++ * this is ++ * a list ++ ++ * with a nested list ++ * and some subitems ++ ++ * and here the parent list continues ++ ++Definition lists are created as follows:: ++ ++ term (up to a line of text) ++ Definition of the term, which must be indented ++ ++ and can even consist of multiple paragraphs ++ ++ next term ++ Description. ++ ++ ++Paragraphs are quoted by just indenting them more than the surrounding ++paragraphs. ++ ++ ++Source Code ++----------- ++ ++Literal code blocks are introduced by ending a paragraph with the special marker ++``::``. The literal block must be indented:: ++ ++ This is a normal text paragraph. The next paragraph is a code sample:: ++ ++ It is not processed in any way, except ++ that the indentation is removed. ++ ++ It can span multiple lines. ++ ++ This is a normal text paragraph again. ++ ++The handling of the ``::`` marker is smart: ++ ++* If it occurs as a paragraph of its own, that paragraph is completely left ++ out of the document. ++* If it is preceded by whitespace, the marker is removed. ++* If it is preceded by non-whitespace, the marker is replaced by a single ++ colon. ++ ++That way, the second sentence in the above example's first paragraph would be ++rendered as "The next paragraph is a code sample:". ++ ++ ++Hyperlinks ++---------- ++ ++External links ++^^^^^^^^^^^^^^ ++ ++Use ```Link text `_`` for inline web links. If the link text ++should be the web address, you don't need special markup at all, the parser ++finds links and mail addresses in ordinary text. ++ ++Internal links ++^^^^^^^^^^^^^^ ++ ++Internal linking is done via a special reST role, see the section on specific ++markup, :ref:`doc-ref-role`. ++ ++ ++Sections ++-------- ++ ++Section headers are created by underlining (and optionally overlining) the ++section title with a punctuation character, at least as long as the text:: ++ ++ ================= ++ This is a heading ++ ================= ++ ++Normally, there are no heading levels assigned to certain characters as the ++structure is determined from the succession of headings. However, for the ++Python documentation, here is a suggested convention: ++ ++* ``#`` with overline, for parts ++* ``*`` with overline, for chapters ++* ``=``, for sections ++* ``-``, for subsections ++* ``^``, for subsubsections ++* ``"``, for paragraphs ++ ++ ++Explicit Markup ++--------------- ++ ++"Explicit markup" is used in reST for most constructs that need special ++handling, such as footnotes, specially-highlighted paragraphs, comments, and ++generic directives. ++ ++An explicit markup block begins with a line starting with ``..`` followed by ++whitespace and is terminated by the next paragraph at the same level of ++indentation. (There needs to be a blank line between explicit markup and normal ++paragraphs. This may all sound a bit complicated, but it is intuitive enough ++when you write it.) ++ ++ ++Directives ++---------- ++ ++A directive is a generic block of explicit markup. Besides roles, it is one of ++the extension mechanisms of reST, and Sphinx makes heavy use of it. ++ ++Basically, a directive consists of a name, arguments, options and content. (Keep ++this terminology in mind, it is used in the next chapter describing custom ++directives.) Looking at this example, :: ++ ++ .. function:: foo(x) ++ foo(y, z) ++ :bar: no ++ ++ Return a line of text input from the user. ++ ++``function`` is the directive name. It is given two arguments here, the ++remainder of the first line and the second line, as well as one option ``bar`` ++(as you can see, options are given in the lines immediately following the ++arguments and indicated by the colons). ++ ++The directive content follows after a blank line and is indented relative to the ++directive start. ++ ++ ++Footnotes ++--------- ++ ++For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote ++body at the bottom of the document after a "Footnotes" rubric heading, like so:: ++ ++ Lorem ipsum [#]_ dolor sit amet ... [#]_ ++ ++ .. rubric:: Footnotes ++ ++ .. [#] Text of the first footnote. ++ .. [#] Text of the second footnote. ++ ++You can also explicitly number the footnotes for better context. ++ ++ ++Comments ++-------- ++ ++Every explicit markup block which isn't a valid markup construct (like the ++footnotes above) is regarded as a comment. ++ ++ ++Source encoding ++--------------- ++ ++Since the easiest way to include special characters like em dashes or copyright ++signs in reST is to directly write them as Unicode characters, one has to ++specify an encoding: ++ ++All Python documentation source files must be in UTF-8 encoding, and the HTML ++documents written from them will be in that encoding as well. ++ ++ ++Gotchas ++------- ++ ++There are some problems one commonly runs into while authoring reST documents: ++ ++* **Separation of inline markup:** As said above, inline markup spans must be ++ separated from the surrounding text by non-word characters, you have to use ++ an escaped space to get around that. ++ ++ ++Additional Markup Constructs ++============================ ++ ++Sphinx adds a lot of new directives and interpreted text roles to standard reST ++markup. This section contains the reference material for these facilities. ++Documentation for "standard" reST constructs is not included here, though ++they are used in the Python documentation. ++ ++.. note:: ++ ++ This is just an overview of Sphinx' extended markup capabilities; full ++ coverage can be found in `its own documentation ++ `_. ++ ++ ++Meta-information markup ++----------------------- ++ ++.. describe:: sectionauthor ++ ++ Identifies the author of the current section. The argument should include ++ the author's name such that it can be used for presentation (though it isn't) ++ and email address. The domain name portion of the address should be lower ++ case. Example:: ++ ++ .. sectionauthor:: Guido van Rossum ++ ++ Currently, this markup isn't reflected in the output in any way, but it helps ++ keep track of contributions. ++ ++ ++Module-specific markup ++---------------------- ++ ++The markup described in this section is used to provide information about a ++module being documented. Each module should be documented in its own file. ++Normally this markup appears after the title heading of that file; a typical ++file might start like this:: ++ ++ :mod:`parrot` -- Dead parrot access ++ =================================== ++ ++ .. module:: parrot ++ :platform: Unix, Windows ++ :synopsis: Analyze and reanimate dead parrots. ++ .. moduleauthor:: Eric Cleese ++ .. moduleauthor:: John Idle ++ ++As you can see, the module-specific markup consists of two directives, the ++``module`` directive and the ``moduleauthor`` directive. ++ ++.. describe:: module ++ ++ This directive marks the beginning of the description of a module, package, ++ or submodule. The name should be fully qualified (i.e. including the ++ package name for submodules). ++ ++ The ``platform`` option, if present, is a comma-separated list of the ++ platforms on which the module is available (if it is available on all ++ platforms, the option should be omitted). The keys are short identifiers; ++ examples that are in use include "IRIX", "Mac", "Windows", and "Unix". It is ++ important to use a key which has already been used when applicable. ++ ++ The ``synopsis`` option should consist of one sentence describing the ++ module's purpose -- it is currently only used in the Global Module Index. ++ ++ The ``deprecated`` option can be given (with no value) to mark a module as ++ deprecated; it will be designated as such in various locations then. ++ ++.. describe:: moduleauthor ++ ++ The ``moduleauthor`` directive, which can appear multiple times, names the ++ authors of the module code, just like ``sectionauthor`` names the author(s) ++ of a piece of documentation. It too does not result in any output currently. ++ ++.. note:: ++ ++ It is important to make the section title of a module-describing file ++ meaningful since that value will be inserted in the table-of-contents trees ++ in overview files. ++ ++ ++Information units ++----------------- ++ ++There are a number of directives used to describe specific features provided by ++modules. Each directive requires one or more signatures to provide basic ++information about what is being described, and the content should be the ++description. The basic version makes entries in the general index; if no index ++entry is desired, you can give the directive option flag ``:noindex:``. The ++following example shows all of the features of this directive type:: ++ ++ .. function:: spam(eggs) ++ ham(eggs) ++ :noindex: ++ ++ Spam or ham the foo. ++ ++The signatures of object methods or data attributes should not include the ++class name, but be nested in a class directive. The generated files will ++reflect this nesting, and the target identifiers (for HTML output) will use ++both the class and method name, to enable consistent cross-references. If you ++describe methods belonging to an abstract protocol such as context managers, ++use a class directive with a (pseudo-)type name too to make the ++index entries more informative. ++ ++The directives are: ++ ++.. describe:: c:function ++ ++ Describes a C function. The signature should be given as in C, e.g.:: ++ ++ .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) ++ ++ This is also used to describe function-like preprocessor macros. The names ++ of the arguments should be given so they may be used in the description. ++ ++ Note that you don't have to backslash-escape asterisks in the signature, ++ as it is not parsed by the reST inliner. ++ ++.. describe:: c:member ++ ++ Describes a C struct member. Example signature:: ++ ++ .. c:member:: PyObject* PyTypeObject.tp_bases ++ ++ The text of the description should include the range of values allowed, how ++ the value should be interpreted, and whether the value can be changed. ++ References to structure members in text should use the ``member`` role. ++ ++.. describe:: c:macro ++ ++ Describes a "simple" C macro. Simple macros are macros which are used ++ for code expansion, but which do not take arguments so cannot be described as ++ functions. This is not to be used for simple constant definitions. Examples ++ of its use in the Python documentation include :c:macro:`PyObject_HEAD` and ++ :c:macro:`Py_BEGIN_ALLOW_THREADS`. ++ ++.. describe:: c:type ++ ++ Describes a C type. The signature should just be the type name. ++ ++.. describe:: c:var ++ ++ Describes a global C variable. The signature should include the type, such ++ as:: ++ ++ .. cvar:: PyObject* PyClass_Type ++ ++.. describe:: data ++ ++ Describes global data in a module, including both variables and values used ++ as "defined constants." Class and object attributes are not documented ++ using this directive. ++ ++.. describe:: exception ++ ++ Describes an exception class. The signature can, but need not include ++ parentheses with constructor arguments. ++ ++.. describe:: function ++ ++ Describes a module-level function. The signature should include the ++ parameters, enclosing optional parameters in brackets. Default values can be ++ given if it enhances clarity. For example:: ++ ++ .. function:: repeat([repeat=3[, number=1000000]]) ++ ++ Object methods are not documented using this directive. Bound object methods ++ placed in the module namespace as part of the public interface of the module ++ are documented using this, as they are equivalent to normal functions for ++ most purposes. ++ ++ The description should include information about the parameters required and ++ how they are used (especially whether mutable objects passed as parameters ++ are modified), side effects, and possible exceptions. A small example may be ++ provided. ++ ++.. describe:: decorator ++ ++ Describes a decorator function. The signature should *not* represent the ++ signature of the actual function, but the usage as a decorator. For example, ++ given the functions ++ ++ .. code-block:: python ++ ++ def removename(func): ++ func.__name__ = '' ++ return func ++ ++ def setnewname(name): ++ def decorator(func): ++ func.__name__ = name ++ return func ++ return decorator ++ ++ the descriptions should look like this:: ++ ++ .. decorator:: removename ++ ++ Remove name of the decorated function. ++ ++ .. decorator:: setnewname(name) ++ ++ Set name of the decorated function to *name*. ++ ++ There is no ``deco`` role to link to a decorator that is marked up with ++ this directive; rather, use the ``:func:`` role. ++ ++.. describe:: class ++ ++ Describes a class. The signature can include parentheses with parameters ++ which will be shown as the constructor arguments. ++ ++.. describe:: attribute ++ ++ Describes an object data attribute. The description should include ++ information about the type of the data to be expected and whether it may be ++ changed directly. This directive should be nested in a class directive, ++ like in this example:: ++ ++ .. class:: Spam ++ ++ Description of the class. ++ ++ .. data:: ham ++ ++ Description of the attribute. ++ ++ If is also possible to document an attribute outside of a class directive, ++ for example if the documentation for different attributes and methods is ++ split in multiple sections. The class name should then be included ++ explicitly:: ++ ++ .. data:: Spam.eggs ++ ++.. describe:: method ++ ++ Describes an object method. The parameters should not include the ``self`` ++ parameter. The description should include similar information to that ++ described for ``function``. This directive should be nested in a class ++ directive, like in the example above. ++ ++.. describe:: decoratormethod ++ ++ Same as ``decorator``, but for decorators that are methods. ++ ++ Refer to a decorator method using the ``:meth:`` role. ++ ++.. describe:: opcode ++ ++ Describes a Python :term:`bytecode` instruction. ++ ++.. describe:: cmdoption ++ ++ Describes a Python command line option or switch. Option argument names ++ should be enclosed in angle brackets. Example:: ++ ++ .. cmdoption:: -m ++ ++ Run a module as a script. ++ ++.. describe:: envvar ++ ++ Describes an environment variable that Python uses or defines. ++ ++ ++There is also a generic version of these directives: ++ ++.. describe:: describe ++ ++ This directive produces the same formatting as the specific ones explained ++ above but does not create index entries or cross-referencing targets. It is ++ used, for example, to describe the directives in this document. Example:: ++ ++ .. describe:: opcode ++ ++ Describes a Python bytecode instruction. ++ ++ ++Showing code examples ++--------------------- ++ ++Examples of Python source code or interactive sessions are represented using ++standard reST literal blocks. They are started by a ``::`` at the end of the ++preceding paragraph and delimited by indentation. ++ ++Representing an interactive session requires including the prompts and output ++along with the Python code. No special markup is required for interactive ++sessions. After the last line of input or output presented, there should not be ++an "unused" primary prompt; this is an example of what *not* to do:: ++ ++ >>> 1 + 1 ++ 2 ++ >>> ++ ++Syntax highlighting is handled in a smart way: ++ ++* There is a "highlighting language" for each source file. Per default, ++ this is ``'python'`` as the majority of files will have to highlight Python ++ snippets. ++ ++* Within Python highlighting mode, interactive sessions are recognized ++ automatically and highlighted appropriately. ++ ++* The highlighting language can be changed using the ``highlightlang`` ++ directive, used as follows:: ++ ++ .. highlightlang:: c ++ ++ This language is used until the next ``highlightlang`` directive is ++ encountered. ++ ++* The ``code-block`` directive can be used to specify the highlight language ++ of a single code block, e.g.:: ++ ++ .. code-block:: c ++ ++ #include ++ ++ void main() { ++ printf("Hello world!\n"); ++ } ++ ++* The values normally used for the highlighting language are: ++ ++ * ``python`` (the default) ++ * ``c`` ++ * ``rest`` ++ * ``none`` (no highlighting) ++ ++* If highlighting with the current language fails, the block is not highlighted ++ in any way. ++ ++Longer displays of verbatim text may be included by storing the example text in ++an external file containing only plain text. The file may be included using the ++``literalinclude`` directive. [1]_ For example, to include the Python source file ++:file:`example.py`, use:: ++ ++ .. literalinclude:: example.py ++ ++The file name is relative to the current file's path. Documentation-specific ++include files should be placed in the ``Doc/includes`` subdirectory. ++ ++ ++Inline markup ++------------- ++ ++As said before, Sphinx uses interpreted text roles to insert semantic markup in ++documents. ++ ++Names of local variables, such as function/method arguments, are an exception, ++they should be marked simply with ``*var*``. ++ ++For all other roles, you have to write ``:rolename:`content```. ++ ++There are some additional facilities that make cross-referencing roles more ++versatile: ++ ++* You may supply an explicit title and reference target, like in reST direct ++ hyperlinks: ``:role:`title ``` will refer to *target*, but the link ++ text will be *title*. ++ ++* If you prefix the content with ``!``, no reference/hyperlink will be created. ++ ++* For the Python object roles, if you prefix the content with ``~``, the link ++ text will only be the last component of the target. For example, ++ ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only ++ display ``get`` as the link text. ++ ++ In HTML output, the link's ``title`` attribute (that is e.g. shown as a ++ tool-tip on mouse-hover) will always be the full target name. ++ ++The following roles refer to objects in modules and are possibly hyperlinked if ++a matching identifier is found: ++ ++.. describe:: mod ++ ++ The name of a module; a dotted name may be used. This should also be used for ++ package names. ++ ++.. describe:: func ++ ++ The name of a Python function; dotted names may be used. The role text ++ should not include trailing parentheses to enhance readability. The ++ parentheses are stripped when searching for identifiers. ++ ++.. describe:: data ++ ++ The name of a module-level variable or constant. ++ ++.. describe:: const ++ ++ The name of a "defined" constant. This may be a C-language ``#define`` ++ or a Python variable that is not intended to be changed. ++ ++.. describe:: class ++ ++ A class name; a dotted name may be used. ++ ++.. describe:: meth ++ ++ The name of a method of an object. The role text should include the type ++ name and the method name. A dotted name may be used. ++ ++.. describe:: attr ++ ++ The name of a data attribute of an object. ++ ++.. describe:: exc ++ ++ The name of an exception. A dotted name may be used. ++ ++The name enclosed in this markup can include a module name and/or a class name. ++For example, ``:func:`filter``` could refer to a function named ``filter`` in ++the current module, or the built-in function of that name. In contrast, ++``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo`` ++module. ++ ++Normally, names in these roles are searched first without any further ++qualification, then with the current module name prepended, then with the ++current module and class name (if any) prepended. If you prefix the name with a ++dot, this order is reversed. For example, in the documentation of the ++:mod:`codecs` module, ``:func:`open``` always refers to the built-in function, ++while ``:func:`.open``` refers to :func:`codecs.open`. ++ ++A similar heuristic is used to determine whether the name is an attribute of ++the currently documented class. ++ ++The following roles create cross-references to C-language constructs if they ++are defined in the API documentation: ++ ++.. describe:: c:data ++ ++ The name of a C-language variable. ++ ++.. describe:: c:func ++ ++ The name of a C-language function. Should include trailing parentheses. ++ ++.. describe:: c:macro ++ ++ The name of a "simple" C macro, as defined above. ++ ++.. describe:: c:type ++ ++ The name of a C-language type. ++ ++.. describe:: c:member ++ ++ The name of a C type member, as defined above. ++ ++ ++The following role does possibly create a cross-reference, but does not refer ++to objects: ++ ++.. describe:: token ++ ++ The name of a grammar token (used in the reference manual to create links ++ between production displays). ++ ++ ++The following role creates a cross-reference to the term in the glossary: ++ ++.. describe:: term ++ ++ Reference to a term in the glossary. The glossary is created using the ++ ``glossary`` directive containing a definition list with terms and ++ definitions. It does not have to be in the same file as the ``term`` ++ markup, in fact, by default the Python docs have one global glossary ++ in the ``glossary.rst`` file. ++ ++ If you use a term that's not explained in a glossary, you'll get a warning ++ during build. ++ ++--------- ++ ++The following roles don't do anything special except formatting the text ++in a different style: ++ ++.. describe:: command ++ ++ The name of an OS-level command, such as ``rm``. ++ ++.. describe:: dfn ++ ++ Mark the defining instance of a term in the text. (No index entries are ++ generated.) ++ ++.. describe:: envvar ++ ++ An environment variable. Index entries are generated. ++ ++.. describe:: file ++ ++ The name of a file or directory. Within the contents, you can use curly ++ braces to indicate a "variable" part, for example:: ++ ++ ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ... ++ ++ In the built documentation, the ``x`` will be displayed differently to ++ indicate that it is to be replaced by the Python minor version. ++ ++.. describe:: guilabel ++ ++ Labels presented as part of an interactive user interface should be marked ++ using ``guilabel``. This includes labels from text-based interfaces such as ++ those created using :mod:`curses` or other text-based libraries. Any label ++ used in the interface should be marked with this role, including button ++ labels, window titles, field names, menu and menu selection names, and even ++ values in selection lists. ++ ++.. describe:: kbd ++ ++ Mark a sequence of keystrokes. What form the key sequence takes may depend ++ on platform- or application-specific conventions. When there are no relevant ++ conventions, the names of modifier keys should be spelled out, to improve ++ accessibility for new users and non-native speakers. For example, an ++ *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without ++ reference to a specific application or platform, the same sequence should be ++ marked as ``:kbd:`Control-x Control-f```. ++ ++.. describe:: keyword ++ ++ The name of a Python keyword. Using this role will generate a link to the ++ documentation of the keyword. ``True``, ``False`` and ``None`` do not use ++ this role, but simple code markup (````True````), given that they're ++ fundamental to the language and should be known to any programmer. ++ ++.. describe:: mailheader ++ ++ The name of an RFC 822-style mail header. This markup does not imply that ++ the header is being used in an email message, but can be used to refer to any ++ header of the same "style." This is also used for headers defined by the ++ various MIME specifications. The header name should be entered in the same ++ way it would normally be found in practice, with the camel-casing conventions ++ being preferred where there is more than one common usage. For example: ++ ``:mailheader:`Content-Type```. ++ ++.. describe:: makevar ++ ++ The name of a :command:`make` variable. ++ ++.. describe:: manpage ++ ++ A reference to a Unix manual page including the section, ++ e.g. ``:manpage:`ls(1)```. ++ ++.. describe:: menuselection ++ ++ Menu selections should be marked using the ``menuselection`` role. This is ++ used to mark a complete sequence of menu selections, including selecting ++ submenus and choosing a specific operation, or any subsequence of such a ++ sequence. The names of individual selections should be separated by ++ ``-->``. ++ ++ For example, to mark the selection "Start > Programs", use this markup:: ++ ++ :menuselection:`Start --> Programs` ++ ++ When including a selection that includes some trailing indicator, such as the ++ ellipsis some operating systems use to indicate that the command opens a ++ dialog, the indicator should be omitted from the selection name. ++ ++.. describe:: mimetype ++ ++ The name of a MIME type, or a component of a MIME type (the major or minor ++ portion, taken alone). ++ ++.. describe:: newsgroup ++ ++ The name of a Usenet newsgroup. ++ ++.. describe:: option ++ ++ A command-line option of Python. The leading hyphen(s) must be included. ++ If a matching ``cmdoption`` directive exists, it is linked to. For options ++ of other programs or scripts, use simple ````code```` markup. ++ ++.. describe:: program ++ ++ The name of an executable program. This may differ from the file name for ++ the executable for some platforms. In particular, the ``.exe`` (or other) ++ extension should be omitted for Windows programs. ++ ++.. describe:: regexp ++ ++ A regular expression. Quotes should not be included. ++ ++.. describe:: samp ++ ++ A piece of literal text, such as code. Within the contents, you can use ++ curly braces to indicate a "variable" part, as in ``:file:``. ++ ++ If you don't need the "variable part" indication, use the standard ++ ````code```` instead. ++ ++ ++The following roles generate external links: ++ ++.. describe:: pep ++ ++ A reference to a Python Enhancement Proposal. This generates appropriate ++ index entries. The text "PEP *number*\ " is generated; in the HTML output, ++ this text is a hyperlink to an online copy of the specified PEP. ++ ++.. describe:: rfc ++ ++ A reference to an Internet Request for Comments. This generates appropriate ++ index entries. The text "RFC *number*\ " is generated; in the HTML output, ++ this text is a hyperlink to an online copy of the specified RFC. ++ ++ ++Note that there are no special roles for including hyperlinks as you can use ++the standard reST markup for that purpose. ++ ++ ++.. _doc-ref-role: ++ ++Cross-linking markup ++-------------------- ++ ++To support cross-referencing to arbitrary sections in the documentation, the ++standard reST labels are "abused" a bit: Every label must precede a section ++title; and every label name must be unique throughout the entire documentation ++source. ++ ++You can then reference to these sections using the ``:ref:`label-name``` role. ++ ++Example:: ++ ++ .. _my-reference-label: ++ ++ Section to cross-reference ++ -------------------------- ++ ++ This is the text of the section. ++ ++ It refers to the section itself, see :ref:`my-reference-label`. ++ ++The ``:ref:`` invocation is replaced with the section title. ++ ++Alternatively, you can reference any label (not just section titles) ++if you provide the link text ``:ref:`link text ```. ++ ++Paragraph-level markup ++---------------------- ++ ++These directives create short paragraphs and can be used inside information ++units as well as normal text: ++ ++.. describe:: note ++ ++ An especially important bit of information about an API that a user should be ++ aware of when using whatever bit of API the note pertains to. The content of ++ the directive should be written in complete sentences and include all ++ appropriate punctuation. ++ ++ Example:: ++ ++ .. note:: ++ ++ This function is not suitable for sending spam e-mails. ++ ++.. describe:: warning ++ ++ An important bit of information about an API that a user should be aware of ++ when using whatever bit of API the warning pertains to. The content of the ++ directive should be written in complete sentences and include all appropriate ++ punctuation. In the interest of not scaring users away from pages filled ++ with warnings, this directive should only be chosen over ``note`` for ++ information regarding the possibility of crashes, data loss, or security ++ implications. ++ ++.. describe:: versionadded ++ ++ This directive documents the version of Python which added the described ++ feature, or a part of it, to the library or C API. When this applies to an ++ entire module, it should be placed at the top of the module section before ++ any prose. ++ ++ The first argument must be given and is the version in question; if the ++ addition is only part of the described API element, you should add a second ++ argument consisting of a *brief* explanation of the change. ++ ++ Example:: ++ ++ .. versionadded:: 3.1 ++ The *spam* parameter. ++ ++ Note that there must be no blank line between the directive head and the ++ explanation; this is to make these blocks visually continuous in the markup. ++ ++.. describe:: versionchanged ++ ++ Similar to ``versionadded``, but describes when and what changed in the named ++ feature in some way (changed side effects, platform support, etc.). This one ++ *must* have the second argument (explanation of the change). ++ ++-------------- ++ ++.. describe:: impl-detail ++ ++ This directive is used to mark CPython-specific information. Use either with ++ a block content or a single sentence as an argument, i.e. either :: ++ ++ .. impl-detail:: ++ ++ This describes some implementation detail. ++ ++ More explanation. ++ ++ or :: ++ ++ .. impl-detail:: This shortly mentions an implementation detail. ++ ++ "\ **CPython implementation detail:**\ " is automatically prepended to the ++ content. ++ ++.. describe:: seealso ++ ++ Many sections include a list of references to module documentation or ++ external documents. These lists are created using the ``seealso`` directive. ++ ++ The ``seealso`` directive is typically placed in a section just before any ++ sub-sections. For the HTML output, it is shown boxed off from the main flow ++ of the text. ++ ++ The content of the ``seealso`` directive should be a reST definition list. ++ Example:: ++ ++ .. seealso:: ++ ++ Module :mod:`zipfile` ++ Documentation of the :mod:`zipfile` standard module. ++ ++ `GNU tar manual, Basic Tar Format `_ ++ Documentation for tar archive files, including GNU tar extensions. ++ ++.. describe:: rubric ++ ++ This directive creates a paragraph heading that is not used to create a ++ table of contents node. It is currently used for the "Footnotes" caption. ++ ++.. describe:: centered ++ ++ This directive creates a centered boldfaced paragraph. Use it as follows:: ++ ++ .. centered:: ++ ++ Paragraph contents. ++ ++ ++Table-of-contents markup ++------------------------ ++ ++Since reST does not have facilities to interconnect several documents, or split ++documents into multiple output files, Sphinx uses a custom directive to add ++relations between the single files the documentation is made of, as well as ++tables of contents. The ``toctree`` directive is the central element. ++ ++.. describe:: toctree ++ ++ This directive inserts a "TOC tree" at the current location, using the ++ individual TOCs (including "sub-TOC trees") of the files given in the ++ directive body. A numeric ``maxdepth`` option may be given to indicate the ++ depth of the tree; by default, all levels are included. ++ ++ Consider this example (taken from the library reference index):: ++ ++ .. toctree:: ++ :maxdepth: 2 ++ ++ intro ++ strings ++ datatypes ++ numeric ++ (many more files listed here) ++ ++ This accomplishes two things: ++ ++ * Tables of contents from all those files are inserted, with a maximum depth ++ of two, that means one nested heading. ``toctree`` directives in those ++ files are also taken into account. ++ * Sphinx knows that the relative order of the files ``intro``, ++ ``strings`` and so forth, and it knows that they are children of the ++ shown file, the library index. From this information it generates "next ++ chapter", "previous chapter" and "parent chapter" links. ++ ++ In the end, all files included in the build process must occur in one ++ ``toctree`` directive; Sphinx will emit a warning if it finds a file that is ++ not included, because that means that this file will not be reachable through ++ standard navigation. ++ ++ The special file ``contents.rst`` at the root of the source directory is the ++ "root" of the TOC tree hierarchy; from it the "Contents" page is generated. ++ ++ ++Index-generating markup ++----------------------- ++ ++Sphinx automatically creates index entries from all information units (like ++functions, classes or attributes) like discussed before. ++ ++However, there is also an explicit directive available, to make the index more ++comprehensive and enable index entries in documents where information is not ++mainly contained in information units, such as the language reference. ++ ++The directive is ``index`` and contains one or more index entries. Each entry ++consists of a type and a value, separated by a colon. ++ ++For example:: ++ ++ .. index:: ++ single: execution; context ++ module: __main__ ++ module: sys ++ triple: module; search; path ++ ++This directive contains five entries, which will be converted to entries in the ++generated index which link to the exact location of the index statement (or, in ++case of offline media, the corresponding page number). ++ ++The possible entry types are: ++ ++single ++ Creates a single index entry. Can be made a subentry by separating the ++ subentry text with a semicolon (this notation is also used below to describe ++ what entries are created). ++pair ++ ``pair: loop; statement`` is a shortcut that creates two index entries, ++ namely ``loop; statement`` and ``statement; loop``. ++triple ++ Likewise, ``triple: module; search; path`` is a shortcut that creates three ++ index entries, which are ``module; search path``, ``search; path, module`` and ++ ``path; module search``. ++module, keyword, operator, object, exception, statement, builtin ++ These all create two index entries. For example, ``module: hashlib`` ++ creates the entries ``module; hashlib`` and ``hashlib; module``. The ++ builtin entry type is slightly different in that "built-in function" is used ++ in place of "builtin" when creating the two entries. ++ ++For index directives containing only "single" entries, there is a shorthand ++notation:: ++ ++ .. index:: BNF, grammar, syntax, notation ++ ++This creates four index entries. ++ ++ ++Grammar production displays ++--------------------------- ++ ++Special markup is available for displaying the productions of a formal grammar. ++The markup is simple and does not attempt to model all aspects of BNF (or any ++derived forms), but provides enough to allow context-free grammars to be ++displayed in a way that causes uses of a symbol to be rendered as hyperlinks to ++the definition of the symbol. There is this directive: ++ ++.. describe:: productionlist ++ ++ This directive is used to enclose a group of productions. Each production is ++ given on a single line and consists of a name, separated by a colon from the ++ following definition. If the definition spans multiple lines, each ++ continuation line must begin with a colon placed at the same column as in the ++ first line. ++ ++ Blank lines are not allowed within ``productionlist`` directive arguments. ++ ++ The definition can contain token names which are marked as interpreted text ++ (e.g. ``unaryneg ::= "-" `integer```) -- this generates cross-references ++ to the productions of these tokens. ++ ++ Note that no further reST parsing is done in the production, so that you ++ don't have to escape ``*`` or ``|`` characters. ++ ++ ++.. XXX describe optional first parameter ++ ++The following is an example taken from the Python Reference Manual:: ++ ++ .. productionlist:: ++ try_stmt: try1_stmt | try2_stmt ++ try1_stmt: "try" ":" `suite` ++ : ("except" [`expression` ["," `target`]] ":" `suite`)+ ++ : ["else" ":" `suite`] ++ : ["finally" ":" `suite`] ++ try2_stmt: "try" ":" `suite` ++ : "finally" ":" `suite` ++ ++ ++Substitutions ++------------- ++ ++The documentation system provides three substitutions that are defined by default. ++They are set in the build configuration file :file:`conf.py`. ++ ++.. describe:: |release| ++ ++ Replaced by the Python release the documentation refers to. This is the full ++ version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``. ++ ++.. describe:: |version| ++ ++ Replaced by the Python version the documentation refers to. This consists ++ only of the major and minor version parts, e.g. ``2.5``, even for version ++ 2.5.1. ++ ++.. describe:: |today| ++ ++ Replaced by either today's date, or the date set in the build configuration ++ file. Normally has the format ``April 14, 2007``. ++ ++ ++.. rubric:: Footnotes ++ ++.. [1] There is a standard ``.. include`` directive, but it raises errors if the ++ file is not found. This one only emits a warning. ++ ++ ++.. _building-doc: ++ ++Building the documentation ++========================== ++ ++The toolset used to build the docs is written in Python and is called Sphinx_. ++Sphinx is maintained separately and is not included in this tree. Also needed ++are docutils_, supplying the base markup that Sphinx uses; Jinja_, a templating ++engine; and optionally Pygments_, a code highlighter. ++ ++To build the documentation, follow the instructions from one of the sections ++below. You can view the documentation after building the HTML by pointing ++a browser at the file :file:`Doc/build/html/index.html`. ++ ++In the Python 2.7 and 3.3 branches, the Sphinx toolchain will be checked out ++using Subversion from ``svn.python.org`` by the Makefile. This toolchain will ++need an installed Python 2 to run. ++ ++In the Python 3.4 and later branches, you are expected to have installed a ++recent version of Sphinx on your system, so that the Makefile can find the ++``sphinx-build`` command. ++ ++ ++Using make / make.bat ++--------------------- ++ ++On Unix, run the following from the root of your :ref:`repository clone ++`:: ++ ++ cd Doc ++ make html ++ ++or alternatively ``make -C Doc html``. This builds the output as HTML. ++ ++For Windows users there is a :file:`make.bat` batchfile that tries to work like ++``make`` does. ++ ++Available :command:`make` targets are: ++ ++ * "html", which builds standalone HTML files for offline viewing. ++ ++ * "htmlhelp", which builds HTML files and a HTML Help project file usable to ++ convert them into a single Compiled HTML (.chm) file -- these are popular ++ under Microsoft Windows, but very handy on every platform. ++ ++ To create the CHM file, you need to run the Microsoft HTML Help Workshop ++ over the generated project (.hhp) file. ++ ++ * "latex", which builds LaTeX source files as input to "pdflatex" to produce ++ PDF documents. ++ ++ * "text", which builds a plain text file for each source file. ++ ++ * "linkcheck", which checks all external references to see whether they are ++ broken, redirected or malformed, and outputs this information to stdout ++ as well as a plain-text (.txt) file. ++ ++ * "changes", which builds an overview over all versionadded/versionchanged/ ++ deprecated items in the current version. This is meant as a help for the ++ writer of the "What's New" document. ++ ++ * "coverage", which builds a coverage overview for standard library modules ++ and C API. ++ ++ * "pydoc-topics", which builds a Python module containing a dictionary with ++ plain text documentation for the labels defined in ++ :file:`Doc/tools/sphinxext/pyspecific.py` -- pydoc needs these to show topic ++ and keyword help. ++ ++ * "suspicious", which checks the parsed markup for text that looks like ++ malformed and thus unconverted reST. ++ ++ ++Without make ++------------ ++ ++Install the Sphinx package and its dependencies from PyPI. ++ ++Then, from the ``Docs`` directory, run :: ++ ++ sphinx-build -b . build/ ++ ++where ```` is one of html, text, latex, or htmlhelp (for explanations ++see the make targets above). ++ ++.. _docutils: http://docutils.sourceforge.net/ ++.. _Jinja: http://jinja.pocoo.org/ ++.. _Pygments: http://pygments.org/ ++.. _Sphinx: http://sphinx-doc.org/ +diff -r 85f290e474e2 build/_sources/emacs.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/emacs.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,32 @@ ++.. _emacs: ++ ++============= ++Emacs support ++============= ++ ++If you want to edit Python code in Emacs, you should download python-mode.el ++and install it somewhere on your load-path. See the project page to download: ++https://launchpad.net/python-mode ++ ++While Emacs comes with a python.el file, it is not recommended. ++python-mode.el is maintained by core Python developers and is generally ++considered more Python programmer friendly. For example, python-mode.el ++includes a killer feature called `pdbtrack` which allows you to set a pdb ++breakpoint in your code, run your program in an Emacs shell buffer, and do gud ++style debugging when the breakpoint is hit. ++ ++python-mode.el is compatible with both GNU Emacs from the FSF, and XEmacs. ++ ++For more information and bug reporting, see the above project page. For help, ++development, or discussions, see the python-mode mailing list: ++http://mail.python.org/mailman/listinfo/python-mode ++ ++ ++.. ++ Local Variables: ++ mode: indented-text ++ indent-tabs-mode: nil ++ sentence-end-double-space: t ++ fill-column: 78 ++ coding: utf-8 ++ End: +diff -r 85f290e474e2 build/_sources/experts.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/experts.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,338 @@ ++.. _experts: ++ ++Experts Index ++================= ++ ++This document has tables that list Python Modules, Tools, Platforms and ++Interest Areas and names for each item that indicate a maintainer or an ++expert in the field. This list is intended to be used by issue submitters, ++issue triage people, and other issue participants to find people to add to ++the nosy list or to contact directly by email for help and decisions on ++feature requests and bug fixes. People on this list may be asked to render ++final judgement on a feature or bug. If no active maintainer is listed for ++a given module, then questionable changes should go to python-dev, while ++any other issues can and should be decided by any committer. ++ ++Unless a name is followed by a '*', you should never assign an issue to ++that person, only make them nosy. Names followed by a '*' may be assigned ++issues involving the module or topic. ++ ++.. TODO document automatic assignment/nosy: people need not add them manually ++ ++The Platform and Interest Area tables list broader fields in which various ++people have expertise. These people can also be contacted for help, ++opinions, and decisions when issues involve their areas. ++ ++If a listed maintainer does not respond to requests for comment for an ++extended period (three weeks or more), they should be marked as inactive ++in this list by placing the word 'inactive' in parenthesis behind their ++tracker id. They are of course free to remove that inactive mark at ++any time. ++ ++Committers should update these tables as their areas of expertise widen. ++New topics may be added to the Interest Area table at will. ++ ++The existence of this list is not meant to indicate that these people ++*must* be contacted for decisions; it is, rather, a resource to be used ++by non-committers to find responsible parties, and by committers who do ++not feel qualified to make a decision in a particular context. ++ ++See also :PEP:`291` and :PEP:`360` for information about certain modules ++with special rules. ++ ++ ++Stdlib ++------ ++==================== ============================================= ++Module Maintainers ++==================== ============================================= ++__future__ ++__main__ gvanrossum, ncoghlan ++_dummy_thread brett.cannon ++_thread pitrou ++abc ++aifc r.david.murray ++argparse bethard ++array ++ast benjamin.peterson ++asynchat josiahcarlson, giampaolo.rodola, stutzbach ++asyncio gvanrossum, haypo, pitrou, yselivanov ++asyncore josiahcarlson, giampaolo.rodola, stutzbach ++atexit ++audioop ++base64 ++bdb ++binascii ++binhex ++bisect rhettinger ++builtins ++bz2 nadeem.vawda ++calendar rhettinger ++cgi ++cgitb ++chunk ++cmath mark.dickinson ++cmd ++code ++codecs lemburg, doerwalter ++codeop ++collections rhettinger ++collections.abc rhettinger, stutzbach ++colorsys ++compileall ++concurrent.futures bquinlan ++configparser lukasz.langa* ++contextlib ncoghlan* ++copy alexandre.vassalotti ++copyreg alexandre.vassalotti ++cProfile ++crypt jafo* ++csv skip.montanaro (inactive) ++ctypes theller (inactive), belopolsky, amaury.forgeotdarc, ++ meador.inge ++curses ++datetime belopolsky ++dbm ++decimal facundobatista, rhettinger, mark.dickinson ++difflib tim.peters (inactive) ++dis ncoghlan* ++distutils eric.araujo ++doctest tim.peters (inactive) ++dummy_threading brett.cannon ++email barry, r.david.murray* ++encodings lemburg, loewis ++enum eli.bendersky*, barry, ethan.furman* ++errno ++exceptions ++fcntl ++filecmp ++fileinput ++fnmatch ++formatter ++fpectl ++fractions mark.dickinson, rhettinger ++ftplib giampaolo.rodola ++functools ncoghlan, rhettinger ++gc pitrou ++getopt ++getpass ++gettext loewis ++glob ++grp ++gzip ++hashlib christian.heimes, gregory.p.smith ++heapq rhettinger, stutzbach ++hmac christian.heimes, gregory.p.smith ++html ezio.melotti ++http ++idlelib kbk, terry.reedy, roger.serwy ++imaplib ++imghdr ++imp ++importlib brett.cannon ++inspect yselivanov ++io pitrou, benjamin.peterson, stutzbach ++ipaddress pmoody, ncoghlan ++itertools rhettinger ++json bob.ippolito (inactive), ezio.melotti, rhettinger, pitrou ++keyword ++lib2to3 benjamin.peterson ++linecache ++locale loewis, lemburg ++logging vinay.sajip ++lzma nadeem.vawda ++macpath ++mailbox petri.lehtinen ++mailcap ++marshal ++math mark.dickinson, rhettinger, stutzbach ++mimetypes ++mmap ++modulefinder theller (inactive), jvr ++msilib loewis ++msvcrt ++multiprocessing jnoller, sbt* ++netrc ++nis ++nntplib pitrou ++numbers ++operator ++optparse aronacher ++os loewis ++ossaudiodev ++parser benjamin.peterson ++pathlib pitrou* ++pdb georg.brandl* ++pickle alexandre.vassalotti, pitrou ++pickletools alexandre.vassalotti ++pipes ++pkgutil ++platform lemburg ++plistlib ++poplib giampaolo.rodola ++posix ++pprint fdrake ++profile georg.brandl ++pstats georg.brandl ++pty ++pwd ++py_compile ++pybench lemburg, pitrou ++pyclbr ++pydoc ++queue rhettinger ++quopri ++random rhettinger, mark.dickinson ++re effbot (inactive), pitrou, ezio.melotti ++readline ++reprlib ++resource ++rlcompleter ++runpy ncoghlan ++sched giampaolo.rodola ++select ++selectors ++shelve ++shlex ++shutil tarek, hynek ++signal ++site ++smtpd giampaolo.rodola ++smtplib ++sndhdr ++socket pitrou ++socketserver ++spwd ++sqlite3 ghaering ++ssl janssen, pitrou, giampaolo.rodola, christian.heimes ++stat christian.heimes ++statistics ++string georg.brandl* ++stringprep ++struct mark.dickinson, meador.inge ++subprocess astrand (inactive) ++sunau ++symbol ++symtable benjamin.peterson ++sys ++sysconfig tarek ++syslog jafo* ++tabnanny tim.peters (inactive) ++tarfile lars.gustaebel ++telnetlib ++tempfile georg.brandl, ncoghlan ++termios ++test ezio.melotti ++textwrap georg.brandl ++threading pitrou ++time belopolsky ++timeit georg.brandl ++tkinter gpolo ++token georg.brandl ++tokenize meador.inge ++trace belopolsky ++traceback georg.brandl* ++tty ++turtle gregorlingl ++types ++unicodedata loewis, lemburg, ezio.melotti ++unittest michael.foord*, ezio.melotti ++unittest.mock michael.foord* ++urllib orsenthil ++uu ++uuid ++venv vinay.sajip ++warnings ++wave ++weakref fdrake, pitrou ++webbrowser georg.brandl ++winreg stutzbach ++winsound effbot (inactive) ++wsgiref pje ++xdrlib ++xml.dom ++xml.dom.minidom ++xml.dom.pulldom ++xml.etree effbot (inactive), eli.bendersky*, scoder ++xml.parsers.expat christian.heimes ++xml.sax christian.heimes ++xml.sax.handler ++xml.sax.saxutils ++xml.sax.xmlreader ++xmlrpc loewis ++zipfile alanmcintyre ++zipimport ++zlib nadeem.vawda ++==================== ============================================= ++ ++ ++Tools ++----- ++================== =========== ++Tool Maintainers ++================== =========== ++pybench lemburg ++================== =========== ++ ++ ++Platforms ++--------- ++=================== =========== ++Platform Maintainers ++=================== =========== ++AIX David.Edelsohn ++Cygwin jlt63, stutzbach ++FreeBSD ++HP-UX ++Linux ++Mac OS X ronaldoussoren, ned.deily, hynek ++NetBSD1 ++OS2/EMX aimacintyre ++Solaris/OpenIndiana jcea ++Windows tim.golden ++JVM/Java frank.wierzbicki ++=================== =========== ++ ++ ++Miscellaneous ++------------- ++================== =========== ++Interest Area Maintainers ++================== =========== ++algorithms ++ast/compiler ncoghlan, benjamin.peterson, brett.cannon, georg.brandl ++autoconf/makefiles ++bsd ++benchmarks pitrou, brett.cannon ++bug tracker ezio.melotti ++buildbots pitrou ++bytecode benjamin.peterson, pitrou, georg.brandl ++context managers ncoghlan ++coverity scan christian.heimes, brett.cannon ++cryptography christian.heimes, gregory.p.smith ++data formats mark.dickinson, georg.brandl ++database lemburg ++devguide ncoghlan, eric.araujo, ezio.melotti ++documentation georg.brandl, ezio.melotti, eric.araujo ++GUI ++i18n lemburg, eric.araujo ++import machinery brett.cannon, ncoghlan, eric.snow ++io pitrou, benjamin.peterson, stutzbach, hynek ++locale lemburg, loewis ++mathematics mark.dickinson, eric.smith, lemburg, stutzbach ++memory management tim.peters, lemburg ++networking giampaolo.rodola, pitrou ++object model benjamin.peterson ++packaging tarek, lemburg, alexis, eric.araujo ++py3 transition benjamin.peterson ++release management tarek, lemburg, benjamin.peterson, barry, loewis, ++ gvanrossum, anthonybaxter, eric.araujo, ned.deily, ++ georg.brandl ++str.format eric.smith ++testing michael.foord, pitrou, ezio.melotti ++test coverage ncoghlan, giampaolo.rodola, christian.heimes ++threads pitrou ++time and dates lemburg, belopolsky ++unicode lemburg, ezio.melotti, haypo, benjamin.peterson, pitrou ++version control eric.araujo, georg.brandl, ezio.melotti ++================== =========== +diff -r 85f290e474e2 build/_sources/faq.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/faq.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,996 @@ ++:tocdepth: 2 ++ ++.. _faq: ++ ++Python Developer FAQ ++~~~~~~~~~~~~~~~~~~~~ ++ ++.. contents:: ++ :local: ++ ++ ++Communications ++============== ++ ++ ++Where should I ask general Python questions? ++-------------------------------------------- ++ ++General Python questions should still go to `python-list`_ or `tutor`_ ++or similar resources, such as StackOverflow_ or the ``#python`` IRC channel ++on Freenode_. ++ ++.. _python-list: http://mail.python.org/mailman/listinfo/python-list ++.. _tutor: http://mail.python.org/mailman/listinfo/tutor ++.. _StackOverflow: http://stackoverflow.com/ ++.. _Freenode: http://freenode.net/ ++ ++ ++.. index:: ++ single: PEP process; in FAQ ++ ++.. _suggesting-changes: ++ ++Where should I suggest new features and language changes? ++--------------------------------------------------------- ++ ++The `python-ideas`_ mailing list is specifically intended for discussion of ++new features and language changes. Please don't be disappointed if your ++idea isn't met with universal approval: as the long list of Rejected and ++Withdrawn PEPs in the `PEP Index`_ attests, and as befits a reasonably mature ++programming language, getting significant changes into Python isn't a simple ++task. ++ ++If the idea is reasonable, someone will suggest posting it as a feature ++request on the `issue tracker`_, or, for larger changes, writing it up as ++a `draft PEP`_. ++ ++Sometimes core developers will differ in opinion, or merely be collectively ++unconvinced. When there isn't an obvious victor then the ++`Status Quo Wins a Stalemate`_ as outlined in the linked post. ++ ++For some examples on language changes that were accepted please read ++`Justifying Python Language Changes`_. ++ ++See also the :ref:`langchanges` section of this guide. ++ ++.. _python-ideas: http://mail.python.org/mailman/listinfo/python-ideas ++.. _issue tracker: http://bugs.python.org ++.. _PEP Index: http://www.python.org/dev/peps ++.. _draft PEP: http://www.python.org/dev/peps/pep-0001/ ++.. _Status Quo Wins a Stalemate: http://www.curiousefficiency.org/posts/2011/02/status-quo-wins-stalemate.html ++.. _Justifying Python Language Changes: http://www.curiousefficiency.org/posts/2011/02/justifying-python-language-changes.html ++ ++Where should I ask general questions about contributing to CPython? ++------------------------------------------------------------------- ++ ++The `Python Mentors`_ program is specifically about encouraging ++developers and others that would like to contribute to Python development in ++general, rather than necessarily being focused on one particular issue. ++Some core developers are also available on the ``#python-dev`` IRC channel on ++Freenode_. ++ ++.. _Python Mentors: http://pythonmentors.com ++ ++ ++Where should I report specific problems? ++---------------------------------------- ++ ++Specific problems should be posted to the `issue tracker`_. ++ ++ ++What if I'm not sure it is a bug? ++--------------------------------- ++ ++The general Python help locations listed above are the best place to start ++with that kind of question. If they agree it looks like a bug, then the ++next step is to either post it to the `issue tracker`_ or else to ask further ++on the core development mailing list, `python-dev`_. ++ ++.. _python-dev: http://mail.python.org/mailman/listinfo/python-dev ++ ++ ++What if I disagree with an issue resolution on the tracker? ++----------------------------------------------------------- ++ ++First, take some time to consider any comments made in association with the ++resolution of the tracker issue. On reflection, they may seem more reasonable ++than they first appeared. ++ ++If you still feel the resolution is incorrect, then raise the question on ++`python-dev`_. If the consensus there supports the disputed resolution, please ++take any further objections to `python-ideas`_ (or some other forum). Further ++argument on `python-dev`_ after a consensus has been reached amongst the core ++developers is unlikely to win any converts. ++ ++ ++How do I tell who is and isn't a core developer? ++------------------------------------------------ ++ ++You can check their name against the `full list of developers`_ with commit ++rights to the main source control repository. ++ ++On the `issue tracker`_, most core developers will have the Python logo ++appear next to their name. ++ ++.. _full list of developers: http://hg.python.org/committers.txt ++ ++ ++What standards of behaviour are expected in these communication channels? ++------------------------------------------------------------------------- ++ ++We try to foster environments of mutual respect, tolerance and encouragement, ++as described in the PSF's `Diversity Statement`_. Abiding by the guidelines ++in this document and asking questions or posting suggestions in the ++appropriate channels are an excellent way to get started on the mutual respect ++part, greatly increasing the chances of receiving tolerance and encouragement ++in return. ++ ++.. _Diversity Statement: http://www.python.org/psf/diversity/ ++ ++ ++Version Control ++=============== ++ ++For everyone ++------------ ++ ++The following FAQs are intended for both core developers and contributors. ++ ++Where can I learn about the version control system used, Mercurial (hg)? ++'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++Mercurial_'s (also known as ``hg``) official web site is at ++http://mercurial.selenic.com/. A book on Mercurial published by ++`O'Reilly Media`_, `Mercurial: The Definitive Guide`_, is available ++for free online. Another resource is `Hg Init: a Mercurial tutorial`_ ++by Joel Spolsky. ++ ++With Mercurial installed, you can run the help tool that comes with ++Mercurial to get help:: ++ ++ hg help ++ ++The `man page`_ for ``hg`` provides a quick refresher on the details of ++various commands, but doesn't provide any guidance on overall ++workflow. ++ ++.. _Mercurial: http://mercurial.selenic.com/ ++.. _O'Reilly Media: http://www.oreilly.com/ ++.. _Mercurial\: The Definitive Guide: http://hgbook.red-bean.com/ ++.. _man page: http://www.selenic.com/mercurial/hg.1.html ++.. _Hg Init\: a Mercurial tutorial: http://hginit.com/ ++ ++ ++I already know how to use Git, can I use that instead? ++'''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++While the main workflow for core developers requires Mercurial, if ++you just want to generate patches with ``git diff`` and post them to the ++`issue tracker`_, Petri Lehtinen maintains a `git mirror`_ of the main ++`CPython repository`_. To create a local clone based on this mirror rather ++than the main repository:: ++ ++ git clone git://github.com/akheron/cpython ++ ++The mirror's master branch tracks the main repository's default branch, ++while the maintenance branch names (``2.7``, ``3.3``, etc) are mapped ++directly. ++ ++.. _git mirror: http://github.com/akheron/cpython ++.. _CPython repository: http://hg.python.org/cpython ++ ++Please only use this approach if you're already an experienced Git user and ++don't require assistance with the specifics of version control commands. All ++other parts of this developer's guide assume the use of Mercurial for local ++version control. ++ ++ ++What do I need to use Mercurial? ++'''''''''''''''''''''''''''''''' ++ ++UNIX ++^^^^ ++ ++First, you need to `download Mercurial`_. Most UNIX-based operating systems ++have binary packages available. Most package management systems also ++have native Mercurial packages available. ++ ++If you have push rights, you need OpenSSH_. This is needed to verify ++your identity when performing commits. As with Mercurial, binary packages ++are typically available either online or through the platform's package ++management system. ++ ++Mercurial does not use its own compression via SSH ++because it is better to enable compression at the SSH level. Enabling ++SSH compression can make cloning a remote repository much faster. ++You can configure it in your ``~/.ssh/config`` file; for example:: ++ ++ Host hg.python.org ++ Compression yes ++ ++.. _download Mercurial: http://mercurial.selenic.com/downloads/ ++.. _OpenSSH: http://www.openssh.org/ ++ ++ ++Windows ++^^^^^^^ ++ ++The recommended option on Windows is to `download TortoiseHg`_ which ++integrates with Windows Explorer and also bundles the command line client ++(meaning you can type ``hg`` in a DOS box). Note that most ++entries in this FAQ only cover the command line client in detail - refer ++to the TortoiseHg documentation for assistance with its graphical interface. ++ ++If you have push rights, you need to configure Mercurial to work with ++your SSH keys. For that, open your Mercurial configuration file ++(you can do so by opening the TortoiseHg Global Settings dialog and then ++clicking *"Edit File"*). If there is no ``[ui]`` section, create it by ++typing just that on a line by itself. Then add the following line:: ++ ++ ssh = TortoisePlink.exe -ssh -2 -C -i C:\path\to\yourkey.ppk ++ ++where ``C:\path\to\yourkey.ppk`` should be replaced with the actual path ++to your SSH private key. ++ ++.. note:: ++ If your private key is in OpenSSH format, you must first convert it to ++ PuTTY format by loading it into `PuTTYgen`_. ++ ++.. _download TortoiseHg: http://tortoisehg.bitbucket.org/download/index.html ++ ++ ++What's a working copy? What's a repository? ++''''''''''''''''''''''''''''''''''''''''''' ++ ++Mercurial is a "distributed" version control system. This means that each ++participant, even casual contributors, download a complete copy (called a ++*clone*, since it is obtained by calling ``hg clone``) of the central ++repository which can be treated as a stand-alone repository for all purposes. ++That copy is called in the FAQ the *local repository*, to differentiate ++with any *remote repository* you might also interact with. ++ ++But you don't modify files directly in the local repository; Mercurial doesn't ++allow for it. You modify files in what's called the *working copy* associated ++with your local repository: you also run compilations and tests there. ++Once you are satisfied with your changes, you can :ref:`commit them `; ++committing records the changes as a new *revision* in the *local repository*. ++ ++Changes in your *local repository* don't get automatically shared with the ++rest of the world. Mercurial ensures that you have to do so explicitly ++(this allows you to experiment quite freely with multiple branches of ++development, all on your private computer). The main commands for doing ++so are ``hg pull`` and ``hg push``. ++ ++ ++Which branches are in my local repository? ++'''''''''''''''''''''''''''''''''''''''''' ++ ++Typing ``hg branches`` displays the open branches in your local repository:: ++ ++ $ hg branches ++ default 86781:52ec6a3eeda5 ++ 2.7 86776:dd12639b82bf ++ 3.3 86779:544b654d000c (inactive) ++ 3.2 86778:dda1a32748e0 (inactive) ++ 3.1 86777:b1ddcb220a7f (inactive) ++ ++Why are some branches marked "inactive"? ++'''''''''''''''''''''''''''''''''''''''' ++ ++Assuming you get the following output:: ++ ++ $ hg branches ++ default 68042:8ff33af017ef ++ 3.3 68039:c17d7772c638 (inactive) ++ ++This means all changesets in the "3.3" branch have been merged into the ++"default" branch (or any other branch, if such exists). ++ ++ ++.. _hg-current-branch: ++ ++Which branch is currently checked out in my working copy? ++''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++Use:: ++ ++ $ hg branch ++ default ++ ++Or to get more information:: ++ ++ $ hg summary ++ parent: 68026:f12ef116dd10 tip ++ In FTP.close() method, make sure to also close the socket object, not only the file. ++ branch: default ++ commit: (clean) ++ update: (current) ++ ++ ++.. _hg-switch-branches: ++ ++How do I switch between branches inside my working copy? ++'''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++Simply use ``hg update`` to checkout another branch in the current directory:: ++ ++ $ hg branch ++ default ++ $ hg update 3.3 ++ 86 files updated, 0 files merged, 11 files removed, 0 files unresolved ++ $ hg branch ++ 3.3 ++ ++Adding the ``-v`` option to ``hg update`` will list all updated files. ++ ++Note that, due to some previously built executables being used as a part of ++the build process, you may sometimes run into issues when attempting to ++switch between Python 2.x and Python 3.x branches. In these cases, it is ++best to run a ``make distclean`` to ensure that all previously built files ++are removed. ++ ++ ++I want to keep a separate working copy per development branch, is it possible? ++'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++There are two ways: ++ ++1) Use the "`share extension`_" as described in the :ref:`multiple-clones` ++ section; ++2) Create several clones of your local repository; ++ ++If you want to use the second way, you can do:: ++ ++ $ hg clone cpython py33 ++ updating to branch default ++ 3434 files updated, 0 files merged, 0 files removed, 0 files unresolved ++ $ cd py33 ++ $ hg update 3.3 ++ 86 files updated, 0 files merged, 11 files removed, 0 files unresolved ++ ++The current branch in a working copy is "sticky": if you pull in some new ++changes, ``hg update`` will update to the head of the *current branch*. ++ ++.. _share extension: http://mercurial.selenic.com/wiki/ShareExtension ++ ++ ++.. _hg-paths: ++ ++How do I link my local repository to a particular remote repository? ++'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++Your local repository is linked by default to the remote repository it ++was *cloned* from. If you created it from scratch, however, it is not linked ++to any remote repository. In ``.hg/hgrc`` file for the local repository, add ++or modify the following section:: ++ ++ [paths] ++ default = ssh://hg@hg.python.org/devguide ++ ++This example is for a local repository that mirrors the ``devguide`` repository ++on ``hg.python.org``. The same approach works for other remote repositories. ++ ++Anywhere that ```` is used in the commands in this ++FAQ, ``hg`` will use the default remote repository if you omit the parameter. ++ ++ ++How do I create a shorthand alias for a remote repository? ++'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++In your global ``.hgrc`` file add a section similar to the following:: ++ ++ [paths] ++ dg = ssh://hg@hg.python.org/devguide ++ ++This example creates a ``dg`` alias for the ``devguide`` repository ++on ``hg.python.org``. This allows "dg" to be entered instead of the ++full URL for commands taking a repository argument (e.g. ``hg pull dg`` or ++``hg outgoing dg``). ++ ++Anywhere that ```` is used in the commands in this ++FAQ, ``hg`` should accept an alias in place of a complete remote URL. ++ ++ ++How do I compare my local repository to a remote repository? ++'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++To display the list of changes that are in your local repository, but not ++in the remote, use:: ++ ++ hg outgoing ++ ++This is the list of changes that will be sent if you call ++``hg push ``. It does **not** include any :ref:`uncommitted ++changes ` in your working copy! ++ ++Conversely, for the list of changes that are in the remote repository but ++not in the local, use:: ++ ++ hg incoming ++ ++This is the list of changes that will be retrieved if you call ++``hg pull ``. ++ ++.. note:: ++ In most daily use, you will work against the default remote repository, ++ and therefore simply type ``hg outgoing`` and ``hg incoming``. ++ ++ In this case, you can also get a synthetic summary using ++ ``hg summary --remote``. ++ ++ ++How do I update my local repository to be in sync with a remote repository? ++''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++Run:: ++ ++ hg pull ++ ++from the repository you wish to pull the latest changes into. Most of the ++time, that repository is a clone of the repository you want to pull from, ++so you can simply type:: ++ ++ hg pull ++ ++This doesn't update your working copy, though. See below: ++ ++ ++How do I update my working copy with the latest changes? ++'''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++Do:: ++ ++ hg update ++ ++This will update your working copy with the latest changes on the ++:ref:`current branch `. If you had :ref:`uncommitted ++changes ` in your working copy, they will be merged in. ++ ++If you find yourself typing often ``hg pull`` followed by ``hg update``, ++be aware that you can combine them in a single command:: ++ ++ hg pull -u ++ ++ ++.. _hg-local-workflow: ++ ++How do I apply a patch? ++''''''''''''''''''''''' ++ ++If you want to try out or review a patch generated using Mercurial, do:: ++ ++ patch -p1 < somework.patch ++ ++This will apply the changes in your working copy without committing them. ++If the patch was not created by Mercurial (for example, a patch created by ++Subversion and thus lacking any ``a``/``b`` directory prefixes in the patch), ++replace ``-p1`` with ``-p0``. ++ ++If the patch contains renames, deletions or copies, and you intend committing ++it after your review, you might prefer using:: ++ ++ hg import --no-commit somework.patch ++ ++If you want to work on the patch using mq_ (Mercurial Queues), type instead:: ++ ++ hg qimport somework.patch ++ ++This will create a patch in your queue with a name that matches the filename. ++You can use the ``-n`` argument to specify a different name. To have the ++patch applied to the working copy, type:: ++ ++ hg qpush ++ ++Finally, to delete the patch, first un-apply it if necessary using ``hg qpop``, ++then do:: ++ ++ hg qdelete somework.patch ++ ++.. _extended diff format: http://www.selenic.com/mercurial/hg.1.html#diffs ++.. _mq: http://mercurial.selenic.com/wiki/MqExtension ++ ++ ++.. _merge-patch: ++ ++How do I solve conflicts when applying a patch fails? ++''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++The standard ``patch`` command, as well as ``hg import``, will produce ++unhelpful ``*.rej`` files when it fails applying parts of a patch. ++We suggest you try the mpatch_ utility, which can help resolve a number of ++common causes of patch rejects. ++ ++To make use of ``mpatch`` transparent, you can define a shell alias in one ++of your startup files. For example, if you want it to open the ``kdiff3`` ++merge program to fix failing patch hunks:: ++ ++ alias patch='mpatch --merge=kdiff3' ++ ++or if you want it to automatically solve conflicts by using heuristics:: ++ ++ alias patch='mpatch --auto --no-merge' ++ ++.. _mpatch: http://oss.oracle.com/~mason/mpatch/ ++ ++ ++How do I add a file or directory to the repository? ++''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++Simply specify the path to the file or directory to add and run:: ++ ++ hg add PATH ++ ++If ``PATH`` is a directory, Mercurial will recursively add any files in that ++directory and its descendants. ++ ++If you want Mercurial to figure out by itself which files should be added ++and/or removed, just run:: ++ ++ hg addremove ++ ++**Be careful** though, as it might add some files that are not desired in ++the repository (such as build products, cache files, or other data). ++ ++You will then need to run ``hg commit`` (as discussed below) to commit ++the file(s) to your local repository. ++ ++ ++What's the best way to split a file into several files? ++''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++To split a file into several files (e.g. a module converted to a package or a ++long doc file divided in two separate documents) use ``hg copy``:: ++ ++ hg copy module.rst module2.rst ++ ++and then remove the parts that are not necessary from ``module.rst`` and ++``module2.rst``. This allows Mercurial to know that the content of ++``module2.rst`` used to be in ``module.rst``, and will make subsequent merges ++easier. If necessary, you can also use ``hg copy`` several times. ++ ++If you simply create ``module2.rst``, add it with ``hg add``, and copy part of ++the content from ``module.rst``, Mercurial won't know that the two file are ++related. ++ ++ ++How do I delete a file or directory in the repository? ++'''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++Specify the path to be removed with:: ++ ++ hg remove PATH ++ ++This will remove the file or the directory from your working copy; you will ++have to :ref:`commit your changes ` for the removal to be recorded ++in your local repository. ++ ++ ++.. _hg-status: ++ ++What files are modified in my working copy? ++''''''''''''''''''''''''''''''''''''''''''' ++ ++Running:: ++ ++ hg status ++ ++will list any pending changes in the working copy. These changes will get ++committed to the local repository if you issue an ``hg commit`` without ++specifying any path. ++ ++Some ++key indicators that can appear in the first column of output are: ++ ++ = =========================== ++ A Scheduled to be added ++ R Scheduled to be removed ++ M Modified locally ++ ? Not under version control ++ = =========================== ++ ++If you want a line-by-line listing of the differences, use:: ++ ++ hg diff ++ ++ ++How do I revert a file I have modified back to the version in the repository? ++''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++Running:: ++ ++ hg revert PATH ++ ++will revert ``PATH`` to its version in the repository, throwing away any ++changes you made locally. If you run:: ++ ++ hg revert -a ++ ++from the root of your working copy it will recursively restore everything ++to match up with the repository. ++ ++ ++How do I find out who edited or what revision changed a line last? ++'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++You want:: ++ ++ hg annotate PATH ++ ++This will output to stdout every line of the file along with which revision ++last modified that line. When you have the revision number, it is then ++easy to :ref:`display it in detail `. ++ ++ ++.. _hg-log: ++ ++How can I see a list of log messages for a file or specific revision? ++''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++To see the history of changes for a specific file, run:: ++ ++ hg log -v [PATH] ++ ++That will list all messages of revisions which modified the file specified ++in ``PATH``. If ``PATH`` is omitted, all revisions are listed. ++ ++If you want to display line-by-line differences for each revision as well, ++add the ``-p`` option:: ++ ++ hg log -vp [PATH] ++ ++.. _hg-log-rev: ++ ++If you want to view the differences for a specific revision, run:: ++ ++ hg log -vp -r ++ ++ ++How can I see the changeset graph in my repository? ++''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++In Mercurial repositories, changesets don't form a simple list, but rather ++a graph: every changeset has one or two parents (it's called a merge changeset ++in the latter case), and can have any number of children. ++ ++The graphlog_ extension is very useful for examining the structure of the ++changeset graph. It is bundled with Mercurial. ++ ++Graphical tools, such as TortoiseHG, will display the changeset graph ++by default. ++ ++.. _graphlog: http://mercurial.selenic.com/wiki/GraphlogExtension ++ ++ ++How do I update to a specific release tag? ++'''''''''''''''''''''''''''''''''''''''''' ++ ++Run:: ++ ++ hg tags ++ ++to get a list of tags. To update your working copy to a specific tag, use:: ++ ++ hg update ++ ++ ++How do I find which changeset introduced a bug or regression? ++''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++``hg bisect``, as the name indicates, helps you do a bisection of a range of ++changesets. ++ ++You need two changesets to start the search: one that is "good" ++(doesn't have the bug), and one that is "bad" (has the bug). Usually, you ++have just noticed the bug in your working copy, so you can start with:: ++ ++ hg bisect --bad ++ ++Then you must ``update`` to a previous changeset that doesn't have the bug. ++You can conveniently choose a faraway changeset (for example a former release), ++and check that it is indeed "good". Then type:: ++ ++ hg bisect --good ++ ++Mercurial will automatically bisect so as to narrow the range of possible ++culprits, until a single changeset is isolated. Each time Mercurial presents ++you with a new changeset, re-compile Python and run the offending test, for ++example:: ++ ++ make -j2 ++ ./python -m test -uall test_sometest ++ ++Then, type either ``hg bisect --good`` or ``hg bisect --bad`` depending on ++whether the test succeeded or failed. ++ ++ ++How come feature XYZ isn't available in Mercurial? ++'''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++Mercurial comes with many bundled extensions which can be explicitly enabled. ++You can get a list of them by typing ``hg help extensions``. Some of these ++extensions, such as ``color``, can prettify output; others, such as ``fetch`` ++or ``graphlog``, add new Mercurial commands. ++ ++There are also many `configuration options`_ to tweak various aspects of the ++command line and other Mercurial behaviour; typing `man hgrc`_ displays ++their documentation inside your terminal. ++ ++In the end, please refer to the Mercurial `wiki`_, especially the pages about ++`extensions`_ (including third-party ones) and the `tips and tricks`_. ++ ++ ++.. _man hgrc: http://www.selenic.com/mercurial/hgrc.5.html ++.. _wiki: http://mercurial.selenic.com/wiki/ ++.. _extensions: http://mercurial.selenic.com/wiki/UsingExtensions ++.. _tips and tricks: http://mercurial.selenic.com/wiki/TipsAndTricks ++.. _configuration options: http://www.selenic.com/mercurial/hgrc.5.html ++ ++ ++.. _core-devs-faqs: ++ ++For core developers ++------------------- ++ ++These FAQs are intended mainly for core developers. ++ ++ ++.. _hg-commit: ++ ++How do I commit a change to a file? ++''''''''''''''''''''''''''''''''''' ++ ++To commit any changes to a file (which includes adding a new file or deleting ++an existing one), you use the command:: ++ ++ hg commit [PATH] ++ ++``PATH`` is optional: if it is omitted, all changes in your working copy ++will be committed to the local repository. When you commit, be sure that all ++changes are desired by :ref:`reviewing them first `; ++also, when making commits that you intend to push to public repositories, ++you should **not** commit together unrelated changes. ++ ++To abort a commit that you are in the middle of, leave the message ++empty (i.e., close the text editor without adding any text for the ++message). Mercurial will then abort the commit operation so that you can ++try again later. ++ ++Once a change is committed to your local repository, it is still only visible ++by you. This means you are free to experiment with as many local commits ++you feel like. ++ ++.. note:: ++ If you do not like the default text editor Mercurial uses for ++ entering commit messages, you may specify a different editor, ++ either by changing the ``EDITOR`` environment variable or by setting ++ a Mercurial-specific editor in your global ``.hgrc`` with the ``editor`` ++ option in the ``[ui]`` section. ++ ++ ++.. _hg-merge-conflicts: ++ ++How do I solve merge conflicts? ++''''''''''''''''''''''''''''''' ++ ++The easiest way is to install KDiff3 --- Mercurial will open it automatically ++in case of conflicts, and you can then use it to solve the conflicts and ++save the resulting file(s). KDiff3 will also take care of marking the ++conflicts as resolved. ++ ++If you don't use a merge tool, you can use ``hg resolve --list`` to list the ++conflicting files, resolve the conflicts manually, and the use ++``hg resolve --mark `` to mark these conflicts as resolved. ++You can also use ``hg resolve -am`` to mark all the conflicts as resolved. ++ ++.. note:: ++ Mercurial will use KDiff3 automatically if it's installed and it can find ++ it --- you don't need to change any settings. KDiff3 is also already ++ included in the installer of TortoiseHg. For more information, see ++ http://mercurial.selenic.com/wiki/KDiff3. ++ ++ ++.. _hg-null-merge: ++ ++How do I make a null merge? ++''''''''''''''''''''''''''' ++ ++If you committed something (e.g. on 3.3) that shouldn't be ported on newer ++branches (e.g. on default), you have to do a *null merge*:: ++ ++ cd 3.x ++ hg merge 3.3 ++ hg revert -ar default ++ hg resolve -am # needed only if the merge created conflicts ++ hg ci -m '#12345: null merge with 3.3.' ++ ++Before committing, ``hg status`` should list all the merged files as ``M``, ++but ``hg diff`` should produce no output. This will record the merge without ++actually changing the content of the files. ++ ++ ++.. _hg-heads-merge: ++ ++I got "abort: push creates new remote heads!" while pushing, what do I do? ++'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++If you see this message while pushing, it means that you committed something ++on a clone that was not up to date, thus creating a new head. ++This usually happens for two reasons: ++ ++1. You forgot to run ``hg pull`` and/or ``hg up`` before committing; ++2. Someone else pushed on the main repo just before you, causing a push race; ++ ++First of all you should pull the new changesets using ``hg pull``. Then you can ++use ``hg heads`` to see which branches have multiple heads. ++ ++If only one branch has multiple heads, you can do:: ++ ++ cd default ++ hg heads . ++ hg up csid-of-the-other-head ++ hg merge ++ hg ci -m 'Merge heads.' ++ ++``hg heads .`` will show you the two heads of the current branch: the one you ++pulled and the one you created with your commit (you can also specify a branch ++with ``hg heads ``). While not strictly necessary, it is highly ++recommended to switch to the other head before merging. This way you will be ++merging only your changeset with the rest, and in case of conflicts it will be ++a lot easier. ++ ++If more than one branch has multiple heads, you have to repeat these steps for ++each branch. Since this creates new changesets, you will also have to ++:ref:`merge them between branches `. For example, if both ``3.3`` ++and ``default`` have multiple heads, you should first merge heads in ``3.3``, ++then merge heads in ``default``, and finally merge ``3.3`` with ``default`` ++using ``hg merge 3.3`` as usual. ++ ++In order to avoid this, you should *always remember to pull and update before ++committing*. ++ ++ ++How do I undo the changes made in a recent commit? ++'''''''''''''''''''''''''''''''''''''''''''''''''' ++ ++First, this should not happen if you take the habit of :ref:`reviewing changes ++` before committing them. ++ ++In any case, run:: ++ ++ hg backout ++ ++This will modify your working copy so that all changes in ```` ++(including added or deleted files) are undone. You then need to :ref:`commit ++` these changes so that the backout gets permanently recorded. ++ ++.. note:: ++ These instructions are for Mercurial 1.7 and higher. ``hg backout`` has ++ a slightly different behaviour in versions before 1.7. ++ ++ ++SSH ++======= ++ ++How do I generate an SSH 2 public key? ++------------------------------------------------------------------------------- ++ ++All generated SSH keys should be sent to hgaccounts@python.org for ++adding to the list of keys. ++ ++UNIX ++'''' ++ ++Run:: ++ ++ ssh-keygen -t rsa ++ ++This will generate two files; your public key and your private key. Your ++public key is the file ending in ``.pub``. ++ ++Windows ++''''''' ++ ++Use PuTTYgen_ to generate your public key. Choose the "SSH2 DSA" radio button, ++have it create an OpenSSH formatted key, choose a password, and save the private ++key to a file. Copy the section with the public key (using Alt-P) to a file; ++that file now has your public key. ++ ++.. _PuTTYgen: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html ++ ++ ++Is there a way to avoid having to constantly enter my password for my SSH 2 public key? ++--------------------------------------------------------------------------------------- ++ ++UNIX ++'''' ++ ++Use ``ssh-agent`` and ``ssh-add`` to register your private key with SSH for ++your current session. The simplest solution, though, is to use KeyChain_, ++which is a shell script that will handle ``ssh-agent`` and ``ssh-add`` for you ++once per login instead of per session. ++ ++.. _KeyChain: http://www.gentoo.org/proj/en/keychain/ ++ ++ ++.. _pageant: ++ ++Windows ++''''''' ++ ++The Pageant program is bundled with TortoiseHg. You can find it in its ++installation directory (usually ``C:\Program Files (x86)\TortoiseHg\``); ++you can also `download it separately ++`_. ++ ++Running Pageant will prevent you from having to type your password constantly. ++If you add a shortcut to Pageant to your Autostart group and edit the shortcut ++so that the command line includes an argument to your private key then Pageant ++will load the key every time you log in. ++ ++ ++Can I make commits from machines other than the one I generated the keys on? ++------------------------------------------------------------------------------ ++ ++You can :ref:`make commits ` from any machine, since they will be ++recorded in your *local repository*. ++ ++However, to push these changes to the remote server, you will need proper ++credentials. All you need is to make sure that the machine you want to ++push changes from has both the public and private keys in the standard ++place that ssh will look for them (i.e. ~/.ssh on Unix machines). ++Please note that although the key file ending in .pub contains your ++user name and machine name in it, that information is not used by the ++verification process, therefore these key files can be moved to a ++different computer and used for verification. Please guard your keys ++and never share your private key with anyone. If you lose the media ++on which your keys are stored or the machine on which your keys are ++stored, be sure to report this to pydotorg@python.org at the same time ++that you change your keys. ++ ++ ++General ++======= ++ ++How do I regenerate configure? ++------------------------------ ++ ++If a change is made to Python which relies on some POSIX system-specific ++functionality (such as using a new system call), it is necessary to update the ++``configure`` script to test for availability of the functionality. ++ ++Python's ``configure`` script is generated from ``configure.ac`` using Autoconf. ++Instead of editing ``configure``, edit ``configure.ac`` and then run ++``autoreconf`` to regenerate ``configure`` and a number of other files (such as ++``pyconfig.h``. ++ ++When submitting a patch with changes made to ``configure.ac``, it is preferred ++to leave out the generated files as differences between Autoconf versions ++frequently results in many spurious changes cluttering the patch. Instead, ++remind any potential reviewers on the tracker to run ``autoreconf``. ++ ++Note that running ``autoreconf`` is not the same as running ``autoconf``. For ++example, ``autoconf`` by itself will not regenerate ``pyconfig.h.in``. ++``autoreconf`` runs ``autoconf`` and a number of other tools repeatedly as is ++appropriate. ++ ++Python's ``configure.ac`` script typically requires a specific version of ++Autoconf. At the moment, this reads: ``version_required(2.65)`` ++ ++If the system copy of Autoconf does not match this version, you will need to ++install your own copy of Autoconf. ++ ++ ++How do I update my auto-load-safe-path to allow test_gdb to run? ++---------------------------------------------------------------- ++ ++``test_gdb`` attempts to automatically load additional Python specific ++hooks into gdb in order to test them. Unfortunately, the command line ++options it uses to do this aren't always supported correctly. ++ ++If ``test_gdb`` is being skipped with an "auto-loading has been declined" ++message, then it is necessary to identify any Python build directories as ++auto-load safe. One way to achieve this is to add a line like the following ++to ``~/.gdbinit`` (edit the specific list of paths as appropriate):: ++ ++ add-auto-load-safe-path ~/devel/py3k:~/devel/py32:~/devel/py27 +diff -r 85f290e474e2 build/_sources/fixingissues.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/fixingissues.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,25 @@ ++.. _fixingissues: ++ ++Fixing "easy" Issues (and Beyond) ++================================= ++ ++When you feel comfortable enough to want to help tackle issues by trying to ++create a patch to fix an issue, you can start by looking at the `"easy" ++issues`_. These issues *should* be ones where it should take no longer than a day ++or weekend to fix. But because the "easy" classification is typically done at ++triage time it can turn out to be inaccurate, so do feel free to leave a ++comment if you think the classification no longer applies. ++ ++For the truly adventurous looking for a challenge, you can look for issues that ++are not considered easy and try to fix those. It must be warned, though, that ++it is quite possible that a bug that has been left open has been left into that ++state because of the difficulty compared to the benefit of the fix. It could ++also still be open because no consensus has been reached on how to fix the ++issue (although having a patch that proposes a fix can turn the tides of the ++discussion to help bring it to a close). Regardless of why the issue is open, ++you can also always provide useful comments if you do attempt a fix, successful ++or not. ++ ++.. _"easy" issues: http://bugs.python.org/issue?status=1&@sort=-activity&@dispname=Easy%20issues&@startwith=0&@filter=&@group=priority&@columns=id,activity,title,creator,status&keywords=6&@action=search&@pagesize=50 ++ ++.. TODO: add something about no active core developer for the area? +diff -r 85f290e474e2 build/_sources/gdb.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/gdb.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,291 @@ ++.. _gdb: ++ ++gdb Support ++=========== ++ ++If you experience low-level problems such as crashes or deadlocks ++(e.g. when tinkering with parts of CPython which are written in C), ++it can be convenient to use a low-level debugger such as gdb in ++order to diagnose and fix the issue. By default, however, gdb (or any ++of its front-ends) doesn't know about high-level information specific to the ++CPython interpreter, such as which Python function is currently executing, ++or what type or value has a given Python object represented by a standard ++``PyObject *`` pointer. We hereafter present two ways to overcome this ++limitation. ++ ++ ++gdb 7 and later ++--------------- ++ ++In gdb 7, support for `extending gdb with Python ++`_ was ++added. When CPython is built you will notice a ``python-gdb.py`` file in the ++root directory of your checkout. Read the module docstring for details on how ++to use the file to enhance gdb for easier debugging of a CPython process. ++ ++This is what a backtrace looks like (truncated) when this extension is ++enabled:: ++ ++ #0 0x000000000041a6b1 in PyObject_Malloc (nbytes=Cannot access memory at address 0x7fffff7fefe8 ++ ) at Objects/obmalloc.c:748 ++ #1 0x000000000041b7c0 in _PyObject_DebugMallocApi (id=111 'o', nbytes=24) at Objects/obmalloc.c:1445 ++ #2 0x000000000041b717 in _PyObject_DebugMalloc (nbytes=24) at Objects/obmalloc.c:1412 ++ #3 0x000000000044060a in _PyUnicode_New (length=11) at Objects/unicodeobject.c:346 ++ #4 0x00000000004466aa in PyUnicodeUCS2_DecodeUTF8Stateful (s=0x5c2b8d "__lltrace__", size=11, errors=0x0, consumed= ++ 0x0) at Objects/unicodeobject.c:2531 ++ #5 0x0000000000446647 in PyUnicodeUCS2_DecodeUTF8 (s=0x5c2b8d "__lltrace__", size=11, errors=0x0) ++ at Objects/unicodeobject.c:2495 ++ #6 0x0000000000440d1b in PyUnicodeUCS2_FromStringAndSize (u=0x5c2b8d "__lltrace__", size=11) ++ at Objects/unicodeobject.c:551 ++ #7 0x0000000000440d94 in PyUnicodeUCS2_FromString (u=0x5c2b8d "__lltrace__") at Objects/unicodeobject.c:569 ++ #8 0x0000000000584abd in PyDict_GetItemString (v= ++ {'Yuck': , '__builtins__': , '__file__': 'Lib/test/crashers/nasty_eq_vs_dict.py', '__package__': None, 'y': , 'dict': {0: 0, 1: 1, 2: 2, 3: 3}, '__cached__': None, '__name__': '__main__', 'z': , '__doc__': None}, key= ++ 0x5c2b8d "__lltrace__") at Objects/dictobject.c:2171 ++ ++(notice how the dictionary argument to ``PyDict_GetItemString`` is displayed ++as its ``repr()``, rather than an opaque ``PyObject *`` pointer) ++ ++The extension works by supplying a custom printing routine for values of type ++``PyObject *``. If you need to access lower-level details of an object, then ++cast the value to a pointer of the appropriate type. For example:: ++ ++ (gdb) p globals ++ $1 = {'__builtins__': , '__name__': ++ '__main__', 'ctypes': , '__doc__': None, ++ '__package__': None} ++ ++ (gdb) p *(PyDictObject*)globals ++ $2 = {ob_refcnt = 3, ob_type = 0x3dbdf85820, ma_fill = 5, ma_used = 5, ++ ma_mask = 7, ma_table = 0x63d0f8, ma_lookup = 0x3dbdc7ea70 ++ , ma_smalltable = {{me_hash = 7065186196740147912, ++ me_key = '__builtins__', me_value = }, ++ {me_hash = -368181376027291943, me_key = '__name__', ++ me_value ='__main__'}, {me_hash = 0, me_key = 0x0, me_value = 0x0}, ++ {me_hash = 0, me_key = 0x0, me_value = 0x0}, ++ {me_hash = -9177857982131165996, me_key = 'ctypes', ++ me_value = }, ++ {me_hash = -8518757509529533123, me_key = '__doc__', me_value = None}, ++ {me_hash = 0, me_key = 0x0, me_value = 0x0}, { ++ me_hash = 6614918939584953775, me_key = '__package__', me_value = None}}} ++ ++The pretty-printers try to closely match the ``repr()`` implementation of the ++underlying implementation of Python, and thus vary somewhat between Python 2 ++and Python 3. ++ ++An area that can be confusing is that the custom printer for some types look a ++lot like gdb's built-in printer for standard types. For example, the ++pretty-printer for a Python 3 ``int`` gives a ``repr()`` that is not ++distinguishable from a printing of a regular machine-level integer:: ++ ++ (gdb) p some_machine_integer ++ $3 = 42 ++ ++ (gdb) p some_python_integer ++ $4 = 42 ++ ++ (gdb) p *(PyLongObject*)some_python_integer ++ $5 = {ob_base = {ob_base = {ob_refcnt = 8, ob_type = 0x3dad39f5e0}, ob_size = 1}, ++ ob_digit = {42}} ++ ++A similar confusion can arise with the ``str`` type, where the output looks a ++lot like gdb's built-in printer for ``char *``:: ++ ++ (gdb) p ptr_to_python_str ++ $6 = '__builtins__' ++ ++The pretty-printer for ``str`` instances defaults to using single-quotes (as ++does Python's ``repr`` for strings) whereas the standard printer for ``char *`` ++values uses double-quotes and contains a hexadecimal address:: ++ ++ (gdb) p ptr_to_char_star ++ $7 = 0x6d72c0 "hello world" ++ ++Here's how to see the implementation details of a ``str`` instance (for Python ++3, where a ``str`` is a ``PyUnicodeObject *``):: ++ ++ (gdb) p *(PyUnicodeObject*)$6 ++ $8 = {ob_base = {ob_refcnt = 33, ob_type = 0x3dad3a95a0}, length = 12, ++ str = 0x7ffff2128500, hash = 7065186196740147912, state = 1, defenc = 0x0} ++ ++As well as adding pretty-printing support for ``PyObject *``, the extension adds a number of commands to gdb ++ ++``py-list`` ++ List the Python source code (if any) for the current frame in the selected ++ thread. The current line is marked with a ">":: ++ ++ (gdb) py-list ++ 901 if options.profile: ++ 902 options.profile = False ++ 903 profile_me() ++ 904 return ++ 905 ++ >906 u = UI() ++ 907 if not u.quit: ++ 908 try: ++ 909 gtk.main() ++ 910 except KeyboardInterrupt: ++ 911 # properly quit on a keyboard interrupt... ++ ++ Use ``py-list START`` to list at a different line number within the python ++ source, and ``py-list START,END`` to list a specific range of lines within ++ the python source. ++ ++``py-up`` and ``py-down`` ++ The ``py-up`` and ``py-down`` commands are analogous to gdb's regular ``up`` ++ and ``down`` commands, but try to move at the level of CPython frames, rather ++ than C frames. ++ ++ gdb is not always able to read the relevant frame information, depending on ++ the optimization level with which CPython was compiled. Internally, the ++ commands look for C frames that are executing ``PyEval_EvalFrameEx`` (which ++ implements the core bytecode interpreter loop within CPython) and look up ++ the value of the related ``PyFrameObject *``. ++ ++ They emit the frame number (at the C level) within the thread. ++ ++ For example:: ++ ++ (gdb) py-up ++ #37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/ ++ gnome_sudoku/main.py, line 906, in start_game () ++ u = UI() ++ (gdb) py-up ++ #40 Frame 0x948e82c, for file /usr/lib/python2.6/site-packages/ ++ gnome_sudoku/gnome_sudoku.py, line 22, in start_game(main=) ++ main.start_game() ++ (gdb) py-up ++ Unable to find an older python frame ++ ++ so we're at the top of the python stack. Going back down:: ++ ++ (gdb) py-down ++ #37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/gnome_sudoku/main.py, line 906, in start_game () ++ u = UI() ++ (gdb) py-down ++ #34 (unable to read python frame information) ++ (gdb) py-down ++ #23 (unable to read python frame information) ++ (gdb) py-down ++ #19 (unable to read python frame information) ++ (gdb) py-down ++ #14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/game_selector.py, line 201, in run_swallowed_dialog (self=, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, 'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\n7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': , 'gsd.hints': 0, 'timer.active_time': , 'timer.total_time': }], dialog=, saved_game_model=, sudoku_maker=, main_page=0) at remote 0x98fa6e4>, d=) ++ gtk.main() ++ (gdb) py-down ++ #8 (unable to read python frame information) ++ (gdb) py-down ++ Unable to find a newer python frame ++ ++ and we're at the bottom of the python stack. ++ ++``py-bt`` ++ The ``py-bt`` command attempts to display a Python-level backtrace of the ++ current thread. ++ ++ For example:: ++ ++ (gdb) py-bt ++ #8 (unable to read python frame information) ++ #11 Frame 0x9aead74, for file /usr/lib/python2.6/site-packages/gnome_sudoku/dialog_swallower.py, line 48, in run_dialog (self=, main_page=0) at remote 0x98fa6e4>, d=) ++ gtk.main() ++ #14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/game_selector.py, line 201, in run_swallowed_dialog (self=, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, 'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\n7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': , 'gsd.hints': 0, 'timer.active_time': , 'timer.total_time': }], dialog=, saved_game_model=, sudoku_maker=) ++ main.start_game() ++ ++ The frame numbers correspond to those displayed by gdb's standard ``backtrace`` command. ++ ++``py-print`` ++ The ``py-print`` command looks up a Python name and tries to print it. It looks in locals within the current thread, then globals, then finally builtins:: ++ ++ (gdb) py-print self ++ local 'self' = , ++ main_page=0) at remote 0x98fa6e4> ++ (gdb) py-print __name__ ++ global '__name__' = 'gnome_sudoku.dialog_swallower' ++ (gdb) py-print len ++ builtin 'len' = ++ (gdb) py-print scarlet_pimpernel ++ 'scarlet_pimpernel' not found ++ ++``py-locals`` ++ The ``py-locals`` command looks up all Python locals within the current Python frame in the selected thread, and prints their representations:: ++ ++ (gdb) py-locals ++ self = , ++ main_page=0) at remote 0x98fa6e4> ++ d = ++ ++You can of course use other gdb commands. For example, the ``frame`` command takes you directly to a particular frame within the selected thread. We can use it to go a specific frame shown by ``py-bt`` like this:: ++ ++ (gdb) py-bt ++ (output snipped) ++ #68 Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in () ++ main() ++ (gdb) frame 68 ++ #68 0x00000000004cd1e6 in PyEval_EvalFrameEx (f=Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in (), throwflag=0) at Python/ceval.c:2665 ++ 2665 x = call_function(&sp, oparg); ++ (gdb) py-list ++ 1543 # Run the tests in a context manager that temporary changes the CWD to a ++ 1544 # temporary and writable directory. If it's not possible to create or ++ 1545 # change the CWD, the original CWD will be used. The original CWD is ++ 1546 # available from test_support.SAVEDCWD. ++ 1547 with test_support.temp_cwd(TESTCWD, quiet=True): ++ >1548 main() ++ ++The ``info threads`` command will give you a list of the threads within the process, and you can use the ``thread`` command to select a different one:: ++ ++ (gdb) info threads ++ 105 Thread 0x7fffefa18710 (LWP 10260) sem_wait () at ../nptl/sysdeps/unix/sysv/linux/x86_64/sem_wait.S:86 ++ 104 Thread 0x7fffdf5fe710 (LWP 10259) sem_wait () at ../nptl/sysdeps/unix/sysv/linux/x86_64/sem_wait.S:86 ++ * 1 Thread 0x7ffff7fe2700 (LWP 10145) 0x00000038e46d73e3 in select () at ../sysdeps/unix/syscall-template.S:82 ++ ++You can use ``thread apply all COMMAND`` or (``t a a COMMAND`` for short) to run a command on all threads. You can use this with ``py-bt`` to see what every thread is doing at the Python level:: ++ ++ (gdb) t a a py-bt ++ ++ Thread 105 (Thread 0x7fffefa18710 (LWP 10260)): ++ #5 Frame 0x7fffd00019d0, for file /home/david/coding/python-svn/Lib/threading.py, line 155, in _acquire_restore (self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, count_owner=(1, 140737213728528), count=1, owner=140737213728528) ++ self.__block.acquire() ++ #8 Frame 0x7fffac001640, for file /home/david/coding/python-svn/Lib/threading.py, line 269, in wait (self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, acquire=, _is_owned=, _release_save=, release=, _acquire_restore=, _Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, timeout=None, waiter=, saved_state=(1, 140737213728528)) ++ self._acquire_restore(saved_state) ++ #12 Frame 0x7fffb8001a10, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 348, in f () ++ cond.wait() ++ #16 Frame 0x7fffb8001c40, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 37, in task (tid=140737213728528) ++ f() ++ ++ Thread 104 (Thread 0x7fffdf5fe710 (LWP 10259)): ++ #5 Frame 0x7fffe4001580, for file /home/david/coding/python-svn/Lib/threading.py, line 155, in _acquire_restore (self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, count_owner=(1, 140736940992272), count=1, owner=140736940992272) ++ self.__block.acquire() ++ #8 Frame 0x7fffc8002090, for file /home/david/coding/python-svn/Lib/threading.py, line 269, in wait (self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=, _RLock__count=1) at remote 0xd7ff40>, acquire=, _is_owned=, _release_save=, release=, _acquire_restore=, _Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, timeout=None, waiter=, saved_state=(1, 140736940992272)) ++ self._acquire_restore(saved_state) ++ #12 Frame 0x7fffac001c90, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 348, in f () ++ cond.wait() ++ #16 Frame 0x7fffac0011c0, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 37, in task (tid=140736940992272) ++ f() ++ ++ Thread 1 (Thread 0x7ffff7fe2700 (LWP 10145)): ++ #5 Frame 0xcb5380, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 16, in _wait () ++ time.sleep(0.01) ++ #8 Frame 0x7fffd00024a0, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 378, in _check_notify (self=, skipped=[], _mirrorOutput=False, testsRun=39, buffer=False, _original_stderr=, _stdout_buffer=, _stderr_buffer=, _moduleSetUpFailed=False, expectedFailures=[], errors=[], _previousTestClass=, unexpectedSuccesses=[], failures=[], shouldStop=False, failfast=False) at remote 0xc185a0>, _threads=(0,), _cleanups=[], _type_equality_funcs={: , : , : , : , `_ ++that adding the floor division ++operator (//) broke the parser module. ++ ++ ++Checklist ++--------- ++ ++* Grammar/Grammar: OK, you'd probably worked this one out :) ++ ++* Parser/Python.asdl may need changes to match the Grammar. Run make to ++ regenerate Include/Python-ast.h and Python/Python-ast.c. ++ ++* Python/ast.c will need changes to create the AST objects involved with the ++ Grammar change. ++ ++* Parser/pgen needs to be rerun to regenerate Include/graminit.h and ++ Python/graminit.c. (make should handle this for you.) ++ ++* Python/symtable.c: This handles the symbol collection pass ++ that happens immediately before the compilation pass. ++ ++* Python/compile.c: You will need to create or modify the ++ compiler_* functions to generate opcodes for your productions. ++ ++* You may need to regenerate Lib/symbol.py and/or Lib/token.py ++ and/or Lib/keyword.py. ++ ++* The parser module. Add some of your new syntax to test_parser, ++ bang on Modules/parsermodule.c until it passes. ++ ++* Add some usage of your new syntax to test_grammar.py ++ ++* If you've gone so far as to change the token structure of ++ Python, then the Lib/tokenizer.py library module will need to be changed. ++ ++* Certain changes may require tweaks to the library module pyclbr. ++ ++* Documentation must be written! ++ ++* After everything has been checked in, you're likely to see a new ++ change to Python/Python-ast.c. This is because this ++ (generated) file contains the hg version of the source from ++ which it was generated. There's no way to avoid this; you just ++ have to submit this file separately. +diff -r 85f290e474e2 build/_sources/help.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/help.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,69 @@ ++.. _help: ++ ++Where to Get Help ++================= ++ ++If you are working on Python it is very possible you will come across an issue ++where you need some assistance to solve it (this happens to core developers ++all the time). ++ ++Should you require help, there are a :ref:`variety of options available ++` to seek assistance. If the question involves process or tool ++usage then please check the rest of this guide first (especially the ++:ref:`FAQ`) as it should answer your question. ++ ++ ++Ask #python-dev ++----------------- ++ ++If you are comfortable with IRC you can try asking on ``#python-dev`` (on ++the `freenode`_ network). Typically there are a number of experienced ++developers, ranging from triagers to core developers, who can answer ++questions about developing for Python. Just remember that ``#python-dev`` ++is for questions involving the development *of* Python whereas ``#python`` ++is for questions concerning development *with* Python. ++ ++.. _freenode: http://freenode.net/ ++ ++ ++Core Mentorship ++--------------- ++ ++If you are interested in improving Python and contributing to its development, ++but don’t yet feel entirely comfortable with the public channels mentioned ++above, `Python Mentors`_ are here to help you. Python is fortunate to have a ++community of volunteer core developers willing to mentor anyone wishing to ++contribute code, work on bug fixes or improve documentation. Everyone is ++welcomed and encouraged to contribute. ++ ++.. _Python Mentors: http://pythonmentors.com ++ ++ ++Mailing Lists ++------------- ++ ++Further options for seeking assistance include the `python-ideas`_ and ++`python-dev`_ mailing lists. Python-ideas contains discussion of speculative ++Python language ideas for possible inclusion into the language. If an idea ++gains traction it can then be discussed and honed to the point of becoming a ++solid proposal and presented on python-dev. Python-dev contains discussion ++of current Python design issues, release mechanics, and maintenance of ++existing releases. As with ``#python-dev``, these mailing lists are for ++questions involving the development *of* Python, **not** for development ++*with* Python. ++ ++.. _python-ideas: http://mail.python.org/mailman/listinfo/python-ideas ++.. _python-dev: http://mail.python.org/mailman/listinfo/python-dev ++ ++ ++File a Bug ++---------- ++ ++If you strongly suspect you have stumbled on a bug (be it in the build ++process, in the test suite, or in other areas), then open an issue on the ++`issue tracker`_. As with every bug report it is strongly advised that ++you detail which conditions triggered it (including the OS name and version, ++and what you were trying to do), as well as the exact error message you ++encountered. ++ ++.. _issue tracker: http://bugs.python.org +diff -r 85f290e474e2 build/_sources/index.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/index.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,230 @@ ++======================== ++Python Developer's Guide ++======================== ++ ++This guide is a comprehensive resource for :ref:`contributing ` ++to Python_ -- for both new and experienced contributors. It is ++:ref:`maintained ` by the same community ++that maintains Python. We welcome your contributions to Python! ++ ++ ++Quick Start ++----------- ++ ++Here are the basic steps needed to get :ref:`set up ` and contribute a ++patch: ++ ++1. :ref:`Get the source code `:: ++ ++ hg clone http://hg.python.org/cpython ++ ++2. :ref:`Build Python `. On :ref:`UNIX `:: ++ ++ ./configure --with-pydebug && make -j2 ++ ++ On :ref:`Windows `, open the solution file ++ :file:`PCbuild\\pcbuild.sln` in Visual Studio, select :menuselection:`Debug`, ++ and :menuselection:`Build --> Build Solution`. Run ++ :file:`Tools\\buildbot\\external.bat` or ++ :file:`Tools\\buildbot\\external-amd64.bat` to download and compile 3rd ++ party libraries. Note: Visual Studio may throw errors, but Python will ++ be built. ++ ++3. :doc:`Run the tests `:: ++ ++ ./python -m test -j3 ++ ++ On :ref:`most ` Mac OS X systems, replace :file:`./python` ++ with :file:`./python.exe`. On Windows, use :file:`PCbuild\\python_d.exe` or ++ check the :ref:`Windows instructions `. With Python 2.7, ++ replace ``test`` with ``test.regrtest``. ++4. Make the :doc:`patch `. ++5. Submit it to the `issue tracker`_. ++ ++ ++Quick Links ++----------- ++ ++Here are some links that you probably will reference frequently while ++contributing to Python. ++ ++* `Issue tracker`_ ++* `Buildbot status`_ ++* :doc:`faq` ++* PEPs_ (Python Enhancement Proposals) ++ ++ ++.. _contributing: ++ ++Contributing ++------------ ++ ++We encourage everyone to contribute to Python and that's why we have put up this ++developer's guide. If you still have questions after reviewing the material in ++this guide, then the `Python Mentors`_ group is available to help guide new ++contributors through the process. The :doc:`Developer FAQ ` is another ++useful source of information. ++ ++Guide for contributing to Python: ++ ++* :doc:`setup` ++* :doc:`help` ++* :doc:`patch` ++* :doc:`runtests` ++* Beginner tasks to become familiar with the development process ++ * :doc:`docquality` ++ * :doc:`coverage` ++* Advanced tasks for once you are comfortable ++ * :doc:`silencewarnings` ++ * Fixing issues found by the :doc:`buildbots ` ++ * :doc:`fixingissues` ++* :ref:`tracker` and :ref:`helptriage` ++ * :doc:`triaging` ++* :doc:`communication` ++* :doc:`coredev` ++ * :doc:`committing` ++ * :doc:`devcycle` ++ * :doc:`buildbots` ++ * :doc:`coverity` ++ ++It is **recommended** that the above documents be read in the order listed. You ++can stop where you feel comfortable and begin contributing immediately without ++reading and understanding these documents all at once. If you do choose to skip ++around within the documentation, be aware that it is written assuming preceding ++documentation has been read so you may find it necessary to backtrack to fill in ++missing concepts and terminology. ++ ++ ++Proposing changes to Python itself ++---------------------------------- ++ ++Improving Python's code, documentation and tests are ongoing tasks that are ++never going to be "finished", as Python operates as part of an ever-evolving ++system of technology. An even more challenging ongoing task than these ++necessary maintenance activities is finding ways to make Python, in the form of ++the standard library and the language definition, an even better tool in a ++developer's toolkit. ++ ++While these kinds of change are much rarer than those described above, they do ++happen and that process is also described as part of this guide: ++ ++* :doc:`stdlibchanges` ++* :doc:`langchanges` ++ ++Also refer to :ref:`suggesting-changes` in the FAQ. ++ ++ ++Other Interpreter Implementations ++--------------------------------- ++ ++This guide is specifically for contributing to the Python reference interpreter, ++also known as CPython (while most of the standard library is written in Python, ++the interpreter core is written in C and integrates most easily with the C and ++C++ ecosystems). ++ ++There are other Python implementations, each with a different focus. Like ++CPython, they always have more things they would like to do than they have ++developers to work on them. Some major example that may be of interest are: ++ ++* PyPy_: A Python interpreter focused on high speed (JIT-compiled) operation ++ on major platforms ++* Jython_: A Python interpreter focused on good integration with the Java ++ Virtual Machine (JVM) environment ++* IronPython_: A Python interpreter focused on good integration with the ++ Common Language Runtime (CLR) provided by .NET and Mono ++* Stackless_: A Python interpreter focused on providing lightweight ++ microthreads while remaining largely compatible with CPython specific ++ extension modules ++ ++ ++Key Resources ++------------- ++ ++* Coding style guides ++ * :PEP:`7` (Style Guide for C Code) ++ * :PEP:`8` (Style Guide for Python Code) ++* `Issue tracker`_ ++ * `Meta tracker `_ (issue ++ tracker for the issue tracker) ++ * :doc:`experts` ++ * `Firefox search engine plug-in`_ ++* `Buildbot status`_ ++* Source code ++ * `Browse online `_ ++ * `Snapshot of py3k `_ ++ * `Daily OS X installer `_ ++* PEPs_ (Python Enhancement Proposals) ++* :doc:`faq` ++* :doc:`developers` ++ ++ ++.. _resources: ++ ++Additional Resources ++-------------------- ++ ++* Anyone can clone the sources for this guide. See ++ :ref:`helping-with-the-developers-guide`. ++* Help with ... ++ * :doc:`grammar` ++ * :doc:`compiler` ++* Tool support ++ * :doc:`emacs` ++ * :doc:`gdb` ++ * :doc:`clang` ++ * Various tools with configuration files as found in the `Misc directory`_ ++* `python.org maintenance`_ ++ ++* :ref:`Search this guide ` ++ ++ ++.. _contents: ++ ++Full Table of Contents ++---------------------- ++ ++.. toctree:: ++ :numbered: ++ ++ setup ++ setupwindows ++ help ++ patch ++ runtests ++ coverage ++ docquality ++ documenting ++ silencewarnings ++ fixingissues ++ tracker ++ triaging ++ communication ++ coredev ++ developers ++ committing ++ devcycle ++ buildbots ++ stdlibchanges ++ langchanges ++ experts ++ emacs ++ gdb ++ grammar ++ compiler ++ coverity ++ clang ++ faq ++ ++ ++.. _Buildbot status: http://python.org/dev/buildbot/ ++.. _Firefox search engine plug-in: http://www.python.org/dev/searchplugin/ ++.. _Misc directory: http://hg.python.org/cpython/file/default/Misc ++.. _PEPs: http://www.python.org/dev/peps ++.. _python.org maintenance: http://python.org/dev/pydotorg/ ++.. _Python: http://www.python.org/ ++.. _Python Mentors: http://pythonmentors.com/ ++.. _PyPy: http://www.pypy.org/ ++.. _Jython: http://www.jython.org/ ++.. _IronPython: http://ironpython.net/ ++.. _Stackless: http://www.stackless.com/ ++.. _Issue tracker: http://bugs.python.org/ +diff -r 85f290e474e2 build/_sources/langchanges.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/langchanges.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,63 @@ ++.. _langchanges: ++ ++Changing the Python Language ++============================ ++On occasion people come up with an idea on how to change or improve Python as a ++programming language. This document is meant to explain exactly what changes ++have a reasonable chance of being considered and what the process is to propose ++changes to the language. ++ ++ ++What Qualifies ++-------------- ++First and foremost, it must be understood that changes to the Python ++programming language are difficult to make. When the language changes, ++**every** Python programmer already in existence and all Python programmers to ++come will end up eventually learning about the change you want to propose. ++Books will need updating, code will be changed, and a new way to do things will ++need to be learned. Changes to the Python programming language are never taken ++lightly. ++ ++Because of the seriousness that language changes carry, any change must be ++beneficial to a large proportion of Python users. If the change only benefits a ++small percentage of Python developers then the change will not be made. A good ++way to see if your idea would work for a large portion of the Python community ++is to ask on :ref:`python-list or python-ideas `. You can also ++go through Python's stdlib and find examples of code which would benefit from ++your proposed change (which helps communicate the usefulness of your change to ++others). For further guidance, see :ref:`suggesting-changes` in the FAQ. ++ ++Your proposed change also needs to be *Pythonic*. While Guido is the only ++person who can truly classify something as Pythonic, you can read the `Zen of ++Python`_ for guidance. ++ ++.. _Zen of Python: http://www.python.org/dev/peps/pep-0020/ ++ ++ ++.. index:: PEP process ++ ++PEP Process ++----------- ++Once you are certain you have a language change proposal which will appeal to ++the general Python community, you can begin the process of officially proposing ++the change. This process is the Python Enhancement Proposal (PEP) process. ++:PEP:`1` describes it in detail. ++ ++You will first need a PEP that you will present to python-ideas. You may be a ++little hazy on the technical details as various core developers can help with ++that, but do realize that if you do not present your idea to python-ideas or ++python-list ahead of time you may find out it is technically not possible ++(e.g., Python's parser will not support the grammar change as it is an LL(1) ++parser). Expect extensive comments on the PEP, some of which will be negative. ++ ++Once your PEP has been modified to be of proper quality and to take into ++account comments made on python-ideas, it may proceed to python-dev. There it ++will be assigned a PEP dictator and another general discussion will occur. Once ++again, you will need to modify your PEP to incorporate the large amount of ++comments you will receive. ++ ++The PEP dictator decides if your PEP is accepted (typically based on whether ++most core developers support the PEP). If that occurs then your proposed ++language change will be introduced in the next release of Python. Otherwise ++your PEP will be recorded as rejected along with an explanation as to why so ++that others do not propose the same language change in the future. +diff -r 85f290e474e2 build/_sources/patch.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/patch.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,187 @@ ++.. _patch: ++ ++Lifecycle of a Patch ++==================== ++ ++ ++Creating ++-------- ++ ++Tool Usage ++'''''''''' ++ ++.. _workflow: ++ ++Mercurial allows for various workflows according to each person's or ++project's preference. It is out of this guide's scope to present them all, ++so we will stick to a basic workflow where you work on a patch in your ++working copy without ever making any local commits. ++ ++If you use this workflow, and your work adds or removes files to the ++source tree, you will have to temporarily ``hg add`` or ``hg remove`` them, ++respectively, before generating a patch. ++ ++To generate a patch, just invoke ``hg diff`` which will print out a ++patch of the working copy's changes against the current revision:: ++ ++ hg diff > mywork.patch ++ ++If you want to undo your changes, you can revert them from the working copy:: ++ ++ hg revert -a ++ ++You can later re-apply the changes if you want to continue working on the ++patch:: ++ ++ hg import --no-commit mywork.patch ++ ++ ++.. seealso:: ++ Refer to the :ref:`FAQ ` for ++ :ref:`more information on using Mercurial `. ++ ++ ++Preparation ++''''''''''' ++ ++When creating a patch for submission, there are several things that you should ++do to help ensure that your patch is accepted. ++ ++First, make sure to follow Python's style guidelines. For Python code you ++should follow :PEP:`8`, and for C code you should follow :PEP:`7`. If you have ++one or two discrepancies those can be fixed by the core developer who commits ++your patch. But if you have systematic deviations from the style guides your ++patch will be put on hold until you fix the formatting issues. ++ ++Second, be aware of backwards-compatibility considerations. While the core ++developer who eventually handles your patch will make the final call on whether ++something is acceptable, thinking about backwards-compatibility early ++will help prevent having your patch rejected on these grounds. Put yourself in ++the shoes of someone whose code will be broken by the change(s) introduced by ++the patch. It is quite likely that any change made will break ++someone's code, so you need to have a good reason to make a change as you will ++be forcing someone to update their code. (This obviously does not apply to new ++classes or functions; new arguments should be optional and have default values ++which maintain the existing behavior.) If in doubt, have a look at ++:PEP:`387` or :ref:`discuss ` the issue with experienced ++developers. ++ ++Third, make sure you have proper tests to verify your patch works as expected. ++Patches will not be accepted without the proper tests! ++ ++Fourth, make sure the entire test suite :ref:`runs ` **without ++failure** because of your changes. It is not sufficient to only run whichever ++test seems impacted by your changes, because there might be interferences ++unknown to you between your changes and some other part of the interpreter. ++ ++Fifth, proper :ref:`documentation ` ++additions/changes should be included. ++ ++ ++.. _patch-generation: ++ ++Generation ++'''''''''' ++ ++To perform a quick sanity check on your patch, you can run:: ++ ++ make patchcheck ++ ++This will check and/or fix various common things people forget to do for ++patches, such as adding any new files needed for the patch to work (note ++that not all checks apply to non-core developers). On Windows, use this ++command:: ++ ++ ./python.exe Tools/scripts/patchcheck.py ++ ++Assuming you are using the :ref:`basic approach ` suggested earlier, ++just type the following:: ++ ++ hg diff > mywork.patch ++ ++If you are using another approach, you probably need to find out the right ++invocation of ``hg diff`` for your purposes; see ``hg help diff`` and ``hg ++help revisions``. Just please make sure that you generate a ++**single, condensed** patch rather than a series of several changesets. ++ ++ ++Licensing ++--------- ++ ++For non-trivial changes, we must have your formal approval for distributing ++your work under the `PSF license`_. Therefore, you need to fill out a ++`contributor form`_ which allows the `Python Software Foundation`_ to ++license your code for use with Python (you retain the copyright). ++ ++.. note:: ++ You only have to sign this document once, it will then apply to all ++ your further contributions to Python. ++ ++ ++.. _PSF license: http://docs.python.org/3.4/license.html#terms-and-conditions-for-accessing-or-otherwise-using-python ++.. _contributor form: http://www.python.org/psf/contrib/ ++.. _Python Software Foundation: http://www.python.org/psf/ ++ ++ ++Submitting ++---------- ++ ++If this is a patch in response to a pre-existing issue on the `issue tracker`_, ++attach the patch to the issue; use the ``Choose File`` button on the tracker ++web page for the issue to upload your patch file. Please provide any details ++about your patch that ++would be relevant to the discussion of the issue or your patch. ++ ++If this is a patch for an unreported issue (assuming you already performed a ++search on the issue tracker for a pre-existing issue), create a new issue and ++attach your patch. Please fill in as much relevant detail as possible to ++prevent patch reviewers from having to delay reviewing your patch because of ++lack of information. ++ ++ ++.. _issue tracker: http://bugs.python.org ++ ++ ++Reviewing ++--------- ++ ++To begin with, please be patient! There are many more people submitting patches ++than there are people capable of reviewing your patch. Getting your patch ++reviewed requires a reviewer to have the spare time and motivation to ++look at your patch (we cannot force anyone to review patches). If your patch has ++not received any notice from reviewers (i.e., no comment made) after one ++month, first "ping" the issue on the `issue tracker`_ to remind the nosy list ++that the patch needs a review. If you don't get a response within a few days ++after pinging the issue, then you can try emailing python-dev@python.org asking ++for someone to review your patch. ++ ++When someone does manage to find the time to look at your patch they will most ++likely make comments about how it can be improved (don't worry, even core ++developers of Python have their patches sent back to them for changes). It ++is then expected that you post a new patch addressing these comments, and the ++review process will thus iterate until a satisfactory solution has emerged. ++ ++ ++Committing/Rejecting ++-------------------- ++ ++Once your patch has reached an acceptable state (and thus considered ++"accepted"), it will either be committed or rejected. If it is rejected, please ++do not take it personally! Your work is still appreciated regardless of whether ++your patch is committed. Balancing what *does* and *does not* go into Python ++is tricky and we simply cannot accept everyone's contributions. ++ ++But if your patch is committed it will then go into Python's ++:abbr:`VCS (version control system)` to be released ++with the next major release of Python. It may also be backported to older ++versions of Python as a bugfix if the core developer doing the commit believes ++it is warranted. ++ ++ ++Crediting ++--------- ++ ++Non-trivial contributions are credited in the ``Misc/ACKS`` file (and, most ++often, in a contribution's ``Misc/NEWS`` entry as well). This is something ++the core developer will do when committing your patch, you don't have to ++propose the addition by yourself. +diff -r 85f290e474e2 build/_sources/runtests.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/runtests.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,120 @@ ++.. _runtests: ++ ++Running & Writing Tests ++======================= ++ ++.. note:: ++ ++ This document assumes you are working from an ++ :ref:`in-development ` checkout of Python. If you ++ are not then some things presented here may not work as they may depend ++ on new features not available in earlier versions of Python. ++ ++Running ++------- ++ ++The shortest, simplest way of running the test suite is the following command ++from the root directory of your checkout (after you have built Python):: ++ ++ ./python -m test ++ ++You may need to change this command as follows throughout this section. ++On :ref:`most ` Mac OS X systems, replace :file:`./python` ++with :file:`./python.exe`. On Windows, use :file:`PCbuild\\python_d.exe` or ++check the detailed :ref:`Windows instructions `. If using ++Python 2.7, replace ``test`` with ``test.regrtest``. ++ ++If you don't have easy access to a command line, you can run the test suite from ++a Python or IDLE shell:: ++ ++ >>> from test import autotest ++ ++This will run the majority of tests, but exclude a small portion of them; these ++excluded tests use special kinds of resources: for example, accessing the ++Internet, or trying to play a sound or to display a graphical interface on ++your desktop. They are disabled by default so that running the test suite ++is not too intrusive. To enable some of these additional tests (and for ++other flags which can help debug various issues such as reference leaks), read ++the help text:: ++ ++ ./python -m test -h ++ ++If you want to run a single test, simply specify the test name as an argument. ++You also probably want to enable verbose mode (using ``-v``), so that individual ++failures are detailed:: ++ ++ ./python -m test -v test_abc ++ ++If you have a multi-core or multi-CPU machine, you can enable parallel testing ++using several Python processes so as to speed up things:: ++ ++ ./python -m test -j0 ++ ++If you are running a version of Python prior to 3.3 you must specify the number ++of processes to run simultaneously (e.g. ``-j2``). ++ ++.. _strenuous_testing: ++ ++Finally, if you want to run tests under a more strenuous set of settings, you ++can run ``test`` as:: ++ ++ ./python -bb -E -Wd -m test -r -w -uall ++ ++The various extra flags passed to Python cause it to be much stricter about ++various things (the ``-Wd`` flag should be ``-W error`` at some point, but the ++test suite has not reached a point where all warnings have been dealt with and ++so we cannot guarantee that a bug-free Python will properly complete a test run ++with ``-W error``). The ``-r`` flag to the test runner causes it to run tests in ++a more random order which helps to check that the various tests do not interfere ++with each other. The ``-w`` flag causes failing tests to be run again to see ++if the failures are transient or consistent. ++The ``-uall`` flag allows the use of all available ++resources so as to not skip tests requiring, e.g., Internet access. ++ ++To check for reference leaks (only needed if you modified C code), use the ++``-R`` flag. For example, ``-R 3:2`` will first run the test 3 times to settle ++down the reference count, and then run it 2 more times to verify if there are ++any leaks. ++ ++You can also execute the ``Tools/scripts/run_tests.py`` script as found in a ++CPython checkout. The script tries to balance speed with thoroughness. But if ++you want the most thorough tests you should use the strenuous approach shown ++above. ++ ++ ++Unexpected Skips ++^^^^^^^^^^^^^^^^ ++ ++Sometimes when running the test suite, you will see "unexpected skips" ++reported. These represent cases where an entire test module has been ++skipped, but the test suite normally expects the tests in that module to ++be executed on that platform. ++ ++Often, the cause is that an optional module hasn't been built due to missing ++build dependencies. In these cases, the missing module reported when the test ++is skipped should match one of the modules reported as failing to build when ++:ref:`compiling`. ++ ++In other cases, the skip message should provide enough detail to help figure ++out and resolve the cause of the problem (for example, the default security ++settings on some platforms will disallow some tests) ++ ++ ++Writing ++------- ++ ++Writing tests for Python is much like writing tests for your own code. Tests ++need to be thorough, fast, isolated, consistently repeatable, and as simple as ++possible. We try to have tests both for normal behaviour and for error ++conditions. Tests live in the ``Lib/test`` directory, where every file that ++includes tests has a ``test_`` prefix. ++ ++One difference with ordinary testing is that you are encouraged to rely on the ++:py:mod:`test.support` module. It contains various helpers that are tailored to ++Python's test suite and help smooth out common problems such as platform ++differences, resource consumption and cleanup, or warnings management. ++That module is not suitable for use outside of the standard library. ++ ++When you are adding tests to an existing test file, it is also recommended ++that you study the other tests in that file; it will teach you which precautions ++you have to take to make your tests robust and portable. +diff -r 85f290e474e2 build/_sources/setup.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/setup.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,367 @@ ++=============== ++Getting Started ++=============== ++ ++These instructions cover how to get a working copy of the source code and a ++compiled version of the CPython interpreter (CPython is the version of Python ++available from http://www.python.org/). It also gives an overview of the ++directory structure of the CPython source code. ++ ++OpenHatch also has a great `setup guide`_ for Python for people who are ++completely new to contributing to open source. ++ ++.. _setup guide: https://openhatch.org/wiki/Contributing_to_Python ++ ++ ++.. _setup: ++ ++Getting Set Up ++============== ++ ++Version Control Setup ++--------------------- ++ ++CPython is developed using `Mercurial `_. The Mercurial ++command line program is named ``hg``; this is also used to refer to Mercurial ++itself. Mercurial is easily available for common Unix systems by way of the ++standard package manager; under Windows, you might want to use the ++`TortoiseHg `_ graphical client. ++ ++ ++.. _checkout: ++ ++Getting the Source Code ++----------------------- ++ ++One should always work from a working copy of the CPython source code. ++While it may ++be tempting to work from the copy of Python you already have installed on your ++machine, it is very likely that you will be working from out-of-date code as ++the Python core developers are constantly updating and fixing things in their ++:abbr:`VCS (version control system)`. It also means you will have better tool ++support through the VCS as it will provide a diff tool, etc. ++ ++To get a working copy of the :ref:`in-development ` branch of ++CPython (core developers use a different URL as outlined in :ref:`coredev`), ++run:: ++ ++ hg clone http://hg.python.org/cpython ++ ++If you want a working copy of an already-released version of Python, ++i.e., a version in :ref:`maintenance mode `, you can update your ++working copy. For instance, to update your working copy to Python 3.3, do:: ++ ++ hg update 3.3 ++ ++You will need to re-compile CPython when you do such an update. ++ ++Do note that CPython will notice that it is being run from a working copy. ++This means that if you edit CPython's source code in your working copy, ++changes to Python code will be picked up by the interpreter for immediate ++use and testing. (If you change C code, you will need to recompile the ++affected files as described below.) ++ ++Patches for the documentation can be made from the same repository; see ++:ref:`documenting`. ++ ++.. _compiling: ++ ++Compiling (for debugging) ++------------------------- ++ ++CPython provides several compilation flags which help with debugging various ++things. While all of the known flags can be found in the ++``Misc/SpecialBuilds.txt`` ++file, the most critical one is the ``Py_DEBUG`` flag which creates what is ++known as a "pydebug" build. This flag turns on ++various extra sanity checks which help catch common issues. The use of the flag ++is so common that turning on the flag is a basic compile option. ++ ++You should always ++develop under a pydebug build of CPython (the only instance of when you ++shouldn't is if you are taking performance measurements). Even when working ++only on pure Python code the pydebug build provides several useful checks that ++one should not skip. ++ ++ ++Build dependencies ++'''''''''''''''''' ++ ++The core CPython interpreter only needs a C compiler to be built; if ++you get compile errors with a C89 or C99-compliant compiler, please `open a ++bug report `_. ++However, some of the extension modules will need development headers ++for additional libraries (such as the ``zlib`` library for compression). ++Depending on what you intend to work on, you might need to install these ++additional requirements so that the compiled interpreter supports the ++desired features. ++ ++For UNIX based systems, we try to use system libraries whenever available. ++This means optional components will only build if the relevant system headers ++are available. The best way to obtain the appropriate headers will vary by ++distribution, but the appropriate commands for some popular distributions ++are below. ++ ++Fedora, Red Hat Enterprise Linux and other ``yum`` based systems:: ++ ++ $ sudo yum install yum-utils ++ $ sudo yum-builddep python3 ++ ++Debian, Ubuntu and other ``apt`` based systems:: ++ ++ $ sudo apt-get build-dep python3 ++ ++For Mac OS X systems, it is generally easiest to use the C compiler and other ++development utilities provided by Apple's Xcode Developer Tools. There are ++specific versions supported by Apple for each major release of OS X. For ++current releases, Xcode is available as a no-cost download from Apple's App ++Store. Xcode versions for older releases are available through ++`the Apple Developer web site `_. ++Note that while the Xcode IDE application itself is not needed to build Python, ++the development components packaged inside it may be. You should also install ++the Xcode Command Line Tools component to ensure build tools and system header ++files are installed in their conventional locations (``/usr/bin`` and ++``/usr/include``). How the command line tools are installed varies by OS X ++and Xcode release. In earlier releases, there may be a separate installer ++download. For OS X 10.7 and 10.8, there is an option in the Xcode app ++Preferences menu. For OS X 10.9 (Mavericks), run the following:: ++ ++ $ xcode-select --install ++ ++Also note that OS X does not include several libraries used by the Python ++standard library, including ``libzma``, so expect to see some extension module ++build failures unless you install local copies of them. ++ ++There will sometimes be optional modules added for a new release which ++won't yet be identified in the OS level build dependencies. In those cases, ++just ask for assistance on the core-mentorship list. If working on bug ++fixes for Python 2.7, use ``python`` in place of ``python3`` in the above ++commands. ++ ++Explaining how to build optional dependencies on a UNIX based system without ++root access is beyond the scope of this guide. ++ ++.. _clang: http://clang.llvm.org/ ++ ++.. note:: While you need a C compiler to build CPython, you don't need any ++ knowledge of the C language to contribute! Vast areas of CPython are ++ written completely in Python: as of this writing, CPython contains slightly ++ more Python code than C. ++ ++ ++.. _unix-compiling: ++ ++UNIX ++'''' ++ ++The basic steps for building Python for development is to configure it and ++then compile it. ++ ++Configuration is typically:: ++ ++ ./configure --with-pydebug ++ ++More flags are available to ``configure``, but this is the minimum you should ++do to get a pydebug build of CPython. ++ ++Once ``configure`` is done, you can then compile CPython with:: ++ ++ make -s -j2 ++ ++This will build CPython with only warnings and errors being printed to ++stderr and utilize up to 2 CPU cores. If you are using a multi-core machine ++with more than 2 cores (or a single-core machine), you can adjust the number ++passed into the ``-j`` flag to match the number of cores you have. ++ ++Do take note of what modules were **not** built as stated at the end of your ++build. More than likely you are missing a dependency for the module(s) that ++were not built, and so you can install the dependencies and re-run both ++``configure`` and ``make`` (if available for your OS). ++Otherwise the build failed and thus should be fixed (at least with a bug being ++filed on the `issue tracker`_). ++ ++.. _mac-python.exe: ++ ++Once CPython is done building you will then have a working build ++that can be run in-place; ``./python`` on most machines (and what is used in ++all examples), ``./python.exe`` wherever a case-insensitive filesystem is used ++(e.g. on OS X by default), in order to avoid conflicts with the ``Python`` ++directory. There is normally no need to install your built copy ++of Python! The interpreter will realize where it is being run from ++and thus use the files found in the working copy. If you are worried ++you might accidentally install your working copy build, you can add ++``--prefix=/tmp/python`` to the configuration step. When running from your ++working directory, it is best to avoid using the ``--enable-shared`` flag ++to ``configure``; unless you are very careful, you may accidentally run ++with code from an older, installed shared Python library rather than from ++the interpreter you just built. ++ ++.. _issue tracker: http://bugs.python.org ++ ++ ++Clang ++""""" ++ ++If you are using clang_ to build CPython, some flags you might want to set to ++quiet some standard warnings which are specifically superfluous to CPython are ++``-Wno-unused-value -Wno-empty-body -Qunused-arguments``. You can set your ++``CFLAGS`` environment variable to these flags when running ``configure``. ++ ++If you are using LLVM 2.8, also use the ``-no-integrated-as`` flag in order to ++build the :py:mod:`ctypes` module (without the flag the rest of CPython will ++still build properly). ++ ++ ++.. _windows-compiling: ++ ++Windows ++''''''' ++The readme included in the solution has more details, especially on the ++software needed to resolve the below mentioned build errors. ++ ++**Python 3.3** and later use Microsoft Visual Studio 2010. You can ++download Microsoft Visual C++ 2010 Express `from Microsoft's site ++`_. ++To use it for more than 28 days, one must register through a ++Windows Live account. ++ ++Most Python versions prior to 3.3 use Microsoft Visual Studio 2008. You can ++download Microsoft Visual C++ 2008 Express Edition with SP1 ++from a new location yet to be determined. ++ ++Regardless of Visual Studio version, the ``PCbuild`` directory of a source ++checkout contains the build files for the Python version you are building. ++The full version of Visual Studio is not necessary for common tasks with ++32-bit builds; the gratis C++ Express versions linked above are sufficient. ++Their limitations are given `here (2008) ++`_ ++and `here (2010) ++`_. ++ ++To build from the Visual Studio GUI, open the ``pcbuild.sln`` solution file ++with Visual Studio. If you are using C++ Express, you may get an error message ++indicating solution files are not supported, you can ignore it. Choose the ++:menuselection:`Build Solution` option under the :menuselection:`Build` or ++:menuselection:`Debug` menu (depending on your version of Visual Studio). ++Be sure that "Debug" was chosen as the active solution configuration ++(e.g. under :menuselection:`Build --> Configuration Manager...`) ++ ++When building you may see a number of build errors related to missing ++files or directories. These do not necessarily mean that Python failed ++to build. If you prefer, you can exclude the offending projects from ++the build process by unchecking them inside the ++:menuselection:`Build --> Configuration Manager...` settings. You can ++also use the script :file:`Tools\\buildbot\\external.bat` or ++:file:`Tools\\buildbot\\external-amd64.bat` (as applicable) to download and ++compile missing dependencies. ++ ++Once built you might want to set Python as a startup project. Pressing F5 in ++Visual Studio, or choosing Start Debugging from the Debug menu, will launch ++the interpreter. ++ ++.. _win-python.exe: ++ ++If you want to launch the compiled interpreter from the command-line, the ++path varies according to the build. For a 32-bit build in debug mode, you ++have to invoke ``PCBuild\python_d.exe``, for a 64-bit build in debug mode, ++``PCBuild\amd64\python_d.exe``. If you are compiling in release mode (which ++you shouldn't, in general), replace ``python_d.exe`` with ``python.exe``. ++ ++For additional help for Windows see :ref:`windows-advanced` ++ ++.. _build_troubleshooting: ++ ++Troubleshooting the build ++------------------------- ++ ++This section lists some of the common problems that may arise during the ++compilation of Python, with proposed solutions. ++ ++Avoiding re-creating auto-generated files ++''''''''''''''''''''''''''''''''''''''''' ++ ++Under some circumstances you may encounter Python errors in scripts like ++``Parser/asdl_c.py`` or ``Python/makeopcodetargets.py`` while running ``make``. ++Python auto-generates some of its own code, and a full build from scratch needs ++to run the auto-generation scripts. However, this makes the Python build require ++an already installed Python interpreter; this can also cause version mismatches ++when trying to build an old (2.x) Python with a new (3.x) Python installed, or ++vice versa. ++ ++To overcome this problem, auto-generated files are also checked into the ++Mercurial repository. So if you don't touch the auto-generation scripts, there's ++no real need to auto-generate anything. However, as Mercurial doesn't preserve ++timestamps well, a special build target ``touch`` was added. Run:: ++ ++ make touch ++ ++Before running the compilation ``make``. This will tweak the timestamps of the ++auto-generated files in a way that makes it unnecessary to create them anew and ++henceforth the compilation should not require an installed Python interpreter. ++ ++Editors and Tools ++================= ++ ++Python is used widely enough that practically all code editors have some form ++of support for writing Python code. Various coding tools also include Python ++support. ++ ++For editors and tools which the core developers have felt some special comment ++is needed for coding *in* Python, see :ref:`resources`. ++ ++ ++Directory Structure ++=================== ++ ++There are several top-level directories in the CPython source tree. Knowing what ++each one is meant to hold will help you find where a certain piece of ++functionality is implemented. Do realize, though, there are always exceptions to ++every rule. ++ ++``Doc`` ++ The official documentation. This is what http://docs.python.org/ uses. ++ See also :ref:`building-doc`. ++ ++``Grammar`` ++ Contains the :abbr:`EBNF (Extended Backus-Naur Form)` grammar file for ++ Python. ++ ++``Include`` ++ Contains all interpreter-wide header files. ++ ++``Lib`` ++ The part of the standard library implemented in pure Python. ++ ++``Mac`` ++ Mac-specific code (e.g., using IDLE as an OS X application). ++ ++``Misc`` ++ Things that do not belong elsewhere. Typically this is varying kinds of ++ developer-specific documentation. ++ ++``Modules`` ++ The part of the standard library (plus some other code) that is implemented ++ in C. ++ ++``Objects`` ++ Code for all built-in types. ++ ++``PC`` ++ Windows-specific code along with legacy build files for previously used ++ versions of MSVC. ++ ++``PCbuild`` ++ Build files for the version of MSVC currently used for the Windows ++ installers provided on python.org. ++ ++``Parser`` ++ Code related to the parser. The definition of the AST nodes is also kept ++ here. ++ ++``Python`` ++ The code that makes up the CPython interpreter. This includes the compiler, ++ eval loop and various built-in modules. ++ ++``Tools`` ++ Various tools that are (or have been) used to maintain Python. ++ +diff -r 85f290e474e2 build/_sources/setupWindows.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/setupWindows.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,126 @@ ++.. _windows-advanced: ++ ++============================= ++Setting Up Windows - Advanced ++============================= ++ ++The online directions for downloading the development version source are fine ++and can be found at :ref:`Windows `. There is also ++information in the readme file found in the source directory that is helpful. ++ ++Mercurial must be installed on your machine. ++Stable released version source is available on the download page. ++ ++Subversion is necessary because some of the third party components for the ++windows built are still in a subversion repository. ++ ++Python building/rebuilding assumes the existence of subversion, perl, and a ++version of Visual Studio on your system. If you have all three, skip to step ++three. Otherwise download and install any of those that are missing. ++ ++If it is necessary to have on hand multiple versions of python built from scratch, you ++should isolate them from each other by putting them in a container directory ++perhaps of the same name:: ++ ++ python331/python331, python32/python32 ++ ++where the subdirectory is the source root directory. Use the upper directory ++to isolate the external subprojects created by the buildbots described later. ++The buildbots of one version can wipe out required subprojects of another ++version of python which can cause confusion. ++ ++------ ++Step 0 ++------ ++ ++Download and install a subversion client and add the executable to your path. ++ ++------ ++Step 1 ++------ ++ ++Download and install perl and add the executable to your path. ++ ++------ ++Step 2 ++------ ++ ++Download and install Visual Studio 2010. Either Express C++ will work or ++Visual Studio Professional. Express is free, however, when the solution file ++is loaded, an error message is displayed. ++ ++Visual Studio should be in your path. ++ ++------ ++Step 3 ++------ ++ ++Download and install `NASM `_ ++ ++------ ++Step 4 ++------ ++ ++Download and build the external subprojects with the buildbots using either:: ++ ++ Tools\buildbot\external.bat # for 32 bit processors ++ Tools\buildbot\external-amd64.bat # for 64 bit processors ++ ++from the root directory or your python distribution. ++This step will download the correct versions of the external projects for ++this version of python. There are several projects ++ ++------ ++Step 5 ++------ ++ ++ ++openssl is used for python on windows ++ssl rarely succeeds if you proceed to build using pcbuild.sln: ++ ++The following steps will resolve many problems if you executing them ++before building with the .sln file:: ++ ++ cd into the openssl directory created by the buildbots ++ perl util\mkdef.pl crypto ssl update ++ perl Configure VC-WIN32 --prefix=C:\opt\openssl-1.0.1d ++ ms\do_nasm ++ ++Compilation errors may occur when you attempt to build the .sln file with ++Visual Studio. The errors are typically a forced error contained within a ++block of conditional code. Good results have been found by commenting out ++the forced error. Most recently commenting out code blocks in ++mdc2.h and idea.h produced good results. ++ ++Historically, the openssl build has not had a "clean" function. Cleaning the ++project by deleting and letting the buildbot download again gave good results. ++ ++ ++------ ++Step 6 ++------ ++ ++Finally Build python and its internal subprojects ++ ++ Open the solution "pcbuild.sln" in Visual Studio ++ If you have an express version, then ignore the warning ++ Select the configuration (Release or Debug) :: ++ ++ "Release" builds python.exe ++ "Debug" builds python_d.exe ++ Select the platform Win32 or x64 ++ Build the solution. ++ Right click "Solution 'pccuild'" and select ++ build - for fresh build ++ clean - to delete all files created for build , i.e. objects, ++ libraries, executable, etc. ++ rebuild - clean and build everything ++ ++Note that you can clean and build individual subprojects by right clicking ++on the subproject and selecting build, clean, or rebuild for that project ++ ++Using Visual Studio ++=================== ++ ++There is `Python Tools for Visual Studio `_ an addon published ++by Microsoft for many versions of Visual Studio except the Express editions. +\ No newline at end of file +diff -r 85f290e474e2 build/_sources/silencewarnings.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/silencewarnings.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,18 @@ ++.. _silencewarnings: ++ ++Silence Warnings From the Test Suite ++==================================== ++ ++When running Python's test suite, no warnings should result when you run it ++under :ref:`strenuous testing conditions ` (you can ignore ++the extra flags passed to ``test`` that cause randomness and parallel execution ++if you want). Unfortunately new warnings are added to Python on occasion which ++take some time to eliminate (e.g., ``ResourceWarning``). Typically the easy ++warnings are dealt with quickly, but the more difficult ones that require some ++thought and work do not get fixed immediately. ++ ++If you decide to tackle a warning you have found, open an issue on the `issue ++tracker`_ (if one has not already been opened) and say you are going to try and ++tackle the issue, and then proceed to fix the issue. ++ ++.. _issue tracker: http://bugs.python.org +diff -r 85f290e474e2 build/_sources/stdlibchanges.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/stdlibchanges.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,151 @@ ++.. _stdlibchanges: ++ ++Adding to the Stdlib ++==================== ++ ++While the stdlib contains a great amount of useful code, sometimes you want ++more than is provided. This document is meant to explain how you can get either ++a new addition to a pre-existing module in the stdlib or add an entirely new ++module. ++ ++Changes to pre-existing code is not covered as that is considered a bugfix and ++thus is treated as a bug that should be filed on the `issue tracker`_. ++ ++.. _issue tracker: http://bugs.python.org/ ++ ++ ++Adding to a pre-existing module ++------------------------------- ++ ++If you have found that a function, method, or class is useful and you believe ++it would be useful to the general Python community, there are some steps to go ++through in order to see it added to the stdlib. ++ ++First is you should gauge the usefulness of the code. Typically this is done ++by sharing the code publicly. You have a couple of options for this. One is to ++post it online at the `Python Cookbook`_. Based on feedback or reviews of the ++recipe you can see if others find the functionality as useful as you do. ++A search of the issue tracker for previous suggestions related to the proposed ++addition may turn up a rejected issue that explains why the suggestion will not ++be accepted. ++Another is to do a blog post about the code and see what kind of responses you ++receive. Posting to python-list (see :ref:`communication` for where to find the ++list and other mailing lists) to discuss your code also works. Finally, asking ++on a specific :abbr:`SIG (special interest group)` from mail.python.org or ++python-ideas is also acceptable. This is not a required step but it is ++suggested. ++ ++If you have found general acceptance and usefulness for your code from people, ++you can open an issue on the `issue tracker`_ with the code attached as a ++:ref:`patch `. If possible, also submit a ++:ref:`contributor agreement `. ++ ++If a core developer decides that your code would be useful to the general ++Python community, they will then commit your code. If your code is not picked ++up by a core developer and committed then please do not take this personally. ++Through your public sharing of your code in order to gauge community support ++for it you at least can know that others will come across it who may find it ++useful. ++ ++.. _Python Cookbook: http://code.activestate.com/recipes/langs/python/ ++ ++ ++Adding a new module ++------------------- ++It must be stated upfront that getting a new module into the stdlib is very ++difficult. Adding any significant amount of code to the stdlib increases the ++burden placed upon core developers. It also means that the module somewhat ++becomes "sanctioned" by the core developers as a good way to do something, ++typically leading to the rest of the Python community to using the new module ++over other available solutions. All of this means that additions to the stdlib ++are not taken lightly. ++ ++ ++Acceptable Types of Modules ++''''''''''''''''''''''''''' ++Typically two types of modules get added to the stdlib. One type is a module ++which implements something that is difficult to get right. A good example of ++this is the :py:mod:`multiprocessing` package. Working out the various OS ++issues, working through concurrency issues, etc. are all very difficult to get ++right. ++ ++The second type of module is one that implements something that people ++re-implement constantly. The :py:mod:`itertools` module is a good example of ++this type as its constituent parts are not necessarily complex, but are used ++regularly in a wide range of programs and can be a little tricky to get right. ++Modules that parse widely used data formats also fall under this type of module ++that the stdlib consists of. ++ ++While a new stdlib module does not need to appeal to all users of Python, it ++should be something that a large portion of the community will find useful. ++This makes sure that the developer burden placed upon core developers is worth ++it. ++ ++ ++Requirements ++'''''''''''''' ++In order for a module to even be considered for inclusion into the stdlib, a ++couple of requirements must be met. ++ ++The most basic is that the code must meet ++:ref:`standard patch requirements `. For code that has ++been developed outside the stdlib typically this means making sure the coding ++style guides are followed and that the proper tests have been written. ++ ++The module needs to have been out in the community for at least a year. Because ++of Python's conservative nature when it comes to backwards-compatibility, when ++a module is added to the stdlib its API becomes frozen. This means that a module ++should only enter the stdlib when it is mature and gone through its ++"growing pains". ++ ++The module needs to be considered best-of-breed. When something is included in ++the stdlib it tends to be chosen first for products over other third-party ++solutions. By virtue of having been available to the public for at least a ++year, a module needs to have established itself as (one of) the top choices by ++the community for solving the problem the module is intended for. ++ ++The development of the module must move into Python's ++infrastructure (i.e., the module is no longer directly maintained outside of ++Python). This prevents a divergence between the code that is included in the ++stdlib and that which is released outside the stdlib (typically done to provide ++the module to older versions of Python). It also removes the burden of forcing ++core developers to have to redirect bug reports or patches to an external issue ++tracker and :abbr:`VCS (version control system)`. ++ ++Someone involved with the development of the ++module must promise to help maintain the module in the stdlib for two years. ++This not only helps out other core developers by alleviating workload from bug ++reports that arrive from the first Python release containing the module, but ++also helps to make sure that the overall design of the module continues to be ++uniform. ++ ++ ++Proposal Process ++'''''''''''''''' ++If the module you want to propose adding to the stdlib meets the proper ++requirements, you may propose its inclusion. To start, you should email ++python-list or python-ideas to make sure the community in general would support ++the inclusion of the module (see :ref:`communication`). ++ ++If the feedback from the community is positive overall, you will need to write ++a :abbr:`PEP (Python enhancement proposal)` for the module's inclusion. It ++should outline what the module's overall goal is, why it should be included in ++the stdlib, and specify the API of the module. See the `PEP index`_ for PEPs ++that have been accepted before that proposed a module for inclusion. ++ ++Once your PEP is written, send it to python-ideas for basic vetting. Be ++prepared for extensive feedback and lots of discussion (not all of it ++positive). This will help make the PEP be of good quality and properly ++formatted. ++ ++When you have listened to, responded, and integrated as appropriate the ++feedback from python-ideas into your PEP, you may send it to python-dev. You ++will once again receive a large amount of feedback and discussion. A PEP ++dictator will be assigned who makes the final call on whether the PEP will be ++accepted or not. If the PEP dictator agrees to accept your PEP (which typically ++means that the core developers end up agreeing in general to accepting ++your PEP) then the module ++will be added to the stdlib once the creators of the module sign ++:ref:`contributor agreements `. ++ ++.. _PEP index: http://www.python.org/dev/peps/ +diff -r 85f290e474e2 build/_sources/tracker.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/tracker.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,201 @@ ++============== ++Issue Tracking ++============== ++ ++.. _tracker: ++ ++Using the Issue Tracker ++======================= ++ ++If you think you found a bug in Python, you can report it to the ++`issue tracker`_. Documentation bugs can also be reported there. ++Issues about the tracker should be reported to the `meta tracker`_. ++ ++ ++Checking if a bug already exists ++-------------------------------- ++ ++The first step in filing a report is to determine whether the problem has ++already been reported. The advantage in doing so, aside from saving the ++developers time, is that you learn what has been done to fix it; it may be that ++the problem has already been fixed for the next release, or additional ++information is needed (in which case you are welcome to provide it if you can!). ++ ++To do this, search the bug database using the search box on the top of the page. ++An `advanced search`_ is also available by clicking on "Search" in ++the sidebar. ++ ++ ++Reporting an issue ++------------------ ++ ++If the problem you're reporting is not already in the `issue tracker`_, you ++need to log in by entering your user and password in the form on the left. ++If you don't already have a tracker account, select the "Register" link or, ++if you use OpenID, one of the OpenID provider logos in the sidebar. ++ ++It is not possible to submit a bug report anonymously. ++ ++Being now logged in, you can submit a bug by clicking on the "Create New" link ++in the sidebar. ++ ++The submission form has a number of fields, and they are described in detail ++in the :ref:`triaging` page. This is a short summary: ++ ++* in the **Title** field, enter a *very* short description of the problem; ++ less than ten words is good; ++* in the **Type** field, select the type of your problem (usually behavior); ++* if you know which **Components** and **Versions** are affected by the issue, ++ you can select these too; ++* if you have JavaScript enabled, you can use the **Nosy List** field to search ++ developers that can help with the issue by entering the name of the affected ++ module, operating system, or interest area. ++* last but not least, you have to describe the problem in detail, including ++ what you expected to happen and what did happen, in the **Comment** field. ++ Be sure to include whether any extension modules were involved, and what ++ hardware and software platform you were using (including version information ++ as appropriate). ++ ++The triaging team will take care of setting other fields, and possibly assign ++the issue to a specific developer. You will automatically receive an update ++each time an action is taken on the bug. ++ ++ ++.. _helptriage: ++ ++Helping Triage Issues ++===================== ++ ++Once you know your way around how Python's source files are ++structured and you are comfortable working with patches, a great way to ++participate is to help triage issues. Do realize, though, that experience ++working on Python is needed in order to effectively help triage. ++ ++Around the clock, new issues are being opened on the `issue tracker`_ and ++existing issues are being updated. Every ++issue needs to be triaged to make sure various things are in proper order. Even ++without special privileges you can help with this process. ++ ++ ++Classifying Reports ++------------------- ++ ++For bugs, an issue needs to: ++ ++* clearly explain the bug so it can be reproduced ++* include all relevant platform details ++* state what version(s) of Python are affected by the bug. ++ ++These are things you can help with once you have experience developing for ++Python. For instance, if a bug is not clearly explained enough for you to ++reproduce it then there is a good chance a core developer won't be able to ++either. And it is always helpful to know if a bug not only affects the ++in-development version of Python, but whether it also affects other versions in ++maintenance mode. And if the bug lacks a unit test that should end up in ++Python's test suite, having that written can be very helpful. ++ ++This is all helpful as it allows triagers (i.e., ++:ref:`people with the Developer role on the issue tracker `) to ++properly classify an issue so it can be handled by the right core developers in ++a timely fashion. ++ ++ ++Reviewing Patches ++----------------- ++ ++If an issue has a patch attached that has not been reviewed, you can help by ++making sure the patch: ++ ++* follows the style guides ++* applies cleanly to an up-to-date clone ++* is a good solution to the problem it is trying to solve ++* includes proper tests ++* includes proper documentation changes ++* submitter is listed in ``Misc/ACKS``, either already or the patch adds them ++ ++Doing all of this allows core developers and :ref:`triagers ` to more ++quickly look for subtle issues that only people with extensive experience ++working on Python's code base will notice. ++ ++ ++Finding an Issue You Can Help With ++---------------------------------- ++ ++If you want to help triaging issues, you might also want to search for issues ++that you are knowledgeable about. An easy way to do it, is to search for ++the name of a module you are familiar with. You can also use the ++`advanced search`_ and search for specific components (e.g. "Windows" if you ++are a Windows developer, "Extension Modules" if you are familiar with C, etc.). ++Finally you can use the "Random issue" link in the sidebar to pick random ++issues until you find an issue that you like. Is not so uncommon to find old ++issues that can be closed, either because they are no longer valid, or ++because they have a patch that is ready to be committed, but no one had ++time to do it yet. ++ ++In the sidebar you can also find links to summaries for easy issues and ++issues with a patch. ++ ++ ++.. _devrole: ++ ++Gaining the "Developer" Role on the Issue Tracker ++================================================= ++ ++When you have consistently shown the ability to properly ++help triage issues without guidance, you may request that you ++be given the "Developer" role on the `issue tracker`_. You can make the request ++of any person who already has the Developer role. If they decide you are ready ++to gain the extra privileges on the tracker they will then act as a mentor to ++you until you are ready to do things entirely on your own. There is no set rule ++as to how many issues you need to have helped with before or how long you have ++been participating. The key requirements are that you show the desire to ++help, you are able to work well with others (especially those already with the ++Developer role), and that have a firm grasp of how to do things on the issue ++tracker properly on your own. ++ ++Gaining the Developer role will allow you to set any value on any issue in the ++tracker, releasing you from the burden of having to ask others to set values on ++an issue for you in order to properly triage something. This will not only help ++speed up and simplify your work in helping out, but also help lessen the ++workload for everyone by gaining your help. ++ ++ ++The Meta Tracker ++================ ++ ++If you find an issue with the `issue tracker`_, you can report it to the ++`meta tracker`_. The meta tracker is where you file issues against anything ++you come across when working with the issue tracker itself (e.g you can't ++attach a file, the layout is broken on your browser, Rietveld gave you an ++error, etc.). ++ ++If you want to contribute to the tracker you can get a checkout of the source ++and install a local instance where to experiment. You can find detailed ++instructions on the `Tracker Development`_ page. ++ ++ ++.. seealso:: ++ ++ `The Python issue tracker `_ ++ Where to report issues about Python. ++ ++ `The New-bugs-announce mailing list `_ ++ Where all the new issues created on the tracker are reported. ++ ++ `The Python-bugs-list mailing list `_ ++ Where all the changes to issues are reported. ++ ++ `The meta tracker `_ ++ Where to report issues about the tracker itself. ++ ++ `The Tracker development wiki page `_ ++ Instructions about setting up a local instance of the bug tracker. ++ ++ `The Tracker-discuss mailing list `_ ++ Discussions about the bug tracker. ++ ++ ++.. _issue tracker: http://bugs.python.org/ ++.. _meta tracker: http://psf.upfronthosting.co.za/roundup/meta/ ++.. _advanced search: http://bugs.python.org/issue?@template=search ++.. _Tracker Development: http://wiki.python.org/moin/TrackerDevelopment +diff -r 85f290e474e2 build/_sources/triaging.txt +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_sources/triaging.txt Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,326 @@ ++.. _triaging: ++ ++Triaging an Issue ++================= ++ ++When you have the Developer role on the `issue tracker`_ you are able to triage ++issues directly without any assistance. ++ ++Fields ++------ ++ ++Title ++''''' ++Should be properly descriptive of what the issue is about. Occasionally ++people file an issue that either has too generic of a title or end up thinking ++they filed about X but in fact it turns out to be about Y and thus the ++title is now wrong. ++ ++Type ++'''' ++Describes the type of issue. If something does not fit within any ++specific type then simply do not set it. ++ ++behavior ++ Wrong or unexpected behavior, result, or exception. This includes most of ++ the bugs. ++crash ++ Hard crashes of the Python interpreter -- possibly with a core ++ dump or a Windows error box. ++compile error ++ Errors reported by the compiler while compiling Python. ++resource usage ++ Situations where too many resources (e.g. memory) are used. ++security ++ Issues that might have security implications. If you think the issue ++ should not be made public, please report it to security@python.org instead. ++performance ++ Situations where too much time is necessary to complete the task. ++enhancement ++ Issues that propose the addition of new functionality, such as new ++ functions, classes, modules, or even new arguments for existing functions. ++ Also used for improvements in the documentation and test suite and for ++ other refactorings. ++ ++Stage ++''''' ++What is needed next to advance the issue. The *stage* needn't be set until ++it is clear that the issue warrants fixing. ++ ++test needed ++ The bug reporter should post a script or instructions to let a triager or ++ developer reproduce the issue. ++needs patch ++ The issue lacks a patch to solve the problem (i.e. fixing the bug, or ++ adding the requested improvement). ++patch review ++ There is a patch, but it needs reviewing or is in the process of being ++ reviewed. This can be done by any triager as well as a core developer. ++commit review ++ A triager performed a patch review and it looks good to them, but a core ++ developer needs to commit the patch (and do a quick once-over to make sure ++ nothing was overlooked). ++committed/rejected ++ The issue is considered closed and dealt with. ++ ++Components ++'''''''''' ++What part of Python is affected by the issue. This is a multi-select field. ++Be aware that what component is chosen may cause the issue to be auto-assigned, ++i.e. the issue tracker may automatically fill in the `Assigned To`_ field ++after you press ``Submit changes``. ++ ++The following component(s) should be selected if the issue applies to: ++ ++2to3 (2.x to 3.0 conversion tool) ++ The 2to3 conversion tool in `Lib/lib2to3`_. ++Benchmarks ++ The benchmarks in the benchmarks_ repo. ++Build ++ The build process. ++ctypes ++ The ctypes package in `Lib/ctypes`_. ++Demos and Tools ++ The files in Tools_ and `Tools/demo`_. ++Devguide ++ The `Developer's guide`_. ++Distutils ++ The distutils package in `Lib/distutils`_. ++Distutils2 ++ The packaging module in `Lib/packaging`_. ++Documentation ++ The documentation in Doc_ (used to build the HTML doc at http://docs.python.org/). ++email ++ The email package and related modules. ++Extension Modules ++ C modules in Modules_. ++IDLE ++ The `Lib/idlelib`_ package. ++Installation ++ The installation process. ++Interpreter Core ++ The interpreter core, the built-in objects in `Objects`_, the `Python`_, ++ `Grammar`_ and `Parser`_ dirs. ++IO ++ The I/O system, `Lib/io.py`_ and `Modules/_io`_. ++Library (Lib) ++ Python modules in Lib_. ++Macintosh ++ The Mac OS X operating system. ++Regular Expressions ++ The `Lib/re.py`_ and `Modules/_sre.c`_ modules. ++Tests ++ The unittest and doctest frameworks in `Lib/unittest`_ and ++ `Lib/doctest.py`_. ++ ++ The CPython tests in `Lib/test`_, the test runner in `Lib/test/regrtest.py`_ ++ and the `Lib/test/support.py`_ module. ++Tkinter ++ The `Lib/tkinter`_ package. ++Unicode ++ Unicode, codecs, str vs bytes, `Objects/unicodeobject.c`_. ++Windows ++ The Windows operating system. ++XML ++ The `Lib/xml`_ package. ++ ++Versions ++'''''''' ++The known versions of Python that the issue affects and should be fixed for. ++Thus if an issue for a new feature is assigned for e.g., Python 3.3 but is not ++applied before Python 3.3.0 is released, this field should be updated to say ++Python 3.4 as the version and drop Python 3.3. ++ ++Priority ++'''''''' ++How important is this issue? ++ ++low ++ This is for low-impact bugs, or feature requests of little utility. ++normal ++ The default value for most issues, which deserve fixing but without ++ any urgency to do so. ++high ++ Make some effort to fix the issue before the next final release. ++critical ++ This issue should definitely be fixed before the next final release. ++deferred blocker ++ The issue will not hold up the next release, but will be promoted to a ++ release blocker for the following release, e.g., won't block the next ++ release of a1 but will block a2. ++release blocker ++ The issue must be fixed before *any* release is made, e.g., will block the ++ next release even if it is an alpha release. ++ ++As a guideline, *critical* and above are usually reserved for crashes, ++serious regressions or breakage of very important APIs. Whether a bug ++is a *release blocker* is a decision better left to the release manager so, ++in any doubt, add him or her to the *nosy list*. ++ ++Keywords ++'''''''' ++Various flags about the issue. Multiple values are possible. ++ ++buildbot ++ A buildbot triggered the issue being reported. ++easy ++ Fixing the issue should not take longer than a day for someone new to ++ contributing to Python to solve. ++gsoc ++ The issue would fit as, or is related to, a GSoC_ project. ++needs review ++ The patch attached to the issue is in need of a review. ++patch ++ There is a patch attached to the issue. ++3.3regression ++ The issue is a regression in 3.3. ++ ++Nosy List ++''''''''' ++A list of people who may be interested in an issue. It is acceptable to add ++someone to the nosy list if you think the issue should be brought to their ++attention. Use the :ref:`experts` to know who wants to be added to the nosy ++list for issues targeting specific areas. ++ ++ ++If you are logged in and have JavaScript enabled, you can use the ``[+]`` ++button to add yourself to the nosy list (remember to click on ++"Submit Changes" afterwards). Note that you are added to the nosy ++automatically when you submit a message. ++The nosy list also has an autocomplete that lets you search from the lists of ++developers and :ref:`experts`. The search is case-insensitive and ++works for real names, modules, interest areas, etc., and only adds the ++username(s) to the nosy once an entry is selected. ++ ++Assigned To ++''''''''''' ++Who is expected to take the next step in resolving the issue. It is acceptable ++to assign an issue to someone if the issue cannot move forward without their ++help, e.g., they need to make a technical decision to allow the issue to move ++forward. Also consult the :ref:`experts` as certain stdlib modules should ++always be assigned to a specific person. ++ ++Dependencies ++'''''''''''' ++The issue requires the listed issue(s) to be resolved first before it can move ++forward. ++ ++Superseder ++'''''''''' ++The issue is a duplicate of the listed issue(s). ++ ++Status ++'''''' ++open ++ Issue is not resolved. ++languishing ++ The issue has no clear solution , e.g., no agreement on a technical ++ solution or if it is even a problem worth fixing. ++pending ++ The issue is blocked until someone (often the ++ :abbr:`OP (original poster)`) provides some critical information; ++ the issue will be closed after a set amount of time if no reply comes in. ++ Useful when someone opens an issue that lacks enough information to ++ reproduce the bug reported. Requesting additional information and setting ++ status to *pending* indicates that the issue should be closed if the ++ necessary information is never provided. ++closed ++ The issue has been resolved (somehow). ++ ++Resolution ++'''''''''' ++Why the issue is in its current state (not usually used for "open"). ++ ++duplicate ++ Duplicate of another issue; should have the Superseder field filled out. ++fixed ++ A fix for the issue was committed. ++invalid ++ For some reason the issue is invalid (e.g. the perceived problem is not ++ a bug in Python). ++later ++ Issue is to be worked on at a later date. ++out of date ++ The issue has already been fixed, or the problem doesn't exist anymore ++ for other reasons. ++postponed ++ Issue will not be worked on at the moment. ++rejected ++ Issue was rejected (especially for feature requests). ++remind ++ The issue is acting as a reminder for someone. ++wont fix ++ Issue will not be fixed, typically because it would cause a ++ backwards-compatibility problem. ++works for me ++ Bug cannot be reproduced. ++ ++Mercurial Repository ++'''''''''''''''''''' ++HTTP link to a Mercurial repository that contains a patch for the issue. ++A :guilabel:`Create Patch` button will appear that computes a diff for the ++head revision of the remote branch and attaches it to the issue. The button ++supports only CPython_ patches. ++ ++If you don't indicate a remote branch, ``default`` is used. You can ++indicate a remote branch by adding ``#BRANCH`` to the end of the URL. ++ ++Generating Special Links in a Comment ++------------------------------------- ++Comments can automatically generate a link to various web pages if formatted ++properly. ++ ++* ``#``, ``issue``, or ``issue `` links to the ++ tracker issue ````. ++* ``msg`` links to the tracker message ````. ++* a 12-digit or 40-digit hex ```` is assumed to be a Mercurial ++ changeset identifier and generates a link to changeset ```` ++ in the official Python source code repositories. ++* ``r``, ``rev``, or ``revision `` is assumed to be ++ a legacy Subversion revision number, a reference to a changeset that was ++ checked in prior to 2011-03-05 when the official Python source code ++ repositories were migrated from the :abbr:`svn (Subversion)` ++ :abbr:`VCS (version control system)` to Mercurial. ++ The issue tracker automatically translates the legacy svn revision ++ ```` to its corresponding Mercurial changeset identifier. ++* ``Dir/file.ext`` and ``Dir/file.ext:NNN`` generate links to files in the ++ `Python source code repositories `_, ++ possibly linking to the line number specified after the ``:``. ++* ``PEP `` and ``PEP`` link to the ++ :abbr:`PEP (Python Enhancement Proposal)` ````. ++* ``devguide`` (lowercase), ``devguide/triaging``, and ++ ``devguide/triaging#generating-special-links-in-a-comment`` generate links to ++ the Devguide, this page, and this section respectively. ++ ++ ++.. _CPython: http://hg.python.org/cpython/file/default/ ++.. _Doc: http://hg.python.org/cpython/file/default/Doc/ ++.. _Grammar: http://hg.python.org/cpython/file/default/Grammar/ ++.. _Lib: http://hg.python.org/cpython/file/default/Lib/ ++.. _Lib/lib2to3: http://hg.python.org/cpython/file/default/Lib/lib2to3/ ++.. _Lib/ctypes: http://hg.python.org/cpython/file/default/Lib/ctypes/ ++.. _Lib/distutils: http://hg.python.org/cpython/file/default/Lib/distutils/ ++.. _Lib/doctest.py: http://hg.python.org/cpython/file/default/Lib/doctest.py ++.. _Lib/idlelib: http://hg.python.org/cpython/file/default/Lib/idlelib/ ++.. _Lib/io.py: http://hg.python.org/cpython/file/default/Lib/io.py ++.. _Lib/packaging: http://hg.python.org/cpython/file/default/Lib/packaging/ ++.. _Lib/re.py: http://hg.python.org/cpython/file/default/Lib/re.py ++.. _Lib/test: http://hg.python.org/cpython/file/default/Lib/test/ ++.. _Lib/test/regrtest.py: http://hg.python.org/cpython/file/default/Lib/test/regrtest.py ++.. _Lib/test/support.py: http://hg.python.org/cpython/file/default/Lib/test/support.py ++.. _Lib/tkinter: http://hg.python.org/cpython/file/default/Lib/tkinter/ ++.. _Lib/unittest: http://hg.python.org/cpython/file/default/Lib/unittest/ ++.. _Lib/xml: http://hg.python.org/cpython/file/default/Lib/xml/ ++.. _Modules: http://hg.python.org/cpython/file/default/Modules/ ++.. _Modules/_io: http://hg.python.org/cpython/file/default/Modules/_io/ ++.. _Modules/_sre.c: http://hg.python.org/cpython/file/default/Modules/_sre.c ++.. _Objects: http://hg.python.org/cpython/file/default/Objects/ ++.. _Objects/unicodeobject.c: http://hg.python.org/cpython/file/default/Objects/unicodeobject.c ++.. _Parser: http://hg.python.org/cpython/file/default/Parser/ ++.. _Python: http://hg.python.org/cpython/file/default/Python/ ++.. _Tools: http://hg.python.org/cpython/file/default/Tools/ ++.. _Tools/demo: http://hg.python.org/cpython/file/default/Tools/demo/ ++.. _benchmarks: http://hg.python.org/benchmarks/ ++.. _Developer's guide: http://hg.python.org/devguide/ ++.. _GSoC: http://code.google.com/soc/ ++.. _issue tracker: http://bugs.python.org +diff -r 85f290e474e2 build/_static/ajax-loader.gif +Binary file build/_static/ajax-loader.gif has changed +diff -r 85f290e474e2 build/_static/basic.css +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_static/basic.css Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,537 @@ ++/* ++ * basic.css ++ * ~~~~~~~~~ ++ * ++ * Sphinx stylesheet -- basic theme. ++ * ++ * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. ++ * :license: BSD, see LICENSE for details. ++ * ++ */ ++ ++/* -- main layout ----------------------------------------------------------- */ ++ ++div.clearer { ++ clear: both; ++} ++ ++/* -- relbar ---------------------------------------------------------------- */ ++ ++div.related { ++ width: 100%; ++ font-size: 90%; ++} ++ ++div.related h3 { ++ display: none; ++} ++ ++div.related ul { ++ margin: 0; ++ padding: 0 0 0 10px; ++ list-style: none; ++} ++ ++div.related li { ++ display: inline; ++} ++ ++div.related li.right { ++ float: right; ++ margin-right: 5px; ++} ++ ++/* -- sidebar --------------------------------------------------------------- */ ++ ++div.sphinxsidebarwrapper { ++ padding: 10px 5px 0 10px; ++} ++ ++div.sphinxsidebar { ++ float: left; ++ width: 230px; ++ margin-left: -100%; ++ font-size: 90%; ++} ++ ++div.sphinxsidebar ul { ++ list-style: none; ++} ++ ++div.sphinxsidebar ul ul, ++div.sphinxsidebar ul.want-points { ++ margin-left: 20px; ++ list-style: square; ++} ++ ++div.sphinxsidebar ul ul { ++ margin-top: 0; ++ margin-bottom: 0; ++} ++ ++div.sphinxsidebar form { ++ margin-top: 10px; ++} ++ ++div.sphinxsidebar input { ++ border: 1px solid #98dbcc; ++ font-family: sans-serif; ++ font-size: 1em; ++} ++ ++div.sphinxsidebar #searchbox input[type="text"] { ++ width: 170px; ++} ++ ++div.sphinxsidebar #searchbox input[type="submit"] { ++ width: 30px; ++} ++ ++img { ++ border: 0; ++ max-width: 100%; ++} ++ ++/* -- search page ----------------------------------------------------------- */ ++ ++ul.search { ++ margin: 10px 0 0 20px; ++ padding: 0; ++} ++ ++ul.search li { ++ padding: 5px 0 5px 20px; ++ background-image: url(file.png); ++ background-repeat: no-repeat; ++ background-position: 0 7px; ++} ++ ++ul.search li a { ++ font-weight: bold; ++} ++ ++ul.search li div.context { ++ color: #888; ++ margin: 2px 0 0 30px; ++ text-align: left; ++} ++ ++ul.keywordmatches li.goodmatch a { ++ font-weight: bold; ++} ++ ++/* -- index page ------------------------------------------------------------ */ ++ ++table.contentstable { ++ width: 90%; ++} ++ ++table.contentstable p.biglink { ++ line-height: 150%; ++} ++ ++a.biglink { ++ font-size: 1.3em; ++} ++ ++span.linkdescr { ++ font-style: italic; ++ padding-top: 5px; ++ font-size: 90%; ++} ++ ++/* -- general index --------------------------------------------------------- */ ++ ++table.indextable { ++ width: 100%; ++} ++ ++table.indextable td { ++ text-align: left; ++ vertical-align: top; ++} ++ ++table.indextable dl, table.indextable dd { ++ margin-top: 0; ++ margin-bottom: 0; ++} ++ ++table.indextable tr.pcap { ++ height: 10px; ++} ++ ++table.indextable tr.cap { ++ margin-top: 10px; ++ background-color: #f2f2f2; ++} ++ ++img.toggler { ++ margin-right: 3px; ++ margin-top: 3px; ++ cursor: pointer; ++} ++ ++div.modindex-jumpbox { ++ border-top: 1px solid #ddd; ++ border-bottom: 1px solid #ddd; ++ margin: 1em 0 1em 0; ++ padding: 0.4em; ++} ++ ++div.genindex-jumpbox { ++ border-top: 1px solid #ddd; ++ border-bottom: 1px solid #ddd; ++ margin: 1em 0 1em 0; ++ padding: 0.4em; ++} ++ ++/* -- general body styles --------------------------------------------------- */ ++ ++a.headerlink { ++ visibility: hidden; ++} ++ ++h1:hover > a.headerlink, ++h2:hover > a.headerlink, ++h3:hover > a.headerlink, ++h4:hover > a.headerlink, ++h5:hover > a.headerlink, ++h6:hover > a.headerlink, ++dt:hover > a.headerlink { ++ visibility: visible; ++} ++ ++div.body p.caption { ++ text-align: inherit; ++} ++ ++div.body td { ++ text-align: left; ++} ++ ++.field-list ul { ++ padding-left: 1em; ++} ++ ++.first { ++ margin-top: 0 !important; ++} ++ ++p.rubric { ++ margin-top: 30px; ++ font-weight: bold; ++} ++ ++img.align-left, .figure.align-left, object.align-left { ++ clear: left; ++ float: left; ++ margin-right: 1em; ++} ++ ++img.align-right, .figure.align-right, object.align-right { ++ clear: right; ++ float: right; ++ margin-left: 1em; ++} ++ ++img.align-center, .figure.align-center, object.align-center { ++ display: block; ++ margin-left: auto; ++ margin-right: auto; ++} ++ ++.align-left { ++ text-align: left; ++} ++ ++.align-center { ++ text-align: center; ++} ++ ++.align-right { ++ text-align: right; ++} ++ ++/* -- sidebars -------------------------------------------------------------- */ ++ ++div.sidebar { ++ margin: 0 0 0.5em 1em; ++ border: 1px solid #ddb; ++ padding: 7px 7px 0 7px; ++ background-color: #ffe; ++ width: 40%; ++ float: right; ++} ++ ++p.sidebar-title { ++ font-weight: bold; ++} ++ ++/* -- topics ---------------------------------------------------------------- */ ++ ++div.topic { ++ border: 1px solid #ccc; ++ padding: 7px 7px 0 7px; ++ margin: 10px 0 10px 0; ++} ++ ++p.topic-title { ++ font-size: 1.1em; ++ font-weight: bold; ++ margin-top: 10px; ++} ++ ++/* -- admonitions ----------------------------------------------------------- */ ++ ++div.admonition { ++ margin-top: 10px; ++ margin-bottom: 10px; ++ padding: 7px; ++} ++ ++div.admonition dt { ++ font-weight: bold; ++} ++ ++div.admonition dl { ++ margin-bottom: 0; ++} ++ ++p.admonition-title { ++ margin: 0px 10px 5px 0px; ++ font-weight: bold; ++} ++ ++div.body p.centered { ++ text-align: center; ++ margin-top: 25px; ++} ++ ++/* -- tables ---------------------------------------------------------------- */ ++ ++table.docutils { ++ border: 0; ++ border-collapse: collapse; ++} ++ ++table.docutils td, table.docutils th { ++ padding: 1px 8px 1px 5px; ++ border-top: 0; ++ border-left: 0; ++ border-right: 0; ++ border-bottom: 1px solid #aaa; ++} ++ ++table.field-list td, table.field-list th { ++ border: 0 !important; ++} ++ ++table.footnote td, table.footnote th { ++ border: 0 !important; ++} ++ ++th { ++ text-align: left; ++ padding-right: 5px; ++} ++ ++table.citation { ++ border-left: solid 1px gray; ++ margin-left: 1px; ++} ++ ++table.citation td { ++ border-bottom: none; ++} ++ ++/* -- other body styles ----------------------------------------------------- */ ++ ++ol.arabic { ++ list-style: decimal; ++} ++ ++ol.loweralpha { ++ list-style: lower-alpha; ++} ++ ++ol.upperalpha { ++ list-style: upper-alpha; ++} ++ ++ol.lowerroman { ++ list-style: lower-roman; ++} ++ ++ol.upperroman { ++ list-style: upper-roman; ++} ++ ++dl { ++ margin-bottom: 15px; ++} ++ ++dd p { ++ margin-top: 0px; ++} ++ ++dd ul, dd table { ++ margin-bottom: 10px; ++} ++ ++dd { ++ margin-top: 3px; ++ margin-bottom: 10px; ++ margin-left: 30px; ++} ++ ++dt:target, .highlighted { ++ background-color: #fbe54e; ++} ++ ++dl.glossary dt { ++ font-weight: bold; ++ font-size: 1.1em; ++} ++ ++.field-list ul { ++ margin: 0; ++ padding-left: 1em; ++} ++ ++.field-list p { ++ margin: 0; ++} ++ ++.optional { ++ font-size: 1.3em; ++} ++ ++.versionmodified { ++ font-style: italic; ++} ++ ++.system-message { ++ background-color: #fda; ++ padding: 5px; ++ border: 3px solid red; ++} ++ ++.footnote:target { ++ background-color: #ffa; ++} ++ ++.line-block { ++ display: block; ++ margin-top: 1em; ++ margin-bottom: 1em; ++} ++ ++.line-block .line-block { ++ margin-top: 0; ++ margin-bottom: 0; ++ margin-left: 1.5em; ++} ++ ++.guilabel, .menuselection { ++ font-family: sans-serif; ++} ++ ++.accelerator { ++ text-decoration: underline; ++} ++ ++.classifier { ++ font-style: oblique; ++} ++ ++abbr, acronym { ++ border-bottom: dotted 1px; ++ cursor: help; ++} ++ ++/* -- code displays --------------------------------------------------------- */ ++ ++pre { ++ overflow: auto; ++ overflow-y: hidden; /* fixes display issues on Chrome browsers */ ++} ++ ++td.linenos pre { ++ padding: 5px 0px; ++ border: 0; ++ background-color: transparent; ++ color: #aaa; ++} ++ ++table.highlighttable { ++ margin-left: 0.5em; ++} ++ ++table.highlighttable td { ++ padding: 0 0.5em 0 0.5em; ++} ++ ++tt.descname { ++ background-color: transparent; ++ font-weight: bold; ++ font-size: 1.2em; ++} ++ ++tt.descclassname { ++ background-color: transparent; ++} ++ ++tt.xref, a tt { ++ background-color: transparent; ++ font-weight: bold; ++} ++ ++h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { ++ background-color: transparent; ++} ++ ++.viewcode-link { ++ float: right; ++} ++ ++.viewcode-back { ++ float: right; ++ font-family: sans-serif; ++} ++ ++div.viewcode-block:target { ++ margin: -1px -10px; ++ padding: 0 10px; ++} ++ ++/* -- math display ---------------------------------------------------------- */ ++ ++img.math { ++ vertical-align: middle; ++} ++ ++div.body div.math p { ++ text-align: center; ++} ++ ++span.eqno { ++ float: right; ++} ++ ++/* -- printout stylesheet --------------------------------------------------- */ ++ ++@media print { ++ div.document, ++ div.documentwrapper, ++ div.bodywrapper { ++ margin: 0 !important; ++ width: 100%; ++ } ++ ++ div.sphinxsidebar, ++ div.related, ++ div.footer, ++ #top-link { ++ display: none; ++ } ++} +\ No newline at end of file +diff -r 85f290e474e2 build/_static/comment-bright.png +Binary file build/_static/comment-bright.png has changed +diff -r 85f290e474e2 build/_static/comment-close.png +Binary file build/_static/comment-close.png has changed +diff -r 85f290e474e2 build/_static/comment.png +Binary file build/_static/comment.png has changed +diff -r 85f290e474e2 build/_static/doctools.js +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_static/doctools.js Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,238 @@ ++/* ++ * doctools.js ++ * ~~~~~~~~~~~ ++ * ++ * Sphinx JavaScript utilities for all documentation. ++ * ++ * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. ++ * :license: BSD, see LICENSE for details. ++ * ++ */ ++ ++/** ++ * select a different prefix for underscore ++ */ ++$u = _.noConflict(); ++ ++/** ++ * make the code below compatible with browsers without ++ * an installed firebug like debugger ++if (!window.console || !console.firebug) { ++ var names = ["log", "debug", "info", "warn", "error", "assert", "dir", ++ "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace", ++ "profile", "profileEnd"]; ++ window.console = {}; ++ for (var i = 0; i < names.length; ++i) ++ window.console[names[i]] = function() {}; ++} ++ */ ++ ++/** ++ * small helper function to urldecode strings ++ */ ++jQuery.urldecode = function(x) { ++ return decodeURIComponent(x).replace(/\+/g, ' '); ++}; ++ ++/** ++ * small helper function to urlencode strings ++ */ ++jQuery.urlencode = encodeURIComponent; ++ ++/** ++ * This function returns the parsed url parameters of the ++ * current request. Multiple values per key are supported, ++ * it will always return arrays of strings for the value parts. ++ */ ++jQuery.getQueryParameters = function(s) { ++ if (typeof s == 'undefined') ++ s = document.location.search; ++ var parts = s.substr(s.indexOf('?') + 1).split('&'); ++ var result = {}; ++ for (var i = 0; i < parts.length; i++) { ++ var tmp = parts[i].split('=', 2); ++ var key = jQuery.urldecode(tmp[0]); ++ var value = jQuery.urldecode(tmp[1]); ++ if (key in result) ++ result[key].push(value); ++ else ++ result[key] = [value]; ++ } ++ return result; ++}; ++ ++/** ++ * highlight a given string on a jquery object by wrapping it in ++ * span elements with the given class name. ++ */ ++jQuery.fn.highlightText = function(text, className) { ++ function highlight(node) { ++ if (node.nodeType == 3) { ++ var val = node.nodeValue; ++ var pos = val.toLowerCase().indexOf(text); ++ if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) { ++ var span = document.createElement("span"); ++ span.className = className; ++ span.appendChild(document.createTextNode(val.substr(pos, text.length))); ++ node.parentNode.insertBefore(span, node.parentNode.insertBefore( ++ document.createTextNode(val.substr(pos + text.length)), ++ node.nextSibling)); ++ node.nodeValue = val.substr(0, pos); ++ } ++ } ++ else if (!jQuery(node).is("button, select, textarea")) { ++ jQuery.each(node.childNodes, function() { ++ highlight(this); ++ }); ++ } ++ } ++ return this.each(function() { ++ highlight(this); ++ }); ++}; ++ ++/** ++ * Small JavaScript module for the documentation. ++ */ ++var Documentation = { ++ ++ init : function() { ++ this.fixFirefoxAnchorBug(); ++ this.highlightSearchWords(); ++ this.initIndexTable(); ++ }, ++ ++ /** ++ * i18n support ++ */ ++ TRANSLATIONS : {}, ++ PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, ++ LOCALE : 'unknown', ++ ++ // gettext and ngettext don't access this so that the functions ++ // can safely bound to a different name (_ = Documentation.gettext) ++ gettext : function(string) { ++ var translated = Documentation.TRANSLATIONS[string]; ++ if (typeof translated == 'undefined') ++ return string; ++ return (typeof translated == 'string') ? translated : translated[0]; ++ }, ++ ++ ngettext : function(singular, plural, n) { ++ var translated = Documentation.TRANSLATIONS[singular]; ++ if (typeof translated == 'undefined') ++ return (n == 1) ? singular : plural; ++ return translated[Documentation.PLURALEXPR(n)]; ++ }, ++ ++ addTranslations : function(catalog) { ++ for (var key in catalog.messages) ++ this.TRANSLATIONS[key] = catalog.messages[key]; ++ this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); ++ this.LOCALE = catalog.locale; ++ }, ++ ++ /** ++ * add context elements like header anchor links ++ */ ++ addContextElements : function() { ++ $('div[id] > :header:first').each(function() { ++ $('\u00B6'). ++ attr('href', '#' + this.id). ++ attr('title', _('Permalink to this headline')). ++ appendTo(this); ++ }); ++ $('dt[id]').each(function() { ++ $('\u00B6'). ++ attr('href', '#' + this.id). ++ attr('title', _('Permalink to this definition')). ++ appendTo(this); ++ }); ++ }, ++ ++ /** ++ * workaround a firefox stupidity ++ */ ++ fixFirefoxAnchorBug : function() { ++ if (document.location.hash && $.browser.mozilla) ++ window.setTimeout(function() { ++ document.location.href += ''; ++ }, 10); ++ }, ++ ++ /** ++ * highlight the search words provided in the url in the text ++ */ ++ highlightSearchWords : function() { ++ var params = $.getQueryParameters(); ++ var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; ++ if (terms.length) { ++ var body = $('div.body'); ++ if (!body.length) { ++ body = $('body'); ++ } ++ window.setTimeout(function() { ++ $.each(terms, function() { ++ body.highlightText(this.toLowerCase(), 'highlighted'); ++ }); ++ }, 10); ++ $('

      ' + _('Hide Search Matches') + '

      ') ++ .appendTo($('#searchbox')); ++ } ++ }, ++ ++ /** ++ * init the domain index toggle buttons ++ */ ++ initIndexTable : function() { ++ var togglers = $('img.toggler').click(function() { ++ var src = $(this).attr('src'); ++ var idnum = $(this).attr('id').substr(7); ++ $('tr.cg-' + idnum).toggle(); ++ if (src.substr(-9) == 'minus.png') ++ $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); ++ else ++ $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); ++ }).css('display', ''); ++ if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) { ++ togglers.click(); ++ } ++ }, ++ ++ /** ++ * helper function to hide the search marks again ++ */ ++ hideSearchWords : function() { ++ $('#searchbox .highlight-link').fadeOut(300); ++ $('span.highlighted').removeClass('highlighted'); ++ }, ++ ++ /** ++ * make the url absolute ++ */ ++ makeURL : function(relativeURL) { ++ return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; ++ }, ++ ++ /** ++ * get the current relative url ++ */ ++ getCurrentURL : function() { ++ var path = document.location.pathname; ++ var parts = path.split(/\//); ++ $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { ++ if (this == '..') ++ parts.pop(); ++ }); ++ var url = parts.join('/'); ++ return path.substring(url.lastIndexOf('/') + 1, path.length - 1); ++ } ++}; ++ ++// quick alias for translations ++_ = Documentation.gettext; ++ ++$(document).ready(function() { ++ Documentation.init(); ++}); +diff -r 85f290e474e2 build/_static/down-pressed.png +Binary file build/_static/down-pressed.png has changed +diff -r 85f290e474e2 build/_static/down.png +Binary file build/_static/down.png has changed +diff -r 85f290e474e2 build/_static/file.png +Binary file build/_static/file.png has changed +diff -r 85f290e474e2 build/_static/jquery.js +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_static/jquery.js Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,2 @@ ++/*! jQuery v1.8.3 jquery.com | jquery.org/license */ ++(function(e,t){function _(e){var t=M[e]={};return v.each(e.split(y),function(e,n){t[n]=!0}),t}function H(e,n,r){if(r===t&&e.nodeType===1){var i="data-"+n.replace(P,"-$1").toLowerCase();r=e.getAttribute(i);if(typeof r=="string"){try{r=r==="true"?!0:r==="false"?!1:r==="null"?null:+r+""===r?+r:D.test(r)?v.parseJSON(r):r}catch(s){}v.data(e,n,r)}else r=t}return r}function B(e){var t;for(t in e){if(t==="data"&&v.isEmptyObject(e[t]))continue;if(t!=="toJSON")return!1}return!0}function et(){return!1}function tt(){return!0}function ut(e){return!e||!e.parentNode||e.parentNode.nodeType===11}function at(e,t){do e=e[t];while(e&&e.nodeType!==1);return e}function ft(e,t,n){t=t||0;if(v.isFunction(t))return v.grep(e,function(e,r){var i=!!t.call(e,r,e);return i===n});if(t.nodeType)return v.grep(e,function(e,r){return e===t===n});if(typeof t=="string"){var r=v.grep(e,function(e){return e.nodeType===1});if(it.test(t))return v.filter(t,r,!n);t=v.filter(t,r)}return v.grep(e,function(e,r){return v.inArray(e,t)>=0===n})}function lt(e){var t=ct.split("|"),n=e.createDocumentFragment();if(n.createElement)while(t.length)n.createElement(t.pop());return n}function Lt(e,t){return e.getElementsByTagName(t)[0]||e.appendChild(e.ownerDocument.createElement(t))}function At(e,t){if(t.nodeType!==1||!v.hasData(e))return;var n,r,i,s=v._data(e),o=v._data(t,s),u=s.events;if(u){delete o.handle,o.events={};for(n in u)for(r=0,i=u[n].length;r").appendTo(i.body),n=t.css("display");t.remove();if(n==="none"||n===""){Pt=i.body.appendChild(Pt||v.extend(i.createElement("iframe"),{frameBorder:0,width:0,height:0}));if(!Ht||!Pt.createElement)Ht=(Pt.contentWindow||Pt.contentDocument).document,Ht.write(""),Ht.close();t=Ht.body.appendChild(Ht.createElement(e)),n=Dt(t,"display"),i.body.removeChild(Pt)}return Wt[e]=n,n}function fn(e,t,n,r){var i;if(v.isArray(t))v.each(t,function(t,i){n||sn.test(e)?r(e,i):fn(e+"["+(typeof i=="object"?t:"")+"]",i,n,r)});else if(!n&&v.type(t)==="object")for(i in t)fn(e+"["+i+"]",t[i],n,r);else r(e,t)}function Cn(e){return function(t,n){typeof t!="string"&&(n=t,t="*");var r,i,s,o=t.toLowerCase().split(y),u=0,a=o.length;if(v.isFunction(n))for(;u)[^>]*$|#([\w\-]*)$)/,E=/^<(\w+)\s*\/?>(?:<\/\1>|)$/,S=/^[\],:{}\s]*$/,x=/(?:^|:|,)(?:\s*\[)+/g,T=/\\(?:["\\\/bfnrt]|u[\da-fA-F]{4})/g,N=/"[^"\\\r\n]*"|true|false|null|-?(?:\d\d*\.|)\d+(?:[eE][\-+]?\d+|)/g,C=/^-ms-/,k=/-([\da-z])/gi,L=function(e,t){return(t+"").toUpperCase()},A=function(){i.addEventListener?(i.removeEventListener("DOMContentLoaded",A,!1),v.ready()):i.readyState==="complete"&&(i.detachEvent("onreadystatechange",A),v.ready())},O={};v.fn=v.prototype={constructor:v,init:function(e,n,r){var s,o,u,a;if(!e)return this;if(e.nodeType)return this.context=this[0]=e,this.length=1,this;if(typeof e=="string"){e.charAt(0)==="<"&&e.charAt(e.length-1)===">"&&e.length>=3?s=[null,e,null]:s=w.exec(e);if(s&&(s[1]||!n)){if(s[1])return n=n instanceof v?n[0]:n,a=n&&n.nodeType?n.ownerDocument||n:i,e=v.parseHTML(s[1],a,!0),E.test(s[1])&&v.isPlainObject(n)&&this.attr.call(e,n,!0),v.merge(this,e);o=i.getElementById(s[2]);if(o&&o.parentNode){if(o.id!==s[2])return r.find(e);this.length=1,this[0]=o}return this.context=i,this.selector=e,this}return!n||n.jquery?(n||r).find(e):this.constructor(n).find(e)}return v.isFunction(e)?r.ready(e):(e.selector!==t&&(this.selector=e.selector,this.context=e.context),v.makeArray(e,this))},selector:"",jquery:"1.8.3",length:0,size:function(){return this.length},toArray:function(){return l.call(this)},get:function(e){return e==null?this.toArray():e<0?this[this.length+e]:this[e]},pushStack:function(e,t,n){var r=v.merge(this.constructor(),e);return r.prevObject=this,r.context=this.context,t==="find"?r.selector=this.selector+(this.selector?" ":"")+n:t&&(r.selector=this.selector+"."+t+"("+n+")"),r},each:function(e,t){return v.each(this,e,t)},ready:function(e){return v.ready.promise().done(e),this},eq:function(e){return e=+e,e===-1?this.slice(e):this.slice(e,e+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(l.apply(this,arguments),"slice",l.call(arguments).join(","))},map:function(e){return this.pushStack(v.map(this,function(t,n){return e.call(t,n,t)}))},end:function(){return this.prevObject||this.constructor(null)},push:f,sort:[].sort,splice:[].splice},v.fn.init.prototype=v.fn,v.extend=v.fn.extend=function(){var e,n,r,i,s,o,u=arguments[0]||{},a=1,f=arguments.length,l=!1;typeof u=="boolean"&&(l=u,u=arguments[1]||{},a=2),typeof u!="object"&&!v.isFunction(u)&&(u={}),f===a&&(u=this,--a);for(;a0)return;r.resolveWith(i,[v]),v.fn.trigger&&v(i).trigger("ready").off("ready")},isFunction:function(e){return v.type(e)==="function"},isArray:Array.isArray||function(e){return v.type(e)==="array"},isWindow:function(e){return e!=null&&e==e.window},isNumeric:function(e){return!isNaN(parseFloat(e))&&isFinite(e)},type:function(e){return e==null?String(e):O[h.call(e)]||"object"},isPlainObject:function(e){if(!e||v.type(e)!=="object"||e.nodeType||v.isWindow(e))return!1;try{if(e.constructor&&!p.call(e,"constructor")&&!p.call(e.constructor.prototype,"isPrototypeOf"))return!1}catch(n){return!1}var r;for(r in e);return r===t||p.call(e,r)},isEmptyObject:function(e){var t;for(t in e)return!1;return!0},error:function(e){throw new Error(e)},parseHTML:function(e,t,n){var r;return!e||typeof e!="string"?null:(typeof t=="boolean"&&(n=t,t=0),t=t||i,(r=E.exec(e))?[t.createElement(r[1])]:(r=v.buildFragment([e],t,n?null:[]),v.merge([],(r.cacheable?v.clone(r.fragment):r.fragment).childNodes)))},parseJSON:function(t){if(!t||typeof t!="string")return null;t=v.trim(t);if(e.JSON&&e.JSON.parse)return e.JSON.parse(t);if(S.test(t.replace(T,"@").replace(N,"]").replace(x,"")))return(new Function("return "+t))();v.error("Invalid JSON: "+t)},parseXML:function(n){var r,i;if(!n||typeof n!="string")return null;try{e.DOMParser?(i=new DOMParser,r=i.parseFromString(n,"text/xml")):(r=new ActiveXObject("Microsoft.XMLDOM"),r.async="false",r.loadXML(n))}catch(s){r=t}return(!r||!r.documentElement||r.getElementsByTagName("parsererror").length)&&v.error("Invalid XML: "+n),r},noop:function(){},globalEval:function(t){t&&g.test(t)&&(e.execScript||function(t){e.eval.call(e,t)})(t)},camelCase:function(e){return e.replace(C,"ms-").replace(k,L)},nodeName:function(e,t){return e.nodeName&&e.nodeName.toLowerCase()===t.toLowerCase()},each:function(e,n,r){var i,s=0,o=e.length,u=o===t||v.isFunction(e);if(r){if(u){for(i in e)if(n.apply(e[i],r)===!1)break}else for(;s0&&e[0]&&e[a-1]||a===0||v.isArray(e));if(f)for(;u-1)a.splice(n,1),i&&(n<=o&&o--,n<=u&&u--)}),this},has:function(e){return v.inArray(e,a)>-1},empty:function(){return a=[],this},disable:function(){return a=f=n=t,this},disabled:function(){return!a},lock:function(){return f=t,n||c.disable(),this},locked:function(){return!f},fireWith:function(e,t){return t=t||[],t=[e,t.slice?t.slice():t],a&&(!r||f)&&(i?f.push(t):l(t)),this},fire:function(){return c.fireWith(this,arguments),this},fired:function(){return!!r}};return c},v.extend({Deferred:function(e){var t=[["resolve","done",v.Callbacks("once memory"),"resolved"],["reject","fail",v.Callbacks("once memory"),"rejected"],["notify","progress",v.Callbacks("memory")]],n="pending",r={state:function(){return n},always:function(){return i.done(arguments).fail(arguments),this},then:function(){var e=arguments;return v.Deferred(function(n){v.each(t,function(t,r){var s=r[0],o=e[t];i[r[1]](v.isFunction(o)?function(){var e=o.apply(this,arguments);e&&v.isFunction(e.promise)?e.promise().done(n.resolve).fail(n.reject).progress(n.notify):n[s+"With"](this===i?n:this,[e])}:n[s])}),e=null}).promise()},promise:function(e){return e!=null?v.extend(e,r):r}},i={};return r.pipe=r.then,v.each(t,function(e,s){var o=s[2],u=s[3];r[s[1]]=o.add,u&&o.add(function(){n=u},t[e^1][2].disable,t[2][2].lock),i[s[0]]=o.fire,i[s[0]+"With"]=o.fireWith}),r.promise(i),e&&e.call(i,i),i},when:function(e){var t=0,n=l.call(arguments),r=n.length,i=r!==1||e&&v.isFunction(e.promise)?r:0,s=i===1?e:v.Deferred(),o=function(e,t,n){return function(r){t[e]=this,n[e]=arguments.length>1?l.call(arguments):r,n===u?s.notifyWith(t,n):--i||s.resolveWith(t,n)}},u,a,f;if(r>1){u=new Array(r),a=new Array(r),f=new Array(r);for(;t
      a",n=p.getElementsByTagName("*"),r=p.getElementsByTagName("a")[0];if(!n||!r||!n.length)return{};s=i.createElement("select"),o=s.appendChild(i.createElement("option")),u=p.getElementsByTagName("input")[0],r.style.cssText="top:1px;float:left;opacity:.5",t={leadingWhitespace:p.firstChild.nodeType===3,tbody:!p.getElementsByTagName("tbody").length,htmlSerialize:!!p.getElementsByTagName("link").length,style:/top/.test(r.getAttribute("style")),hrefNormalized:r.getAttribute("href")==="/a",opacity:/^0.5/.test(r.style.opacity),cssFloat:!!r.style.cssFloat,checkOn:u.value==="on",optSelected:o.selected,getSetAttribute:p.className!=="t",enctype:!!i.createElement("form").enctype,html5Clone:i.createElement("nav").cloneNode(!0).outerHTML!=="<:nav>",boxModel:i.compatMode==="CSS1Compat",submitBubbles:!0,changeBubbles:!0,focusinBubbles:!1,deleteExpando:!0,noCloneEvent:!0,inlineBlockNeedsLayout:!1,shrinkWrapBlocks:!1,reliableMarginRight:!0,boxSizingReliable:!0,pixelPosition:!1},u.checked=!0,t.noCloneChecked=u.cloneNode(!0).checked,s.disabled=!0,t.optDisabled=!o.disabled;try{delete p.test}catch(d){t.deleteExpando=!1}!p.addEventListener&&p.attachEvent&&p.fireEvent&&(p.attachEvent("onclick",h=function(){t.noCloneEvent=!1}),p.cloneNode(!0).fireEvent("onclick"),p.detachEvent("onclick",h)),u=i.createElement("input"),u.value="t",u.setAttribute("type","radio"),t.radioValue=u.value==="t",u.setAttribute("checked","checked"),u.setAttribute("name","t"),p.appendChild(u),a=i.createDocumentFragment(),a.appendChild(p.lastChild),t.checkClone=a.cloneNode(!0).cloneNode(!0).lastChild.checked,t.appendChecked=u.checked,a.removeChild(u),a.appendChild(p);if(p.attachEvent)for(l in{submit:!0,change:!0,focusin:!0})f="on"+l,c=f in p,c||(p.setAttribute(f,"return;"),c=typeof p[f]=="function"),t[l+"Bubbles"]=c;return v(function(){var n,r,s,o,u="padding:0;margin:0;border:0;display:block;overflow:hidden;",a=i.getElementsByTagName("body")[0];if(!a)return;n=i.createElement("div"),n.style.cssText="visibility:hidden;border:0;width:0;height:0;position:static;top:0;margin-top:1px",a.insertBefore(n,a.firstChild),r=i.createElement("div"),n.appendChild(r),r.innerHTML="
      t
      ",s=r.getElementsByTagName("td"),s[0].style.cssText="padding:0;margin:0;border:0;display:none",c=s[0].offsetHeight===0,s[0].style.display="",s[1].style.display="none",t.reliableHiddenOffsets=c&&s[0].offsetHeight===0,r.innerHTML="",r.style.cssText="box-sizing:border-box;-moz-box-sizing:border-box;-webkit-box-sizing:border-box;padding:1px;border:1px;display:block;width:4px;margin-top:1%;position:absolute;top:1%;",t.boxSizing=r.offsetWidth===4,t.doesNotIncludeMarginInBodyOffset=a.offsetTop!==1,e.getComputedStyle&&(t.pixelPosition=(e.getComputedStyle(r,null)||{}).top!=="1%",t.boxSizingReliable=(e.getComputedStyle(r,null)||{width:"4px"}).width==="4px",o=i.createElement("div"),o.style.cssText=r.style.cssText=u,o.style.marginRight=o.style.width="0",r.style.width="1px",r.appendChild(o),t.reliableMarginRight=!parseFloat((e.getComputedStyle(o,null)||{}).marginRight)),typeof r.style.zoom!="undefined"&&(r.innerHTML="",r.style.cssText=u+"width:1px;padding:1px;display:inline;zoom:1",t.inlineBlockNeedsLayout=r.offsetWidth===3,r.style.display="block",r.style.overflow="visible",r.innerHTML="
      ",r.firstChild.style.width="5px",t.shrinkWrapBlocks=r.offsetWidth!==3,n.style.zoom=1),a.removeChild(n),n=r=s=o=null}),a.removeChild(p),n=r=s=o=u=a=p=null,t}();var D=/(?:\{[\s\S]*\}|\[[\s\S]*\])$/,P=/([A-Z])/g;v.extend({cache:{},deletedIds:[],uuid:0,expando:"jQuery"+(v.fn.jquery+Math.random()).replace(/\D/g,""),noData:{embed:!0,object:"clsid:D27CDB6E-AE6D-11cf-96B8-444553540000",applet:!0},hasData:function(e){return e=e.nodeType?v.cache[e[v.expando]]:e[v.expando],!!e&&!B(e)},data:function(e,n,r,i){if(!v.acceptData(e))return;var s,o,u=v.expando,a=typeof n=="string",f=e.nodeType,l=f?v.cache:e,c=f?e[u]:e[u]&&u;if((!c||!l[c]||!i&&!l[c].data)&&a&&r===t)return;c||(f?e[u]=c=v.deletedIds.pop()||v.guid++:c=u),l[c]||(l[c]={},f||(l[c].toJSON=v.noop));if(typeof n=="object"||typeof n=="function")i?l[c]=v.extend(l[c],n):l[c].data=v.extend(l[c].data,n);return s=l[c],i||(s.data||(s.data={}),s=s.data),r!==t&&(s[v.camelCase(n)]=r),a?(o=s[n],o==null&&(o=s[v.camelCase(n)])):o=s,o},removeData:function(e,t,n){if(!v.acceptData(e))return;var r,i,s,o=e.nodeType,u=o?v.cache:e,a=o?e[v.expando]:v.expando;if(!u[a])return;if(t){r=n?u[a]:u[a].data;if(r){v.isArray(t)||(t in r?t=[t]:(t=v.camelCase(t),t in r?t=[t]:t=t.split(" ")));for(i=0,s=t.length;i1,null,!1))},removeData:function(e){return this.each(function(){v.removeData(this,e)})}}),v.extend({queue:function(e,t,n){var r;if(e)return t=(t||"fx")+"queue",r=v._data(e,t),n&&(!r||v.isArray(n)?r=v._data(e,t,v.makeArray(n)):r.push(n)),r||[]},dequeue:function(e,t){t=t||"fx";var n=v.queue(e,t),r=n.length,i=n.shift(),s=v._queueHooks(e,t),o=function(){v.dequeue(e,t)};i==="inprogress"&&(i=n.shift(),r--),i&&(t==="fx"&&n.unshift("inprogress"),delete s.stop,i.call(e,o,s)),!r&&s&&s.empty.fire()},_queueHooks:function(e,t){var n=t+"queueHooks";return v._data(e,n)||v._data(e,n,{empty:v.Callbacks("once memory").add(function(){v.removeData(e,t+"queue",!0),v.removeData(e,n,!0)})})}}),v.fn.extend({queue:function(e,n){var r=2;return typeof e!="string"&&(n=e,e="fx",r--),arguments.length1)},removeAttr:function(e){return this.each(function(){v.removeAttr(this,e)})},prop:function(e,t){return v.access(this,v.prop,e,t,arguments.length>1)},removeProp:function(e){return e=v.propFix[e]||e,this.each(function(){try{this[e]=t,delete this[e]}catch(n){}})},addClass:function(e){var t,n,r,i,s,o,u;if(v.isFunction(e))return this.each(function(t){v(this).addClass(e.call(this,t,this.className))});if(e&&typeof e=="string"){t=e.split(y);for(n=0,r=this.length;n=0)r=r.replace(" "+n[s]+" "," ");i.className=e?v.trim(r):""}}}return this},toggleClass:function(e,t){var n=typeof e,r=typeof t=="boolean";return v.isFunction(e)?this.each(function(n){v(this).toggleClass(e.call(this,n,this.className,t),t)}):this.each(function(){if(n==="string"){var i,s=0,o=v(this),u=t,a=e.split(y);while(i=a[s++])u=r?u:!o.hasClass(i),o[u?"addClass":"removeClass"](i)}else if(n==="undefined"||n==="boolean")this.className&&v._data(this,"__className__",this.className),this.className=this.className||e===!1?"":v._data(this,"__className__")||""})},hasClass:function(e){var t=" "+e+" ",n=0,r=this.length;for(;n=0)return!0;return!1},val:function(e){var n,r,i,s=this[0];if(!arguments.length){if(s)return n=v.valHooks[s.type]||v.valHooks[s.nodeName.toLowerCase()],n&&"get"in n&&(r=n.get(s,"value"))!==t?r:(r=s.value,typeof r=="string"?r.replace(R,""):r==null?"":r);return}return i=v.isFunction(e),this.each(function(r){var s,o=v(this);if(this.nodeType!==1)return;i?s=e.call(this,r,o.val()):s=e,s==null?s="":typeof s=="number"?s+="":v.isArray(s)&&(s=v.map(s,function(e){return e==null?"":e+""})),n=v.valHooks[this.type]||v.valHooks[this.nodeName.toLowerCase()];if(!n||!("set"in n)||n.set(this,s,"value")===t)this.value=s})}}),v.extend({valHooks:{option:{get:function(e){var t=e.attributes.value;return!t||t.specified?e.value:e.text}},select:{get:function(e){var t,n,r=e.options,i=e.selectedIndex,s=e.type==="select-one"||i<0,o=s?null:[],u=s?i+1:r.length,a=i<0?u:s?i:0;for(;a=0}),n.length||(e.selectedIndex=-1),n}}},attrFn:{},attr:function(e,n,r,i){var s,o,u,a=e.nodeType;if(!e||a===3||a===8||a===2)return;if(i&&v.isFunction(v.fn[n]))return v(e)[n](r);if(typeof e.getAttribute=="undefined")return v.prop(e,n,r);u=a!==1||!v.isXMLDoc(e),u&&(n=n.toLowerCase(),o=v.attrHooks[n]||(X.test(n)?F:j));if(r!==t){if(r===null){v.removeAttr(e,n);return}return o&&"set"in o&&u&&(s=o.set(e,r,n))!==t?s:(e.setAttribute(n,r+""),r)}return o&&"get"in o&&u&&(s=o.get(e,n))!==null?s:(s=e.getAttribute(n),s===null?t:s)},removeAttr:function(e,t){var n,r,i,s,o=0;if(t&&e.nodeType===1){r=t.split(y);for(;o=0}})});var $=/^(?:textarea|input|select)$/i,J=/^([^\.]*|)(?:\.(.+)|)$/,K=/(?:^|\s)hover(\.\S+|)\b/,Q=/^key/,G=/^(?:mouse|contextmenu)|click/,Y=/^(?:focusinfocus|focusoutblur)$/,Z=function(e){return v.event.special.hover?e:e.replace(K,"mouseenter$1 mouseleave$1")};v.event={add:function(e,n,r,i,s){var o,u,a,f,l,c,h,p,d,m,g;if(e.nodeType===3||e.nodeType===8||!n||!r||!(o=v._data(e)))return;r.handler&&(d=r,r=d.handler,s=d.selector),r.guid||(r.guid=v.guid++),a=o.events,a||(o.events=a={}),u=o.handle,u||(o.handle=u=function(e){return typeof v=="undefined"||!!e&&v.event.triggered===e.type?t:v.event.dispatch.apply(u.elem,arguments)},u.elem=e),n=v.trim(Z(n)).split(" ");for(f=0;f=0&&(y=y.slice(0,-1),a=!0),y.indexOf(".")>=0&&(b=y.split("."),y=b.shift(),b.sort());if((!s||v.event.customEvent[y])&&!v.event.global[y])return;n=typeof n=="object"?n[v.expando]?n:new v.Event(y,n):new v.Event(y),n.type=y,n.isTrigger=!0,n.exclusive=a,n.namespace=b.join("."),n.namespace_re=n.namespace?new RegExp("(^|\\.)"+b.join("\\.(?:.*\\.|)")+"(\\.|$)"):null,h=y.indexOf(":")<0?"on"+y:"";if(!s){u=v.cache;for(f in u)u[f].events&&u[f].events[y]&&v.event.trigger(n,r,u[f].handle.elem,!0);return}n.result=t,n.target||(n.target=s),r=r!=null?v.makeArray(r):[],r.unshift(n),p=v.event.special[y]||{};if(p.trigger&&p.trigger.apply(s,r)===!1)return;m=[[s,p.bindType||y]];if(!o&&!p.noBubble&&!v.isWindow(s)){g=p.delegateType||y,l=Y.test(g+y)?s:s.parentNode;for(c=s;l;l=l.parentNode)m.push([l,g]),c=l;c===(s.ownerDocument||i)&&m.push([c.defaultView||c.parentWindow||e,g])}for(f=0;f=0:v.find(h,this,null,[s]).length),u[h]&&f.push(c);f.length&&w.push({elem:s,matches:f})}d.length>m&&w.push({elem:this,matches:d.slice(m)});for(r=0;r0?this.on(t,null,e,n):this.trigger(t)},Q.test(t)&&(v.event.fixHooks[t]=v.event.keyHooks),G.test(t)&&(v.event.fixHooks[t]=v.event.mouseHooks)}),function(e,t){function nt(e,t,n,r){n=n||[],t=t||g;var i,s,a,f,l=t.nodeType;if(!e||typeof e!="string")return n;if(l!==1&&l!==9)return[];a=o(t);if(!a&&!r)if(i=R.exec(e))if(f=i[1]){if(l===9){s=t.getElementById(f);if(!s||!s.parentNode)return n;if(s.id===f)return n.push(s),n}else if(t.ownerDocument&&(s=t.ownerDocument.getElementById(f))&&u(t,s)&&s.id===f)return n.push(s),n}else{if(i[2])return S.apply(n,x.call(t.getElementsByTagName(e),0)),n;if((f=i[3])&&Z&&t.getElementsByClassName)return S.apply(n,x.call(t.getElementsByClassName(f),0)),n}return vt(e.replace(j,"$1"),t,n,r,a)}function rt(e){return function(t){var n=t.nodeName.toLowerCase();return n==="input"&&t.type===e}}function it(e){return function(t){var n=t.nodeName.toLowerCase();return(n==="input"||n==="button")&&t.type===e}}function st(e){return N(function(t){return t=+t,N(function(n,r){var i,s=e([],n.length,t),o=s.length;while(o--)n[i=s[o]]&&(n[i]=!(r[i]=n[i]))})})}function ot(e,t,n){if(e===t)return n;var r=e.nextSibling;while(r){if(r===t)return-1;r=r.nextSibling}return 1}function ut(e,t){var n,r,s,o,u,a,f,l=L[d][e+" "];if(l)return t?0:l.slice(0);u=e,a=[],f=i.preFilter;while(u){if(!n||(r=F.exec(u)))r&&(u=u.slice(r[0].length)||u),a.push(s=[]);n=!1;if(r=I.exec(u))s.push(n=new m(r.shift())),u=u.slice(n.length),n.type=r[0].replace(j," ");for(o in i.filter)(r=J[o].exec(u))&&(!f[o]||(r=f[o](r)))&&(s.push(n=new m(r.shift())),u=u.slice(n.length),n.type=o,n.matches=r);if(!n)break}return t?u.length:u?nt.error(e):L(e,a).slice(0)}function at(e,t,r){var i=t.dir,s=r&&t.dir==="parentNode",o=w++;return t.first?function(t,n,r){while(t=t[i])if(s||t.nodeType===1)return e(t,n,r)}:function(t,r,u){if(!u){var a,f=b+" "+o+" ",l=f+n;while(t=t[i])if(s||t.nodeType===1){if((a=t[d])===l)return t.sizset;if(typeof a=="string"&&a.indexOf(f)===0){if(t.sizset)return t}else{t[d]=l;if(e(t,r,u))return t.sizset=!0,t;t.sizset=!1}}}else while(t=t[i])if(s||t.nodeType===1)if(e(t,r,u))return t}}function ft(e){return e.length>1?function(t,n,r){var i=e.length;while(i--)if(!e[i](t,n,r))return!1;return!0}:e[0]}function lt(e,t,n,r,i){var s,o=[],u=0,a=e.length,f=t!=null;for(;u-1&&(s[f]=!(o[f]=c))}}else g=lt(g===o?g.splice(d,g.length):g),i?i(null,o,g,a):S.apply(o,g)})}function ht(e){var t,n,r,s=e.length,o=i.relative[e[0].type],u=o||i.relative[" "],a=o?1:0,f=at(function(e){return e===t},u,!0),l=at(function(e){return T.call(t,e)>-1},u,!0),h=[function(e,n,r){return!o&&(r||n!==c)||((t=n).nodeType?f(e,n,r):l(e,n,r))}];for(;a1&&ft(h),a>1&&e.slice(0,a-1).join("").replace(j,"$1"),n,a0,s=e.length>0,o=function(u,a,f,l,h){var p,d,v,m=[],y=0,w="0",x=u&&[],T=h!=null,N=c,C=u||s&&i.find.TAG("*",h&&a.parentNode||a),k=b+=N==null?1:Math.E;T&&(c=a!==g&&a,n=o.el);for(;(p=C[w])!=null;w++){if(s&&p){for(d=0;v=e[d];d++)if(v(p,a,f)){l.push(p);break}T&&(b=k,n=++o.el)}r&&((p=!v&&p)&&y--,u&&x.push(p))}y+=w;if(r&&w!==y){for(d=0;v=t[d];d++)v(x,m,a,f);if(u){if(y>0)while(w--)!x[w]&&!m[w]&&(m[w]=E.call(l));m=lt(m)}S.apply(l,m),T&&!u&&m.length>0&&y+t.length>1&&nt.uniqueSort(l)}return T&&(b=k,c=N),x};return o.el=0,r?N(o):o}function dt(e,t,n){var r=0,i=t.length;for(;r2&&(f=u[0]).type==="ID"&&t.nodeType===9&&!s&&i.relative[u[1].type]){t=i.find.ID(f.matches[0].replace($,""),t,s)[0];if(!t)return n;e=e.slice(u.shift().length)}for(o=J.POS.test(e)?-1:u.length-1;o>=0;o--){f=u[o];if(i.relative[l=f.type])break;if(c=i.find[l])if(r=c(f.matches[0].replace($,""),z.test(u[0].type)&&t.parentNode||t,s)){u.splice(o,1),e=r.length&&u.join("");if(!e)return S.apply(n,x.call(r,0)),n;break}}}return a(e,h)(r,t,s,n,z.test(e)),n}function mt(){}var n,r,i,s,o,u,a,f,l,c,h=!0,p="undefined",d=("sizcache"+Math.random()).replace(".",""),m=String,g=e.document,y=g.documentElement,b=0,w=0,E=[].pop,S=[].push,x=[].slice,T=[].indexOf||function(e){var t=0,n=this.length;for(;ti.cacheLength&&delete e[t.shift()],e[n+" "]=r},e)},k=C(),L=C(),A=C(),O="[\\x20\\t\\r\\n\\f]",M="(?:\\\\.|[-\\w]|[^\\x00-\\xa0])+",_=M.replace("w","w#"),D="([*^$|!~]?=)",P="\\["+O+"*("+M+")"+O+"*(?:"+D+O+"*(?:(['\"])((?:\\\\.|[^\\\\])*?)\\3|("+_+")|)|)"+O+"*\\]",H=":("+M+")(?:\\((?:(['\"])((?:\\\\.|[^\\\\])*?)\\2|([^()[\\]]*|(?:(?:"+P+")|[^:]|\\\\.)*|.*))\\)|)",B=":(even|odd|eq|gt|lt|nth|first|last)(?:\\("+O+"*((?:-\\d)?\\d*)"+O+"*\\)|)(?=[^-]|$)",j=new RegExp("^"+O+"+|((?:^|[^\\\\])(?:\\\\.)*)"+O+"+$","g"),F=new RegExp("^"+O+"*,"+O+"*"),I=new RegExp("^"+O+"*([\\x20\\t\\r\\n\\f>+~])"+O+"*"),q=new RegExp(H),R=/^(?:#([\w\-]+)|(\w+)|\.([\w\-]+))$/,U=/^:not/,z=/[\x20\t\r\n\f]*[+~]/,W=/:not\($/,X=/h\d/i,V=/input|select|textarea|button/i,$=/\\(?!\\)/g,J={ID:new RegExp("^#("+M+")"),CLASS:new RegExp("^\\.("+M+")"),NAME:new RegExp("^\\[name=['\"]?("+M+")['\"]?\\]"),TAG:new RegExp("^("+M.replace("w","w*")+")"),ATTR:new RegExp("^"+P),PSEUDO:new RegExp("^"+H),POS:new RegExp(B,"i"),CHILD:new RegExp("^:(only|nth|first|last)-child(?:\\("+O+"*(even|odd|(([+-]|)(\\d*)n|)"+O+"*(?:([+-]|)"+O+"*(\\d+)|))"+O+"*\\)|)","i"),needsContext:new RegExp("^"+O+"*[>+~]|"+B,"i")},K=function(e){var t=g.createElement("div");try{return e(t)}catch(n){return!1}finally{t=null}},Q=K(function(e){return e.appendChild(g.createComment("")),!e.getElementsByTagName("*").length}),G=K(function(e){return e.innerHTML="",e.firstChild&&typeof e.firstChild.getAttribute!==p&&e.firstChild.getAttribute("href")==="#"}),Y=K(function(e){e.innerHTML="";var t=typeof e.lastChild.getAttribute("multiple");return t!=="boolean"&&t!=="string"}),Z=K(function(e){return e.innerHTML="",!e.getElementsByClassName||!e.getElementsByClassName("e").length?!1:(e.lastChild.className="e",e.getElementsByClassName("e").length===2)}),et=K(function(e){e.id=d+0,e.innerHTML="
      ",y.insertBefore(e,y.firstChild);var t=g.getElementsByName&&g.getElementsByName(d).length===2+g.getElementsByName(d+0).length;return r=!g.getElementById(d),y.removeChild(e),t});try{x.call(y.childNodes,0)[0].nodeType}catch(tt){x=function(e){var t,n=[];for(;t=this[e];e++)n.push(t);return n}}nt.matches=function(e,t){return nt(e,null,null,t)},nt.matchesSelector=function(e,t){return nt(t,null,null,[e]).length>0},s=nt.getText=function(e){var t,n="",r=0,i=e.nodeType;if(i){if(i===1||i===9||i===11){if(typeof e.textContent=="string")return e.textContent;for(e=e.firstChild;e;e=e.nextSibling)n+=s(e)}else if(i===3||i===4)return e.nodeValue}else for(;t=e[r];r++)n+=s(t);return n},o=nt.isXML=function(e){var t=e&&(e.ownerDocument||e).documentElement;return t?t.nodeName!=="HTML":!1},u=nt.contains=y.contains?function(e,t){var n=e.nodeType===9?e.documentElement:e,r=t&&t.parentNode;return e===r||!!(r&&r.nodeType===1&&n.contains&&n.contains(r))}:y.compareDocumentPosition?function(e,t){return t&&!!(e.compareDocumentPosition(t)&16)}:function(e,t){while(t=t.parentNode)if(t===e)return!0;return!1},nt.attr=function(e,t){var n,r=o(e);return r||(t=t.toLowerCase()),(n=i.attrHandle[t])?n(e):r||Y?e.getAttribute(t):(n=e.getAttributeNode(t),n?typeof e[t]=="boolean"?e[t]?t:null:n.specified?n.value:null:null)},i=nt.selectors={cacheLength:50,createPseudo:N,match:J,attrHandle:G?{}:{href:function(e){return e.getAttribute("href",2)},type:function(e){return e.getAttribute("type")}},find:{ID:r?function(e,t,n){if(typeof t.getElementById!==p&&!n){var r=t.getElementById(e);return r&&r.parentNode?[r]:[]}}:function(e,n,r){if(typeof n.getElementById!==p&&!r){var i=n.getElementById(e);return i?i.id===e||typeof i.getAttributeNode!==p&&i.getAttributeNode("id").value===e?[i]:t:[]}},TAG:Q?function(e,t){if(typeof t.getElementsByTagName!==p)return t.getElementsByTagName(e)}:function(e,t){var n=t.getElementsByTagName(e);if(e==="*"){var r,i=[],s=0;for(;r=n[s];s++)r.nodeType===1&&i.push(r);return i}return n},NAME:et&&function(e,t){if(typeof t.getElementsByName!==p)return t.getElementsByName(name)},CLASS:Z&&function(e,t,n){if(typeof t.getElementsByClassName!==p&&!n)return t.getElementsByClassName(e)}},relative:{">":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(e){return e[1]=e[1].replace($,""),e[3]=(e[4]||e[5]||"").replace($,""),e[2]==="~="&&(e[3]=" "+e[3]+" "),e.slice(0,4)},CHILD:function(e){return e[1]=e[1].toLowerCase(),e[1]==="nth"?(e[2]||nt.error(e[0]),e[3]=+(e[3]?e[4]+(e[5]||1):2*(e[2]==="even"||e[2]==="odd")),e[4]=+(e[6]+e[7]||e[2]==="odd")):e[2]&&nt.error(e[0]),e},PSEUDO:function(e){var t,n;if(J.CHILD.test(e[0]))return null;if(e[3])e[2]=e[3];else if(t=e[4])q.test(t)&&(n=ut(t,!0))&&(n=t.indexOf(")",t.length-n)-t.length)&&(t=t.slice(0,n),e[0]=e[0].slice(0,n)),e[2]=t;return e.slice(0,3)}},filter:{ID:r?function(e){return e=e.replace($,""),function(t){return t.getAttribute("id")===e}}:function(e){return e=e.replace($,""),function(t){var n=typeof t.getAttributeNode!==p&&t.getAttributeNode("id");return n&&n.value===e}},TAG:function(e){return e==="*"?function(){return!0}:(e=e.replace($,"").toLowerCase(),function(t){return t.nodeName&&t.nodeName.toLowerCase()===e})},CLASS:function(e){var t=k[d][e+" "];return t||(t=new RegExp("(^|"+O+")"+e+"("+O+"|$)"))&&k(e,function(e){return t.test(e.className||typeof e.getAttribute!==p&&e.getAttribute("class")||"")})},ATTR:function(e,t,n){return function(r,i){var s=nt.attr(r,e);return s==null?t==="!=":t?(s+="",t==="="?s===n:t==="!="?s!==n:t==="^="?n&&s.indexOf(n)===0:t==="*="?n&&s.indexOf(n)>-1:t==="$="?n&&s.substr(s.length-n.length)===n:t==="~="?(" "+s+" ").indexOf(n)>-1:t==="|="?s===n||s.substr(0,n.length+1)===n+"-":!1):!0}},CHILD:function(e,t,n,r){return e==="nth"?function(e){var t,i,s=e.parentNode;if(n===1&&r===0)return!0;if(s){i=0;for(t=s.firstChild;t;t=t.nextSibling)if(t.nodeType===1){i++;if(e===t)break}}return i-=r,i===n||i%n===0&&i/n>=0}:function(t){var n=t;switch(e){case"only":case"first":while(n=n.previousSibling)if(n.nodeType===1)return!1;if(e==="first")return!0;n=t;case"last":while(n=n.nextSibling)if(n.nodeType===1)return!1;return!0}}},PSEUDO:function(e,t){var n,r=i.pseudos[e]||i.setFilters[e.toLowerCase()]||nt.error("unsupported pseudo: "+e);return r[d]?r(t):r.length>1?(n=[e,e,"",t],i.setFilters.hasOwnProperty(e.toLowerCase())?N(function(e,n){var i,s=r(e,t),o=s.length;while(o--)i=T.call(e,s[o]),e[i]=!(n[i]=s[o])}):function(e){return r(e,0,n)}):r}},pseudos:{not:N(function(e){var t=[],n=[],r=a(e.replace(j,"$1"));return r[d]?N(function(e,t,n,i){var s,o=r(e,null,i,[]),u=e.length;while(u--)if(s=o[u])e[u]=!(t[u]=s)}):function(e,i,s){return t[0]=e,r(t,null,s,n),!n.pop()}}),has:N(function(e){return function(t){return nt(e,t).length>0}}),contains:N(function(e){return function(t){return(t.textContent||t.innerText||s(t)).indexOf(e)>-1}}),enabled:function(e){return e.disabled===!1},disabled:function(e){return e.disabled===!0},checked:function(e){var t=e.nodeName.toLowerCase();return t==="input"&&!!e.checked||t==="option"&&!!e.selected},selected:function(e){return e.parentNode&&e.parentNode.selectedIndex,e.selected===!0},parent:function(e){return!i.pseudos.empty(e)},empty:function(e){var t;e=e.firstChild;while(e){if(e.nodeName>"@"||(t=e.nodeType)===3||t===4)return!1;e=e.nextSibling}return!0},header:function(e){return X.test(e.nodeName)},text:function(e){var t,n;return e.nodeName.toLowerCase()==="input"&&(t=e.type)==="text"&&((n=e.getAttribute("type"))==null||n.toLowerCase()===t)},radio:rt("radio"),checkbox:rt("checkbox"),file:rt("file"),password:rt("password"),image:rt("image"),submit:it("submit"),reset:it("reset"),button:function(e){var t=e.nodeName.toLowerCase();return t==="input"&&e.type==="button"||t==="button"},input:function(e){return V.test(e.nodeName)},focus:function(e){var t=e.ownerDocument;return e===t.activeElement&&(!t.hasFocus||t.hasFocus())&&!!(e.type||e.href||~e.tabIndex)},active:function(e){return e===e.ownerDocument.activeElement},first:st(function(){return[0]}),last:st(function(e,t){return[t-1]}),eq:st(function(e,t,n){return[n<0?n+t:n]}),even:st(function(e,t){for(var n=0;n=0;)e.push(r);return e}),gt:st(function(e,t,n){for(var r=n<0?n+t:n;++r",e.querySelectorAll("[selected]").length||i.push("\\["+O+"*(?:checked|disabled|ismap|multiple|readonly|selected|value)"),e.querySelectorAll(":checked").length||i.push(":checked")}),K(function(e){e.innerHTML="

      ",e.querySelectorAll("[test^='']").length&&i.push("[*^$]="+O+"*(?:\"\"|'')"),e.innerHTML="",e.querySelectorAll(":enabled").length||i.push(":enabled",":disabled")}),i=new RegExp(i.join("|")),vt=function(e,r,s,o,u){if(!o&&!u&&!i.test(e)){var a,f,l=!0,c=d,h=r,p=r.nodeType===9&&e;if(r.nodeType===1&&r.nodeName.toLowerCase()!=="object"){a=ut(e),(l=r.getAttribute("id"))?c=l.replace(n,"\\$&"):r.setAttribute("id",c),c="[id='"+c+"'] ",f=a.length;while(f--)a[f]=c+a[f].join("");h=z.test(e)&&r.parentNode||r,p=a.join(",")}if(p)try{return S.apply(s,x.call(h.querySelectorAll(p),0)),s}catch(v){}finally{l||r.removeAttribute("id")}}return t(e,r,s,o,u)},u&&(K(function(t){e=u.call(t,"div");try{u.call(t,"[test!='']:sizzle"),s.push("!=",H)}catch(n){}}),s=new RegExp(s.join("|")),nt.matchesSelector=function(t,n){n=n.replace(r,"='$1']");if(!o(t)&&!s.test(n)&&!i.test(n))try{var a=u.call(t,n);if(a||e||t.document&&t.document.nodeType!==11)return a}catch(f){}return nt(n,null,null,[t]).length>0})}(),i.pseudos.nth=i.pseudos.eq,i.filters=mt.prototype=i.pseudos,i.setFilters=new mt,nt.attr=v.attr,v.find=nt,v.expr=nt.selectors,v.expr[":"]=v.expr.pseudos,v.unique=nt.uniqueSort,v.text=nt.getText,v.isXMLDoc=nt.isXML,v.contains=nt.contains}(e);var nt=/Until$/,rt=/^(?:parents|prev(?:Until|All))/,it=/^.[^:#\[\.,]*$/,st=v.expr.match.needsContext,ot={children:!0,contents:!0,next:!0,prev:!0};v.fn.extend({find:function(e){var t,n,r,i,s,o,u=this;if(typeof e!="string")return v(e).filter(function(){for(t=0,n=u.length;t0)for(i=r;i=0:v.filter(e,this).length>0:this.filter(e).length>0)},closest:function(e,t){var n,r=0,i=this.length,s=[],o=st.test(e)||typeof e!="string"?v(e,t||this.context):0;for(;r-1:v.find.matchesSelector(n,e)){s.push(n);break}n=n.parentNode}}return s=s.length>1?v.unique(s):s,this.pushStack(s,"closest",e)},index:function(e){return e?typeof e=="string"?v.inArray(this[0],v(e)):v.inArray(e.jquery?e[0]:e,this):this[0]&&this[0].parentNode?this.prevAll().length:-1},add:function(e,t){var n=typeof e=="string"?v(e,t):v.makeArray(e&&e.nodeType?[e]:e),r=v.merge(this.get(),n);return this.pushStack(ut(n[0])||ut(r[0])?r:v.unique(r))},addBack:function(e){return this.add(e==null?this.prevObject:this.prevObject.filter(e))}}),v.fn.andSelf=v.fn.addBack,v.each({parent:function(e){var t=e.parentNode;return t&&t.nodeType!==11?t:null},parents:function(e){return v.dir(e,"parentNode")},parentsUntil:function(e,t,n){return v.dir(e,"parentNode",n)},next:function(e){return at(e,"nextSibling")},prev:function(e){return at(e,"previousSibling")},nextAll:function(e){return v.dir(e,"nextSibling")},prevAll:function(e){return v.dir(e,"previousSibling")},nextUntil:function(e,t,n){return v.dir(e,"nextSibling",n)},prevUntil:function(e,t,n){return v.dir(e,"previousSibling",n)},siblings:function(e){return v.sibling((e.parentNode||{}).firstChild,e)},children:function(e){return v.sibling(e.firstChild)},contents:function(e){return v.nodeName(e,"iframe")?e.contentDocument||e.contentWindow.document:v.merge([],e.childNodes)}},function(e,t){v.fn[e]=function(n,r){var i=v.map(this,t,n);return nt.test(e)||(r=n),r&&typeof r=="string"&&(i=v.filter(r,i)),i=this.length>1&&!ot[e]?v.unique(i):i,this.length>1&&rt.test(e)&&(i=i.reverse()),this.pushStack(i,e,l.call(arguments).join(","))}}),v.extend({filter:function(e,t,n){return n&&(e=":not("+e+")"),t.length===1?v.find.matchesSelector(t[0],e)?[t[0]]:[]:v.find.matches(e,t)},dir:function(e,n,r){var i=[],s=e[n];while(s&&s.nodeType!==9&&(r===t||s.nodeType!==1||!v(s).is(r)))s.nodeType===1&&i.push(s),s=s[n];return i},sibling:function(e,t){var n=[];for(;e;e=e.nextSibling)e.nodeType===1&&e!==t&&n.push(e);return n}});var ct="abbr|article|aside|audio|bdi|canvas|data|datalist|details|figcaption|figure|footer|header|hgroup|mark|meter|nav|output|progress|section|summary|time|video",ht=/ jQuery\d+="(?:null|\d+)"/g,pt=/^\s+/,dt=/<(?!area|br|col|embed|hr|img|input|link|meta|param)(([\w:]+)[^>]*)\/>/gi,vt=/<([\w:]+)/,mt=/]","i"),Et=/^(?:checkbox|radio)$/,St=/checked\s*(?:[^=]|=\s*.checked.)/i,xt=/\/(java|ecma)script/i,Tt=/^\s*\s*$/g,Nt={option:[1,""],legend:[1,"
      ","
      "],thead:[1,"","
      "],tr:[2,"","
      "],td:[3,"","
      "],col:[2,"","
      "],area:[1,"",""],_default:[0,"",""]},Ct=lt(i),kt=Ct.appendChild(i.createElement("div"));Nt.optgroup=Nt.option,Nt.tbody=Nt.tfoot=Nt.colgroup=Nt.caption=Nt.thead,Nt.th=Nt.td,v.support.htmlSerialize||(Nt._default=[1,"X
      ","
      "]),v.fn.extend({text:function(e){return v.access(this,function(e){return e===t?v.text(this):this.empty().append((this[0]&&this[0].ownerDocument||i).createTextNode(e))},null,e,arguments.length)},wrapAll:function(e){if(v.isFunction(e))return this.each(function(t){v(this).wrapAll(e.call(this,t))});if(this[0]){var t=v(e,this[0].ownerDocument).eq(0).clone(!0);this[0].parentNode&&t.insertBefore(this[0]),t.map(function(){var e=this;while(e.firstChild&&e.firstChild.nodeType===1)e=e.firstChild;return e}).append(this)}return this},wrapInner:function(e){return v.isFunction(e)?this.each(function(t){v(this).wrapInner(e.call(this,t))}):this.each(function(){var t=v(this),n=t.contents();n.length?n.wrapAll(e):t.append(e)})},wrap:function(e){var t=v.isFunction(e);return this.each(function(n){v(this).wrapAll(t?e.call(this,n):e)})},unwrap:function(){return this.parent().each(function(){v.nodeName(this,"body")||v(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,!0,function(e){(this.nodeType===1||this.nodeType===11)&&this.appendChild(e)})},prepend:function(){return this.domManip(arguments,!0,function(e){(this.nodeType===1||this.nodeType===11)&&this.insertBefore(e,this.firstChild)})},before:function(){if(!ut(this[0]))return this.domManip(arguments,!1,function(e){this.parentNode.insertBefore(e,this)});if(arguments.length){var e=v.clean(arguments);return this.pushStack(v.merge(e,this),"before",this.selector)}},after:function(){if(!ut(this[0]))return this.domManip(arguments,!1,function(e){this.parentNode.insertBefore(e,this.nextSibling)});if(arguments.length){var e=v.clean(arguments);return this.pushStack(v.merge(this,e),"after",this.selector)}},remove:function(e,t){var n,r=0;for(;(n=this[r])!=null;r++)if(!e||v.filter(e,[n]).length)!t&&n.nodeType===1&&(v.cleanData(n.getElementsByTagName("*")),v.cleanData([n])),n.parentNode&&n.parentNode.removeChild(n);return this},empty:function(){var e,t=0;for(;(e=this[t])!=null;t++){e.nodeType===1&&v.cleanData(e.getElementsByTagName("*"));while(e.firstChild)e.removeChild(e.firstChild)}return this},clone:function(e,t){return e=e==null?!1:e,t=t==null?e:t,this.map(function(){return v.clone(this,e,t)})},html:function(e){return v.access(this,function(e){var n=this[0]||{},r=0,i=this.length;if(e===t)return n.nodeType===1?n.innerHTML.replace(ht,""):t;if(typeof e=="string"&&!yt.test(e)&&(v.support.htmlSerialize||!wt.test(e))&&(v.support.leadingWhitespace||!pt.test(e))&&!Nt[(vt.exec(e)||["",""])[1].toLowerCase()]){e=e.replace(dt,"<$1>");try{for(;r1&&typeof f=="string"&&St.test(f))return this.each(function(){v(this).domManip(e,n,r)});if(v.isFunction(f))return this.each(function(i){var s=v(this);e[0]=f.call(this,i,n?s.html():t),s.domManip(e,n,r)});if(this[0]){i=v.buildFragment(e,this,l),o=i.fragment,s=o.firstChild,o.childNodes.length===1&&(o=s);if(s){n=n&&v.nodeName(s,"tr");for(u=i.cacheable||c-1;a0?this.clone(!0):this).get(),v(o[i])[t](r),s=s.concat(r);return this.pushStack(s,e,o.selector)}}),v.extend({clone:function(e,t,n){var r,i,s,o;v.support.html5Clone||v.isXMLDoc(e)||!wt.test("<"+e.nodeName+">")?o=e.cloneNode(!0):(kt.innerHTML=e.outerHTML,kt.removeChild(o=kt.firstChild));if((!v.support.noCloneEvent||!v.support.noCloneChecked)&&(e.nodeType===1||e.nodeType===11)&&!v.isXMLDoc(e)){Ot(e,o),r=Mt(e),i=Mt(o);for(s=0;r[s];++s)i[s]&&Ot(r[s],i[s])}if(t){At(e,o);if(n){r=Mt(e),i=Mt(o);for(s=0;r[s];++s)At(r[s],i[s])}}return r=i=null,o},clean:function(e,t,n,r){var s,o,u,a,f,l,c,h,p,d,m,g,y=t===i&&Ct,b=[];if(!t||typeof t.createDocumentFragment=="undefined")t=i;for(s=0;(u=e[s])!=null;s++){typeof u=="number"&&(u+="");if(!u)continue;if(typeof u=="string")if(!gt.test(u))u=t.createTextNode(u);else{y=y||lt(t),c=t.createElement("div"),y.appendChild(c),u=u.replace(dt,"<$1>"),a=(vt.exec(u)||["",""])[1].toLowerCase(),f=Nt[a]||Nt._default,l=f[0],c.innerHTML=f[1]+u+f[2];while(l--)c=c.lastChild;if(!v.support.tbody){h=mt.test(u),p=a==="table"&&!h?c.firstChild&&c.firstChild.childNodes:f[1]===""&&!h?c.childNodes:[];for(o=p.length-1;o>=0;--o)v.nodeName(p[o],"tbody")&&!p[o].childNodes.length&&p[o].parentNode.removeChild(p[o])}!v.support.leadingWhitespace&&pt.test(u)&&c.insertBefore(t.createTextNode(pt.exec(u)[0]),c.firstChild),u=c.childNodes,c.parentNode.removeChild(c)}u.nodeType?b.push(u):v.merge(b,u)}c&&(u=c=y=null);if(!v.support.appendChecked)for(s=0;(u=b[s])!=null;s++)v.nodeName(u,"input")?_t(u):typeof u.getElementsByTagName!="undefined"&&v.grep(u.getElementsByTagName("input"),_t);if(n){m=function(e){if(!e.type||xt.test(e.type))return r?r.push(e.parentNode?e.parentNode.removeChild(e):e):n.appendChild(e)};for(s=0;(u=b[s])!=null;s++)if(!v.nodeName(u,"script")||!m(u))n.appendChild(u),typeof u.getElementsByTagName!="undefined"&&(g=v.grep(v.merge([],u.getElementsByTagName("script")),m),b.splice.apply(b,[s+1,0].concat(g)),s+=g.length)}return b},cleanData:function(e,t){var n,r,i,s,o=0,u=v.expando,a=v.cache,f=v.support.deleteExpando,l=v.event.special;for(;(i=e[o])!=null;o++)if(t||v.acceptData(i)){r=i[u],n=r&&a[r];if(n){if(n.events)for(s in n.events)l[s]?v.event.remove(i,s):v.removeEvent(i,s,n.handle);a[r]&&(delete a[r],f?delete i[u]:i.removeAttribute?i.removeAttribute(u):i[u]=null,v.deletedIds.push(r))}}}}),function(){var e,t;v.uaMatch=function(e){e=e.toLowerCase();var t=/(chrome)[ \/]([\w.]+)/.exec(e)||/(webkit)[ \/]([\w.]+)/.exec(e)||/(opera)(?:.*version|)[ \/]([\w.]+)/.exec(e)||/(msie) ([\w.]+)/.exec(e)||e.indexOf("compatible")<0&&/(mozilla)(?:.*? rv:([\w.]+)|)/.exec(e)||[];return{browser:t[1]||"",version:t[2]||"0"}},e=v.uaMatch(o.userAgent),t={},e.browser&&(t[e.browser]=!0,t.version=e.version),t.chrome?t.webkit=!0:t.webkit&&(t.safari=!0),v.browser=t,v.sub=function(){function e(t,n){return new e.fn.init(t,n)}v.extend(!0,e,this),e.superclass=this,e.fn=e.prototype=this(),e.fn.constructor=e,e.sub=this.sub,e.fn.init=function(r,i){return i&&i instanceof v&&!(i instanceof e)&&(i=e(i)),v.fn.init.call(this,r,i,t)},e.fn.init.prototype=e.fn;var t=e(i);return e}}();var Dt,Pt,Ht,Bt=/alpha\([^)]*\)/i,jt=/opacity=([^)]*)/,Ft=/^(top|right|bottom|left)$/,It=/^(none|table(?!-c[ea]).+)/,qt=/^margin/,Rt=new RegExp("^("+m+")(.*)$","i"),Ut=new RegExp("^("+m+")(?!px)[a-z%]+$","i"),zt=new RegExp("^([-+])=("+m+")","i"),Wt={BODY:"block"},Xt={position:"absolute",visibility:"hidden",display:"block"},Vt={letterSpacing:0,fontWeight:400},$t=["Top","Right","Bottom","Left"],Jt=["Webkit","O","Moz","ms"],Kt=v.fn.toggle;v.fn.extend({css:function(e,n){return v.access(this,function(e,n,r){return r!==t?v.style(e,n,r):v.css(e,n)},e,n,arguments.length>1)},show:function(){return Yt(this,!0)},hide:function(){return Yt(this)},toggle:function(e,t){var n=typeof e=="boolean";return v.isFunction(e)&&v.isFunction(t)?Kt.apply(this,arguments):this.each(function(){(n?e:Gt(this))?v(this).show():v(this).hide()})}}),v.extend({cssHooks:{opacity:{get:function(e,t){if(t){var n=Dt(e,"opacity");return n===""?"1":n}}}},cssNumber:{fillOpacity:!0,fontWeight:!0,lineHeight:!0,opacity:!0,orphans:!0,widows:!0,zIndex:!0,zoom:!0},cssProps:{"float":v.support.cssFloat?"cssFloat":"styleFloat"},style:function(e,n,r,i){if(!e||e.nodeType===3||e.nodeType===8||!e.style)return;var s,o,u,a=v.camelCase(n),f=e.style;n=v.cssProps[a]||(v.cssProps[a]=Qt(f,a)),u=v.cssHooks[n]||v.cssHooks[a];if(r===t)return u&&"get"in u&&(s=u.get(e,!1,i))!==t?s:f[n];o=typeof r,o==="string"&&(s=zt.exec(r))&&(r=(s[1]+1)*s[2]+parseFloat(v.css(e,n)),o="number");if(r==null||o==="number"&&isNaN(r))return;o==="number"&&!v.cssNumber[a]&&(r+="px");if(!u||!("set"in u)||(r=u.set(e,r,i))!==t)try{f[n]=r}catch(l){}},css:function(e,n,r,i){var s,o,u,a=v.camelCase(n);return n=v.cssProps[a]||(v.cssProps[a]=Qt(e.style,a)),u=v.cssHooks[n]||v.cssHooks[a],u&&"get"in u&&(s=u.get(e,!0,i)),s===t&&(s=Dt(e,n)),s==="normal"&&n in Vt&&(s=Vt[n]),r||i!==t?(o=parseFloat(s),r||v.isNumeric(o)?o||0:s):s},swap:function(e,t,n){var r,i,s={};for(i in t)s[i]=e.style[i],e.style[i]=t[i];r=n.call(e);for(i in t)e.style[i]=s[i];return r}}),e.getComputedStyle?Dt=function(t,n){var r,i,s,o,u=e.getComputedStyle(t,null),a=t.style;return u&&(r=u.getPropertyValue(n)||u[n],r===""&&!v.contains(t.ownerDocument,t)&&(r=v.style(t,n)),Ut.test(r)&&qt.test(n)&&(i=a.width,s=a.minWidth,o=a.maxWidth,a.minWidth=a.maxWidth=a.width=r,r=u.width,a.width=i,a.minWidth=s,a.maxWidth=o)),r}:i.documentElement.currentStyle&&(Dt=function(e,t){var n,r,i=e.currentStyle&&e.currentStyle[t],s=e.style;return i==null&&s&&s[t]&&(i=s[t]),Ut.test(i)&&!Ft.test(t)&&(n=s.left,r=e.runtimeStyle&&e.runtimeStyle.left,r&&(e.runtimeStyle.left=e.currentStyle.left),s.left=t==="fontSize"?"1em":i,i=s.pixelLeft+"px",s.left=n,r&&(e.runtimeStyle.left=r)),i===""?"auto":i}),v.each(["height","width"],function(e,t){v.cssHooks[t]={get:function(e,n,r){if(n)return e.offsetWidth===0&&It.test(Dt(e,"display"))?v.swap(e,Xt,function(){return tn(e,t,r)}):tn(e,t,r)},set:function(e,n,r){return Zt(e,n,r?en(e,t,r,v.support.boxSizing&&v.css(e,"boxSizing")==="border-box"):0)}}}),v.support.opacity||(v.cssHooks.opacity={get:function(e,t){return jt.test((t&&e.currentStyle?e.currentStyle.filter:e.style.filter)||"")?.01*parseFloat(RegExp.$1)+"":t?"1":""},set:function(e,t){var n=e.style,r=e.currentStyle,i=v.isNumeric(t)?"alpha(opacity="+t*100+")":"",s=r&&r.filter||n.filter||"";n.zoom=1;if(t>=1&&v.trim(s.replace(Bt,""))===""&&n.removeAttribute){n.removeAttribute("filter");if(r&&!r.filter)return}n.filter=Bt.test(s)?s.replace(Bt,i):s+" "+i}}),v(function(){v.support.reliableMarginRight||(v.cssHooks.marginRight={get:function(e,t){return v.swap(e,{display:"inline-block"},function(){if(t)return Dt(e,"marginRight")})}}),!v.support.pixelPosition&&v.fn.position&&v.each(["top","left"],function(e,t){v.cssHooks[t]={get:function(e,n){if(n){var r=Dt(e,t);return Ut.test(r)?v(e).position()[t]+"px":r}}}})}),v.expr&&v.expr.filters&&(v.expr.filters.hidden=function(e){return e.offsetWidth===0&&e.offsetHeight===0||!v.support.reliableHiddenOffsets&&(e.style&&e.style.display||Dt(e,"display"))==="none"},v.expr.filters.visible=function(e){return!v.expr.filters.hidden(e)}),v.each({margin:"",padding:"",border:"Width"},function(e,t){v.cssHooks[e+t]={expand:function(n){var r,i=typeof n=="string"?n.split(" "):[n],s={};for(r=0;r<4;r++)s[e+$t[r]+t]=i[r]||i[r-2]||i[0];return s}},qt.test(e)||(v.cssHooks[e+t].set=Zt)});var rn=/%20/g,sn=/\[\]$/,on=/\r?\n/g,un=/^(?:color|date|datetime|datetime-local|email|hidden|month|number|password|range|search|tel|text|time|url|week)$/i,an=/^(?:select|textarea)/i;v.fn.extend({serialize:function(){return v.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?v.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&&(this.checked||an.test(this.nodeName)||un.test(this.type))}).map(function(e,t){var n=v(this).val();return n==null?null:v.isArray(n)?v.map(n,function(e,n){return{name:t.name,value:e.replace(on,"\r\n")}}):{name:t.name,value:n.replace(on,"\r\n")}}).get()}}),v.param=function(e,n){var r,i=[],s=function(e,t){t=v.isFunction(t)?t():t==null?"":t,i[i.length]=encodeURIComponent(e)+"="+encodeURIComponent(t)};n===t&&(n=v.ajaxSettings&&v.ajaxSettings.traditional);if(v.isArray(e)||e.jquery&&!v.isPlainObject(e))v.each(e,function(){s(this.name,this.value)});else for(r in e)fn(r,e[r],n,s);return i.join("&").replace(rn,"+")};var ln,cn,hn=/#.*$/,pn=/^(.*?):[ \t]*([^\r\n]*)\r?$/mg,dn=/^(?:about|app|app\-storage|.+\-extension|file|res|widget):$/,vn=/^(?:GET|HEAD)$/,mn=/^\/\//,gn=/\?/,yn=/)<[^<]*)*<\/script>/gi,bn=/([?&])_=[^&]*/,wn=/^([\w\+\.\-]+:)(?:\/\/([^\/?#:]*)(?::(\d+)|)|)/,En=v.fn.load,Sn={},xn={},Tn=["*/"]+["*"];try{cn=s.href}catch(Nn){cn=i.createElement("a"),cn.href="",cn=cn.href}ln=wn.exec(cn.toLowerCase())||[],v.fn.load=function(e,n,r){if(typeof e!="string"&&En)return En.apply(this,arguments);if(!this.length)return this;var i,s,o,u=this,a=e.indexOf(" ");return a>=0&&(i=e.slice(a,e.length),e=e.slice(0,a)),v.isFunction(n)?(r=n,n=t):n&&typeof n=="object"&&(s="POST"),v.ajax({url:e,type:s,dataType:"html",data:n,complete:function(e,t){r&&u.each(r,o||[e.responseText,t,e])}}).done(function(e){o=arguments,u.html(i?v("
      ").append(e.replace(yn,"")).find(i):e)}),this},v.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "),function(e,t){v.fn[t]=function(e){return this.on(t,e)}}),v.each(["get","post"],function(e,n){v[n]=function(e,r,i,s){return v.isFunction(r)&&(s=s||i,i=r,r=t),v.ajax({type:n,url:e,data:r,success:i,dataType:s})}}),v.extend({getScript:function(e,n){return v.get(e,t,n,"script")},getJSON:function(e,t,n){return v.get(e,t,n,"json")},ajaxSetup:function(e,t){return t?Ln(e,v.ajaxSettings):(t=e,e=v.ajaxSettings),Ln(e,t),e},ajaxSettings:{url:cn,isLocal:dn.test(ln[1]),global:!0,type:"GET",contentType:"application/x-www-form-urlencoded; charset=UTF-8",processData:!0,async:!0,accepts:{xml:"application/xml, text/xml",html:"text/html",text:"text/plain",json:"application/json, text/javascript","*":Tn},contents:{xml:/xml/,html:/html/,json:/json/},responseFields:{xml:"responseXML",text:"responseText"},converters:{"* text":e.String,"text html":!0,"text json":v.parseJSON,"text xml":v.parseXML},flatOptions:{context:!0,url:!0}},ajaxPrefilter:Cn(Sn),ajaxTransport:Cn(xn),ajax:function(e,n){function T(e,n,s,a){var l,y,b,w,S,T=n;if(E===2)return;E=2,u&&clearTimeout(u),o=t,i=a||"",x.readyState=e>0?4:0,s&&(w=An(c,x,s));if(e>=200&&e<300||e===304)c.ifModified&&(S=x.getResponseHeader("Last-Modified"),S&&(v.lastModified[r]=S),S=x.getResponseHeader("Etag"),S&&(v.etag[r]=S)),e===304?(T="notmodified",l=!0):(l=On(c,w),T=l.state,y=l.data,b=l.error,l=!b);else{b=T;if(!T||e)T="error",e<0&&(e=0)}x.status=e,x.statusText=(n||T)+"",l?d.resolveWith(h,[y,T,x]):d.rejectWith(h,[x,T,b]),x.statusCode(g),g=t,f&&p.trigger("ajax"+(l?"Success":"Error"),[x,c,l?y:b]),m.fireWith(h,[x,T]),f&&(p.trigger("ajaxComplete",[x,c]),--v.active||v.event.trigger("ajaxStop"))}typeof e=="object"&&(n=e,e=t),n=n||{};var r,i,s,o,u,a,f,l,c=v.ajaxSetup({},n),h=c.context||c,p=h!==c&&(h.nodeType||h instanceof v)?v(h):v.event,d=v.Deferred(),m=v.Callbacks("once memory"),g=c.statusCode||{},b={},w={},E=0,S="canceled",x={readyState:0,setRequestHeader:function(e,t){if(!E){var n=e.toLowerCase();e=w[n]=w[n]||e,b[e]=t}return this},getAllResponseHeaders:function(){return E===2?i:null},getResponseHeader:function(e){var n;if(E===2){if(!s){s={};while(n=pn.exec(i))s[n[1].toLowerCase()]=n[2]}n=s[e.toLowerCase()]}return n===t?null:n},overrideMimeType:function(e){return E||(c.mimeType=e),this},abort:function(e){return e=e||S,o&&o.abort(e),T(0,e),this}};d.promise(x),x.success=x.done,x.error=x.fail,x.complete=m.add,x.statusCode=function(e){if(e){var t;if(E<2)for(t in e)g[t]=[g[t],e[t]];else t=e[x.status],x.always(t)}return this},c.url=((e||c.url)+"").replace(hn,"").replace(mn,ln[1]+"//"),c.dataTypes=v.trim(c.dataType||"*").toLowerCase().split(y),c.crossDomain==null&&(a=wn.exec(c.url.toLowerCase()),c.crossDomain=!(!a||a[1]===ln[1]&&a[2]===ln[2]&&(a[3]||(a[1]==="http:"?80:443))==(ln[3]||(ln[1]==="http:"?80:443)))),c.data&&c.processData&&typeof c.data!="string"&&(c.data=v.param(c.data,c.traditional)),kn(Sn,c,n,x);if(E===2)return x;f=c.global,c.type=c.type.toUpperCase(),c.hasContent=!vn.test(c.type),f&&v.active++===0&&v.event.trigger("ajaxStart");if(!c.hasContent){c.data&&(c.url+=(gn.test(c.url)?"&":"?")+c.data,delete c.data),r=c.url;if(c.cache===!1){var N=v.now(),C=c.url.replace(bn,"$1_="+N);c.url=C+(C===c.url?(gn.test(c.url)?"&":"?")+"_="+N:"")}}(c.data&&c.hasContent&&c.contentType!==!1||n.contentType)&&x.setRequestHeader("Content-Type",c.contentType),c.ifModified&&(r=r||c.url,v.lastModified[r]&&x.setRequestHeader("If-Modified-Since",v.lastModified[r]),v.etag[r]&&x.setRequestHeader("If-None-Match",v.etag[r])),x.setRequestHeader("Accept",c.dataTypes[0]&&c.accepts[c.dataTypes[0]]?c.accepts[c.dataTypes[0]]+(c.dataTypes[0]!=="*"?", "+Tn+"; q=0.01":""):c.accepts["*"]);for(l in c.headers)x.setRequestHeader(l,c.headers[l]);if(!c.beforeSend||c.beforeSend.call(h,x,c)!==!1&&E!==2){S="abort";for(l in{success:1,error:1,complete:1})x[l](c[l]);o=kn(xn,c,n,x);if(!o)T(-1,"No Transport");else{x.readyState=1,f&&p.trigger("ajaxSend",[x,c]),c.async&&c.timeout>0&&(u=setTimeout(function(){x.abort("timeout")},c.timeout));try{E=1,o.send(b,T)}catch(k){if(!(E<2))throw k;T(-1,k)}}return x}return x.abort()},active:0,lastModified:{},etag:{}});var Mn=[],_n=/\?/,Dn=/(=)\?(?=&|$)|\?\?/,Pn=v.now();v.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var e=Mn.pop()||v.expando+"_"+Pn++;return this[e]=!0,e}}),v.ajaxPrefilter("json jsonp",function(n,r,i){var s,o,u,a=n.data,f=n.url,l=n.jsonp!==!1,c=l&&Dn.test(f),h=l&&!c&&typeof a=="string"&&!(n.contentType||"").indexOf("application/x-www-form-urlencoded")&&Dn.test(a);if(n.dataTypes[0]==="jsonp"||c||h)return s=n.jsonpCallback=v.isFunction(n.jsonpCallback)?n.jsonpCallback():n.jsonpCallback,o=e[s],c?n.url=f.replace(Dn,"$1"+s):h?n.data=a.replace(Dn,"$1"+s):l&&(n.url+=(_n.test(f)?"&":"?")+n.jsonp+"="+s),n.converters["script json"]=function(){return u||v.error(s+" was not called"),u[0]},n.dataTypes[0]="json",e[s]=function(){u=arguments},i.always(function(){e[s]=o,n[s]&&(n.jsonpCallback=r.jsonpCallback,Mn.push(s)),u&&v.isFunction(o)&&o(u[0]),u=o=t}),"script"}),v.ajaxSetup({accepts:{script:"text/javascript, application/javascript, application/ecmascript, application/x-ecmascript"},contents:{script:/javascript|ecmascript/},converters:{"text script":function(e){return v.globalEval(e),e}}}),v.ajaxPrefilter("script",function(e){e.cache===t&&(e.cache=!1),e.crossDomain&&(e.type="GET",e.global=!1)}),v.ajaxTransport("script",function(e){if(e.crossDomain){var n,r=i.head||i.getElementsByTagName("head")[0]||i.documentElement;return{send:function(s,o){n=i.createElement("script"),n.async="async",e.scriptCharset&&(n.charset=e.scriptCharset),n.src=e.url,n.onload=n.onreadystatechange=function(e,i){if(i||!n.readyState||/loaded|complete/.test(n.readyState))n.onload=n.onreadystatechange=null,r&&n.parentNode&&r.removeChild(n),n=t,i||o(200,"success")},r.insertBefore(n,r.firstChild)},abort:function(){n&&n.onload(0,1)}}}});var Hn,Bn=e.ActiveXObject?function(){for(var e in Hn)Hn[e](0,1)}:!1,jn=0;v.ajaxSettings.xhr=e.ActiveXObject?function(){return!this.isLocal&&Fn()||In()}:Fn,function(e){v.extend(v.support,{ajax:!!e,cors:!!e&&"withCredentials"in e})}(v.ajaxSettings.xhr()),v.support.ajax&&v.ajaxTransport(function(n){if(!n.crossDomain||v.support.cors){var r;return{send:function(i,s){var o,u,a=n.xhr();n.username?a.open(n.type,n.url,n.async,n.username,n.password):a.open(n.type,n.url,n.async);if(n.xhrFields)for(u in n.xhrFields)a[u]=n.xhrFields[u];n.mimeType&&a.overrideMimeType&&a.overrideMimeType(n.mimeType),!n.crossDomain&&!i["X-Requested-With"]&&(i["X-Requested-With"]="XMLHttpRequest");try{for(u in i)a.setRequestHeader(u,i[u])}catch(f){}a.send(n.hasContent&&n.data||null),r=function(e,i){var u,f,l,c,h;try{if(r&&(i||a.readyState===4)){r=t,o&&(a.onreadystatechange=v.noop,Bn&&delete Hn[o]);if(i)a.readyState!==4&&a.abort();else{u=a.status,l=a.getAllResponseHeaders(),c={},h=a.responseXML,h&&h.documentElement&&(c.xml=h);try{c.text=a.responseText}catch(p){}try{f=a.statusText}catch(p){f=""}!u&&n.isLocal&&!n.crossDomain?u=c.text?200:404:u===1223&&(u=204)}}}catch(d){i||s(-1,d)}c&&s(u,f,c,l)},n.async?a.readyState===4?setTimeout(r,0):(o=++jn,Bn&&(Hn||(Hn={},v(e).unload(Bn)),Hn[o]=r),a.onreadystatechange=r):r()},abort:function(){r&&r(0,1)}}}});var qn,Rn,Un=/^(?:toggle|show|hide)$/,zn=new RegExp("^(?:([-+])=|)("+m+")([a-z%]*)$","i"),Wn=/queueHooks$/,Xn=[Gn],Vn={"*":[function(e,t){var n,r,i=this.createTween(e,t),s=zn.exec(t),o=i.cur(),u=+o||0,a=1,f=20;if(s){n=+s[2],r=s[3]||(v.cssNumber[e]?"":"px");if(r!=="px"&&u){u=v.css(i.elem,e,!0)||n||1;do a=a||".5",u/=a,v.style(i.elem,e,u+r);while(a!==(a=i.cur()/o)&&a!==1&&--f)}i.unit=r,i.start=u,i.end=s[1]?u+(s[1]+1)*n:n}return i}]};v.Animation=v.extend(Kn,{tweener:function(e,t){v.isFunction(e)?(t=e,e=["*"]):e=e.split(" ");var n,r=0,i=e.length;for(;r-1,f={},l={},c,h;a?(l=i.position(),c=l.top,h=l.left):(c=parseFloat(o)||0,h=parseFloat(u)||0),v.isFunction(t)&&(t=t.call(e,n,s)),t.top!=null&&(f.top=t.top-s.top+c),t.left!=null&&(f.left=t.left-s.left+h),"using"in t?t.using.call(e,f):i.css(f)}},v.fn.extend({position:function(){if(!this[0])return;var e=this[0],t=this.offsetParent(),n=this.offset(),r=er.test(t[0].nodeName)?{top:0,left:0}:t.offset();return n.top-=parseFloat(v.css(e,"marginTop"))||0,n.left-=parseFloat(v.css(e,"marginLeft"))||0,r.top+=parseFloat(v.css(t[0],"borderTopWidth"))||0,r.left+=parseFloat(v.css(t[0],"borderLeftWidth"))||0,{top:n.top-r.top,left:n.left-r.left}},offsetParent:function(){return this.map(function(){var e=this.offsetParent||i.body;while(e&&!er.test(e.nodeName)&&v.css(e,"position")==="static")e=e.offsetParent;return e||i.body})}}),v.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(e,n){var r=/Y/.test(n);v.fn[e]=function(i){return v.access(this,function(e,i,s){var o=tr(e);if(s===t)return o?n in o?o[n]:o.document.documentElement[i]:e[i];o?o.scrollTo(r?v(o).scrollLeft():s,r?s:v(o).scrollTop()):e[i]=s},e,i,arguments.length,null)}}),v.each({Height:"height",Width:"width"},function(e,n){v.each({padding:"inner"+e,content:n,"":"outer"+e},function(r,i){v.fn[i]=function(i,s){var o=arguments.length&&(r||typeof i!="boolean"),u=r||(i===!0||s===!0?"margin":"border");return v.access(this,function(n,r,i){var s;return v.isWindow(n)?n.document.documentElement["client"+e]:n.nodeType===9?(s=n.documentElement,Math.max(n.body["scroll"+e],s["scroll"+e],n.body["offset"+e],s["offset"+e],s["client"+e])):i===t?v.css(n,r,i,u):v.style(n,r,i,u)},n,o?i:t,o,null)}})}),e.jQuery=e.$=v,typeof define=="function"&&define.amd&&define.amd.jQuery&&define("jquery",[],function(){return v})})(window); +\ No newline at end of file +diff -r 85f290e474e2 build/_static/minus.png +Binary file build/_static/minus.png has changed +diff -r 85f290e474e2 build/_static/nature.css +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_static/nature.css Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,245 @@ ++/* ++ * nature.css_t ++ * ~~~~~~~~~~~~ ++ * ++ * Sphinx stylesheet -- nature theme. ++ * ++ * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. ++ * :license: BSD, see LICENSE for details. ++ * ++ */ ++ ++@import url("basic.css"); ++ ++/* -- page layout ----------------------------------------------------------- */ ++ ++body { ++ font-family: Arial, sans-serif; ++ font-size: 100%; ++ background-color: #111; ++ color: #555; ++ margin: 0; ++ padding: 0; ++} ++ ++div.documentwrapper { ++ float: left; ++ width: 100%; ++} ++ ++div.bodywrapper { ++ margin: 0 0 0 230px; ++} ++ ++hr { ++ border: 1px solid #B1B4B6; ++} ++ ++div.document { ++ background-color: #eee; ++} ++ ++div.body { ++ background-color: #ffffff; ++ color: #3E4349; ++ padding: 0 30px 30px 30px; ++ font-size: 0.9em; ++} ++ ++div.footer { ++ color: #555; ++ width: 100%; ++ padding: 13px 0; ++ text-align: center; ++ font-size: 75%; ++} ++ ++div.footer a { ++ color: #444; ++ text-decoration: underline; ++} ++ ++div.related { ++ background-color: #6BA81E; ++ line-height: 32px; ++ color: #fff; ++ text-shadow: 0px 1px 0 #444; ++ font-size: 0.9em; ++} ++ ++div.related a { ++ color: #E2F3CC; ++} ++ ++div.sphinxsidebar { ++ font-size: 0.75em; ++ line-height: 1.5em; ++} ++ ++div.sphinxsidebarwrapper{ ++ padding: 20px 0; ++} ++ ++div.sphinxsidebar h3, ++div.sphinxsidebar h4 { ++ font-family: Arial, sans-serif; ++ color: #222; ++ font-size: 1.2em; ++ font-weight: normal; ++ margin: 0; ++ padding: 5px 10px; ++ background-color: #ddd; ++ text-shadow: 1px 1px 0 white ++} ++ ++div.sphinxsidebar h4{ ++ font-size: 1.1em; ++} ++ ++div.sphinxsidebar h3 a { ++ color: #444; ++} ++ ++ ++div.sphinxsidebar p { ++ color: #888; ++ padding: 5px 20px; ++} ++ ++div.sphinxsidebar p.topless { ++} ++ ++div.sphinxsidebar ul { ++ margin: 10px 20px; ++ padding: 0; ++ color: #000; ++} ++ ++div.sphinxsidebar a { ++ color: #444; ++} ++ ++div.sphinxsidebar input { ++ border: 1px solid #ccc; ++ font-family: sans-serif; ++ font-size: 1em; ++} ++ ++div.sphinxsidebar input[type=text]{ ++ margin-left: 20px; ++} ++ ++/* -- body styles ----------------------------------------------------------- */ ++ ++a { ++ color: #005B81; ++ text-decoration: none; ++} ++ ++a:hover { ++ color: #E32E00; ++ text-decoration: underline; ++} ++ ++div.body h1, ++div.body h2, ++div.body h3, ++div.body h4, ++div.body h5, ++div.body h6 { ++ font-family: Arial, sans-serif; ++ background-color: #BED4EB; ++ font-weight: normal; ++ color: #212224; ++ margin: 30px 0px 10px 0px; ++ padding: 5px 0 5px 10px; ++ text-shadow: 0px 1px 0 white ++} ++ ++div.body h1 { border-top: 20px solid white; margin-top: 0; font-size: 200%; } ++div.body h2 { font-size: 150%; background-color: #C8D5E3; } ++div.body h3 { font-size: 120%; background-color: #D8DEE3; } ++div.body h4 { font-size: 110%; background-color: #D8DEE3; } ++div.body h5 { font-size: 100%; background-color: #D8DEE3; } ++div.body h6 { font-size: 100%; background-color: #D8DEE3; } ++ ++a.headerlink { ++ color: #c60f0f; ++ font-size: 0.8em; ++ padding: 0 4px 0 4px; ++ text-decoration: none; ++} ++ ++a.headerlink:hover { ++ background-color: #c60f0f; ++ color: white; ++} ++ ++div.body p, div.body dd, div.body li { ++ line-height: 1.5em; ++} ++ ++div.admonition p.admonition-title + p { ++ display: inline; ++} ++ ++div.highlight{ ++ background-color: white; ++} ++ ++div.note { ++ background-color: #eee; ++ border: 1px solid #ccc; ++} ++ ++div.seealso { ++ background-color: #ffc; ++ border: 1px solid #ff6; ++} ++ ++div.topic { ++ background-color: #eee; ++} ++ ++div.warning { ++ background-color: #ffe4e4; ++ border: 1px solid #f66; ++} ++ ++p.admonition-title { ++ display: inline; ++} ++ ++p.admonition-title:after { ++ content: ":"; ++} ++ ++pre { ++ padding: 10px; ++ background-color: White; ++ color: #222; ++ line-height: 1.2em; ++ border: 1px solid #C6C9CB; ++ font-size: 1.1em; ++ margin: 1.5em 0 1.5em 0; ++ -webkit-box-shadow: 1px 1px 1px #d8d8d8; ++ -moz-box-shadow: 1px 1px 1px #d8d8d8; ++} ++ ++tt { ++ background-color: #ecf0f3; ++ color: #222; ++ /* padding: 1px 2px; */ ++ font-size: 1.1em; ++ font-family: monospace; ++} ++ ++.viewcode-back { ++ font-family: Arial, sans-serif; ++} ++ ++div.viewcode-block:target { ++ background-color: #f4debf; ++ border-top: 1px solid #ac9; ++ border-bottom: 1px solid #ac9; ++} +\ No newline at end of file +diff -r 85f290e474e2 build/_static/plus.png +Binary file build/_static/plus.png has changed +diff -r 85f290e474e2 build/_static/pygments.css +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_static/pygments.css Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,62 @@ ++.highlight .hll { background-color: #ffffcc } ++.highlight { background: #eeffcc; } ++.highlight .c { color: #408090; font-style: italic } /* Comment */ ++.highlight .err { border: 1px solid #FF0000 } /* Error */ ++.highlight .k { color: #007020; font-weight: bold } /* Keyword */ ++.highlight .o { color: #666666 } /* Operator */ ++.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */ ++.highlight .cp { color: #007020 } /* Comment.Preproc */ ++.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */ ++.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */ ++.highlight .gd { color: #A00000 } /* Generic.Deleted */ ++.highlight .ge { font-style: italic } /* Generic.Emph */ ++.highlight .gr { color: #FF0000 } /* Generic.Error */ ++.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */ ++.highlight .gi { color: #00A000 } /* Generic.Inserted */ ++.highlight .go { color: #333333 } /* Generic.Output */ ++.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */ ++.highlight .gs { font-weight: bold } /* Generic.Strong */ ++.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ ++.highlight .gt { color: #0044DD } /* Generic.Traceback */ ++.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */ ++.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */ ++.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */ ++.highlight .kp { color: #007020 } /* Keyword.Pseudo */ ++.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */ ++.highlight .kt { color: #902000 } /* Keyword.Type */ ++.highlight .m { color: #208050 } /* Literal.Number */ ++.highlight .s { color: #4070a0 } /* Literal.String */ ++.highlight .na { color: #4070a0 } /* Name.Attribute */ ++.highlight .nb { color: #007020 } /* Name.Builtin */ ++.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */ ++.highlight .no { color: #60add5 } /* Name.Constant */ ++.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */ ++.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */ ++.highlight .ne { color: #007020 } /* Name.Exception */ ++.highlight .nf { color: #06287e } /* Name.Function */ ++.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */ ++.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */ ++.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */ ++.highlight .nv { color: #bb60d5 } /* Name.Variable */ ++.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */ ++.highlight .w { color: #bbbbbb } /* Text.Whitespace */ ++.highlight .mf { color: #208050 } /* Literal.Number.Float */ ++.highlight .mh { color: #208050 } /* Literal.Number.Hex */ ++.highlight .mi { color: #208050 } /* Literal.Number.Integer */ ++.highlight .mo { color: #208050 } /* Literal.Number.Oct */ ++.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */ ++.highlight .sc { color: #4070a0 } /* Literal.String.Char */ ++.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */ ++.highlight .s2 { color: #4070a0 } /* Literal.String.Double */ ++.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */ ++.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */ ++.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */ ++.highlight .sx { color: #c65d09 } /* Literal.String.Other */ ++.highlight .sr { color: #235388 } /* Literal.String.Regex */ ++.highlight .s1 { color: #4070a0 } /* Literal.String.Single */ ++.highlight .ss { color: #517918 } /* Literal.String.Symbol */ ++.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */ ++.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */ ++.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */ ++.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */ ++.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */ +\ No newline at end of file +diff -r 85f290e474e2 build/_static/searchtools.js +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/_static/searchtools.js Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,622 @@ ++/* ++ * searchtools.js_t ++ * ~~~~~~~~~~~~~~~~ ++ * ++ * Sphinx JavaScript utilties for the full-text search. ++ * ++ * :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS. ++ * :license: BSD, see LICENSE for details. ++ * ++ */ ++ ++ ++/** ++ * Porter Stemmer ++ */ ++var Stemmer = function() { ++ ++ var step2list = { ++ ational: 'ate', ++ tional: 'tion', ++ enci: 'ence', ++ anci: 'ance', ++ izer: 'ize', ++ bli: 'ble', ++ alli: 'al', ++ entli: 'ent', ++ eli: 'e', ++ ousli: 'ous', ++ ization: 'ize', ++ ation: 'ate', ++ ator: 'ate', ++ alism: 'al', ++ iveness: 'ive', ++ fulness: 'ful', ++ ousness: 'ous', ++ aliti: 'al', ++ iviti: 'ive', ++ biliti: 'ble', ++ logi: 'log' ++ }; ++ ++ var step3list = { ++ icate: 'ic', ++ ative: '', ++ alize: 'al', ++ iciti: 'ic', ++ ical: 'ic', ++ ful: '', ++ ness: '' ++ }; ++ ++ var c = "[^aeiou]"; // consonant ++ var v = "[aeiouy]"; // vowel ++ var C = c + "[^aeiouy]*"; // consonant sequence ++ var V = v + "[aeiou]*"; // vowel sequence ++ ++ var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 ++ var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 ++ var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 ++ var s_v = "^(" + C + ")?" + v; // vowel in stem ++ ++ this.stemWord = function (w) { ++ var stem; ++ var suffix; ++ var firstch; ++ var origword = w; ++ ++ if (w.length < 3) ++ return w; ++ ++ var re; ++ var re2; ++ var re3; ++ var re4; ++ ++ firstch = w.substr(0,1); ++ if (firstch == "y") ++ w = firstch.toUpperCase() + w.substr(1); ++ ++ // Step 1a ++ re = /^(.+?)(ss|i)es$/; ++ re2 = /^(.+?)([^s])s$/; ++ ++ if (re.test(w)) ++ w = w.replace(re,"$1$2"); ++ else if (re2.test(w)) ++ w = w.replace(re2,"$1$2"); ++ ++ // Step 1b ++ re = /^(.+?)eed$/; ++ re2 = /^(.+?)(ed|ing)$/; ++ if (re.test(w)) { ++ var fp = re.exec(w); ++ re = new RegExp(mgr0); ++ if (re.test(fp[1])) { ++ re = /.$/; ++ w = w.replace(re,""); ++ } ++ } ++ else if (re2.test(w)) { ++ var fp = re2.exec(w); ++ stem = fp[1]; ++ re2 = new RegExp(s_v); ++ if (re2.test(stem)) { ++ w = stem; ++ re2 = /(at|bl|iz)$/; ++ re3 = new RegExp("([^aeiouylsz])\\1$"); ++ re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); ++ if (re2.test(w)) ++ w = w + "e"; ++ else if (re3.test(w)) { ++ re = /.$/; ++ w = w.replace(re,""); ++ } ++ else if (re4.test(w)) ++ w = w + "e"; ++ } ++ } ++ ++ // Step 1c ++ re = /^(.+?)y$/; ++ if (re.test(w)) { ++ var fp = re.exec(w); ++ stem = fp[1]; ++ re = new RegExp(s_v); ++ if (re.test(stem)) ++ w = stem + "i"; ++ } ++ ++ // Step 2 ++ re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; ++ if (re.test(w)) { ++ var fp = re.exec(w); ++ stem = fp[1]; ++ suffix = fp[2]; ++ re = new RegExp(mgr0); ++ if (re.test(stem)) ++ w = stem + step2list[suffix]; ++ } ++ ++ // Step 3 ++ re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; ++ if (re.test(w)) { ++ var fp = re.exec(w); ++ stem = fp[1]; ++ suffix = fp[2]; ++ re = new RegExp(mgr0); ++ if (re.test(stem)) ++ w = stem + step3list[suffix]; ++ } ++ ++ // Step 4 ++ re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; ++ re2 = /^(.+?)(s|t)(ion)$/; ++ if (re.test(w)) { ++ var fp = re.exec(w); ++ stem = fp[1]; ++ re = new RegExp(mgr1); ++ if (re.test(stem)) ++ w = stem; ++ } ++ else if (re2.test(w)) { ++ var fp = re2.exec(w); ++ stem = fp[1] + fp[2]; ++ re2 = new RegExp(mgr1); ++ if (re2.test(stem)) ++ w = stem; ++ } ++ ++ // Step 5 ++ re = /^(.+?)e$/; ++ if (re.test(w)) { ++ var fp = re.exec(w); ++ stem = fp[1]; ++ re = new RegExp(mgr1); ++ re2 = new RegExp(meq1); ++ re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); ++ if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) ++ w = stem; ++ } ++ re = /ll$/; ++ re2 = new RegExp(mgr1); ++ if (re.test(w) && re2.test(w)) { ++ re = /.$/; ++ w = w.replace(re,""); ++ } ++ ++ // and turn initial Y back to y ++ if (firstch == "y") ++ w = firstch.toLowerCase() + w.substr(1); ++ return w; ++ } ++} ++ ++ ++ ++/** ++ * Simple result scoring code. ++ */ ++var Scorer = { ++ // Implement the following function to further tweak the score for each result ++ // The function takes a result array [filename, title, anchor, descr, score] ++ // and returns the new score. ++ /* ++ score: function(result) { ++ return result[4]; ++ }, ++ */ ++ ++ // query matches the full name of an object ++ objNameMatch: 11, ++ // or matches in the last dotted part of the object name ++ objPartialMatch: 6, ++ // Additive scores depending on the priority of the object ++ objPrio: {0: 15, // used to be importantResults ++ 1: 5, // used to be objectResults ++ 2: -5}, // used to be unimportantResults ++ // Used when the priority is not in the mapping. ++ objPrioDefault: 0, ++ ++ // query found in title ++ title: 15, ++ // query found in terms ++ term: 5 ++}; ++ ++ ++/** ++ * Search Module ++ */ ++var Search = { ++ ++ _index : null, ++ _queued_query : null, ++ _pulse_status : -1, ++ ++ init : function() { ++ var params = $.getQueryParameters(); ++ if (params.q) { ++ var query = params.q[0]; ++ $('input[name="q"]')[0].value = query; ++ this.performSearch(query); ++ } ++ }, ++ ++ loadIndex : function(url) { ++ $.ajax({type: "GET", url: url, data: null, ++ dataType: "script", cache: true, ++ complete: function(jqxhr, textstatus) { ++ if (textstatus != "success") { ++ document.getElementById("searchindexloader").src = url; ++ } ++ }}); ++ }, ++ ++ setIndex : function(index) { ++ var q; ++ this._index = index; ++ if ((q = this._queued_query) !== null) { ++ this._queued_query = null; ++ Search.query(q); ++ } ++ }, ++ ++ hasIndex : function() { ++ return this._index !== null; ++ }, ++ ++ deferQuery : function(query) { ++ this._queued_query = query; ++ }, ++ ++ stopPulse : function() { ++ this._pulse_status = 0; ++ }, ++ ++ startPulse : function() { ++ if (this._pulse_status >= 0) ++ return; ++ function pulse() { ++ var i; ++ Search._pulse_status = (Search._pulse_status + 1) % 4; ++ var dotString = ''; ++ for (i = 0; i < Search._pulse_status; i++) ++ dotString += '.'; ++ Search.dots.text(dotString); ++ if (Search._pulse_status > -1) ++ window.setTimeout(pulse, 500); ++ } ++ pulse(); ++ }, ++ ++ /** ++ * perform a search for something (or wait until index is loaded) ++ */ ++ performSearch : function(query) { ++ // create the required interface elements ++ this.out = $('#search-results'); ++ this.title = $('

      ' + _('Searching') + '

      ').appendTo(this.out); ++ this.dots = $('').appendTo(this.title); ++ this.status = $('

      ').appendTo(this.out); ++ this.output = $('
      '); ++ } ++ // Prettify the comment rating. ++ comment.pretty_rating = comment.rating + ' point' + ++ (comment.rating == 1 ? '' : 's'); ++ // Make a class (for displaying not yet moderated comments differently) ++ comment.css_class = comment.displayed ? '' : ' moderate'; ++ // Create a div for this comment. ++ var context = $.extend({}, opts, comment); ++ var div = $(renderTemplate(commentTemplate, context)); ++ ++ // If the user has voted on this comment, highlight the correct arrow. ++ if (comment.vote) { ++ var direction = (comment.vote == 1) ? 'u' : 'd'; ++ div.find('#' + direction + 'v' + comment.id).hide(); ++ div.find('#' + direction + 'u' + comment.id).show(); ++ } ++ ++ if (opts.moderator || comment.text != '[deleted]') { ++ div.find('a.reply').show(); ++ if (comment.proposal_diff) ++ div.find('#sp' + comment.id).show(); ++ if (opts.moderator && !comment.displayed) ++ div.find('#cm' + comment.id).show(); ++ if (opts.moderator || (opts.username == comment.username)) ++ div.find('#dc' + comment.id).show(); ++ } ++ return div; ++ } ++ ++ /** ++ * A simple template renderer. Placeholders such as <%id%> are replaced ++ * by context['id'] with items being escaped. Placeholders such as <#id#> ++ * are not escaped. ++ */ ++ function renderTemplate(template, context) { ++ var esc = $(document.createElement('div')); ++ ++ function handle(ph, escape) { ++ var cur = context; ++ $.each(ph.split('.'), function() { ++ cur = cur[this]; ++ }); ++ return escape ? esc.text(cur || "").html() : cur; ++ } ++ ++ return template.replace(/<([%#])([\w\.]*)\1>/g, function() { ++ return handle(arguments[2], arguments[1] == '%' ? true : false); ++ }); ++ } ++ ++ /** Flash an error message briefly. */ ++ function showError(message) { ++ $(document.createElement('div')).attr({'class': 'popup-error'}) ++ .append($(document.createElement('div')) ++ .attr({'class': 'error-message'}).text(message)) ++ .appendTo('body') ++ .fadeIn("slow") ++ .delay(2000) ++ .fadeOut("slow"); ++ } ++ ++ /** Add a link the user uses to open the comments popup. */ ++ $.fn.comment = function() { ++ return this.each(function() { ++ var id = $(this).attr('id').substring(1); ++ var count = COMMENT_METADATA[id]; ++ var title = count + ' comment' + (count == 1 ? '' : 's'); ++ var image = count > 0 ? opts.commentBrightImage : opts.commentImage; ++ var addcls = count == 0 ? ' nocomment' : ''; ++ $(this) ++ .append( ++ $(document.createElement('a')).attr({ ++ href: '#', ++ 'class': 'sphinx-comment-open' + addcls, ++ id: 'ao' + id ++ }) ++ .append($(document.createElement('img')).attr({ ++ src: image, ++ alt: 'comment', ++ title: title ++ })) ++ .click(function(event) { ++ event.preventDefault(); ++ show($(this).attr('id').substring(2)); ++ }) ++ ) ++ .append( ++ $(document.createElement('a')).attr({ ++ href: '#', ++ 'class': 'sphinx-comment-close hidden', ++ id: 'ah' + id ++ }) ++ .append($(document.createElement('img')).attr({ ++ src: opts.closeCommentImage, ++ alt: 'close', ++ title: 'close' ++ })) ++ .click(function(event) { ++ event.preventDefault(); ++ hide($(this).attr('id').substring(2)); ++ }) ++ ); ++ }); ++ }; ++ ++ var opts = { ++ processVoteURL: '/_process_vote', ++ addCommentURL: '/_add_comment', ++ getCommentsURL: '/_get_comments', ++ acceptCommentURL: '/_accept_comment', ++ deleteCommentURL: '/_delete_comment', ++ commentImage: '/static/_static/comment.png', ++ closeCommentImage: '/static/_static/comment-close.png', ++ loadingImage: '/static/_static/ajax-loader.gif', ++ commentBrightImage: '/static/_static/comment-bright.png', ++ upArrow: '/static/_static/up.png', ++ downArrow: '/static/_static/down.png', ++ upArrowPressed: '/static/_static/up-pressed.png', ++ downArrowPressed: '/static/_static/down-pressed.png', ++ voting: false, ++ moderator: false ++ }; ++ ++ if (typeof COMMENT_OPTIONS != "undefined") { ++ opts = jQuery.extend(opts, COMMENT_OPTIONS); ++ } ++ ++ var popupTemplate = '\ ++
      \ ++

      \ ++ Sort by:\ ++ best rated\ ++ newest\ ++ oldest\ ++

      \ ++
      Comments
      \ ++
      \ ++ loading comments...
      \ ++
        \ ++
        \ ++

        Add a comment\ ++ (markup):

        \ ++
        \ ++ reStructured text markup: *emph*, **strong**, \ ++ ``code``, \ ++ code blocks: :: and an indented block after blank line
        \ ++
        \ ++ \ ++

        \ ++ \ ++ Propose a change ▹\ ++ \ ++ \ ++ Propose a change ▿\ ++ \ ++

        \ ++ \ ++ \ ++ \ ++ \ ++ \ ++
        \ ++
        '; ++ ++ var commentTemplate = '\ ++
        \ ++
        \ ++
        \ ++ \ ++ \ ++ \ ++ \ ++ \ ++ \ ++
        \ ++
        \ ++ \ ++ \ ++ \ ++ \ ++ \ ++ \ ++
        \ ++
        \ ++
        \ ++

        \ ++ <%username%>\ ++ <%pretty_rating%>\ ++ <%time.delta%>\ ++

        \ ++
        <#text#>
        \ ++

        \ ++ \ ++ reply ▿\ ++ proposal ▹\ ++ proposal ▿\ ++ \ ++ \ ++

        \ ++ 
        \
++<#proposal_diff#>\
++
        \ ++
          \ ++
          \ ++
          \ ++
          \ ++ '; ++ ++ var replyTemplate = '\ ++
        • \ ++
          \ ++
          \ ++ \ ++ \ ++ \ ++ \ ++ \ ++ \ ++
          \ ++
          • '; ++ ++ $(document).ready(function() { ++ init(); ++ }); ++})(jQuery); ++ ++$(document).ready(function() { ++ // add comment anchors for all paragraphs that are commentable ++ $('.sphinx-has-comment').comment(); ++ ++ // highlight search words in search results ++ $("div.context").each(function() { ++ var params = $.getQueryParameters(); ++ var terms = (params.q) ? params.q[0].split(/\s+/) : []; ++ var result = $(this); ++ $.each(terms, function() { ++ result.highlightText(this.toLowerCase(), 'highlighted'); ++ }); ++ }); ++ ++ // directly open comment window if requested ++ var anchor = document.location.hash; ++ if (anchor.substring(0, 9) == '#comment-') { ++ $('#ao' + anchor.substring(9)).click(); ++ document.location.hash = '#s' + anchor.substring(9); ++ } ++}); +diff -r 85f290e474e2 build/buildbots.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/buildbots.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,315 @@ ++ ++ ++ ++ ++ ++ ++ ++ 19. Continuous Integration — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          19. Continuous Integration

          ++

          To assert that there are no regressions in the development and maintenance ++branches, Python has a set of dedicated machines (called buildbots or ++build slaves) used for continuous integration. They span a number of ++hardware/operating system combinations. Furthermore, each machine hosts ++several builders, one per active branch: when a new change is pushed ++to this branch on the public Mercurial repository, all corresponding builders ++will schedule a new build to be run as soon as possible.

          ++

          The build steps run by the buildbots are the following:

          ++
            ++
          • Checkout of the source tree for the changeset which triggered the build
            • ++
          • Compiling Python
            • ++
          • Running the test suite using strenuous settings
            • ++
          • Cleaning up the build tree
            • ++
          ++

          It is your responsibility, as a core developer, to check the automatic ++build results after you push a change to the repository. It is therefore ++important that you get acquainted with the way these results are presented, ++and how various kinds of failures can be explained and diagnosed.

          ++
          ++

          19.1. Checking results of automatic builds

          ++

          There are two ways of visualizing recent build results:

          ++
            ++

          • The Web interface for each branch at http://python.org/dev/buildbot/, ++where the so-called “waterfall” view presents a vertical rundown of recent ++builds for each builder. When interested in one build, you’ll have to ++click on it to know which changesets it corresponds to.

            ++
            • ++

          • The command-line bbreport.py client, which you can get from ++http://code.google.com/p/bbreport/. Installing it is trivial: just add ++the directory containing bbreport.py to your system path so that ++you can run it from any filesystem location. For example, if you want ++to display the latest build results on the development (“default”) branch, ++type:

            ++
            bbreport.py -q 3.x
++
            ++
            ++
            • ++
          ++

          Some buildbots are much faster than others. Over time, you will learn which ++ones produce the quickest results after a build, and which ones take the ++longest time.

          ++

          Also, when several changesets are pushed in a quick succession in the same ++branch, it often happens that a single build is scheduled for all these ++changesets.

          ++
          ++
          ++

          19.2. Stability

          ++

          A subset of the buildbots are marked “stable”. They are taken into account ++when making a new release. The rule is that all stable builders must be free of ++persistent failures when the release is cut. It is absolutely vital ++that core developers fix any issue they introduce on the stable buildbots, ++as soon as possible.

          ++

          This does not mean that other builders’ test results can be taken lightly, ++either. Some of them are known for having platform-specific issues that ++prevent some tests from succeeding (or even terminating at all), but ++introducing additional failures should generally not be an option.

          ++
          ++
          ++

          19.3. Flags-dependent failures

          ++

          Sometimes, while you have run the whole test suite before ++committing, you may witness unexpected failures on the buildbots. One source ++of such discrepancies is if different flags have been passed to the test runner ++or to Python itself. To reproduce, make sure you use the same flags as the ++buildbots: they can be found out simply by clicking the stdio link for ++the failing build’s tests. For example:

          ++
          ./python.exe -Wd -E -bb  ./Lib/test/regrtest.py -uall -rwW
++
          ++
          ++
          ++

          Note

          ++

          Running Lib/test/regrtest.py is exactly equivalent to running ++-m test.

          ++
          ++
          ++
          ++

          19.4. Ordering-dependent failures

          ++

          Sometimes even the failure is subtler, as it relies on the order in which ++the tests are run. The buildbots randomize test order (by using the -r ++option to the test runner) to maximize the probability that potential ++interferences between library modules are exercised; the downside is that it ++can make for seemingly sporadic failures.

          ++

          The --randseed option makes it easy to reproduce the exact randomization ++used in a given build. Again, open the stdio link for the failing test ++run, and check the beginning of the test output proper.

          ++

          Let’s assume, for the sake of example, that the output starts with:

          ++
          ./python -Wd -E -bb Lib/test/regrtest.py -uall -rwW
++== CPython 3.3a0 (default:22ae2b002865, Mar 30 2011, 13:58:40) [GCC 4.4.5]
++==   Linux-2.6.36-gentoo-r5-x86_64-AMD_Athlon-tm-_64_X2_Dual_Core_Processor_4400+-with-gentoo-1.12.14 little-endian
++==   /home/buildbot/buildarea/3.x.ochtman-gentoo-amd64/build/build/test_python_29628
++Testing with flags: sys.flags(debug=0, inspect=0, interactive=0, optimize=0, dont_write_bytecode=0, no_user_site=0, no_site=0, ignore_environment=1, verbose=0, bytes_warning=2, quiet=0)
++Using random seed 2613169
++[  1/353] test_augassign
++[  2/353] test_functools
++
          ++
          ++

          You can reproduce the exact same order using:

          ++
          ./python -Wd -E -bb -m test -uall -rwW --randseed 2613169
++
          ++
          ++

          It will run the following sequence (trimmed for brevity):

          ++
          [  1/353] test_augassign
++[  2/353] test_functools
++[  3/353] test_bool
++[  4/353] test_contains
++[  5/353] test_compileall
++[  6/353] test_unicode
++
          ++
          ++

          If this is enough to reproduce the failure on your setup, you can then ++bisect the test sequence to look for the specific interference causing the ++failure. Copy and paste the test sequence in a text file, then use the ++--fromfile (or -f) option of the test runner to run the exact ++sequence recorded in that text file:

          ++
          ./python -Wd -E -bb -m test -uall -rwW --fromfile mytestsequence.txt
++
          ++
          ++

          In the example sequence above, if test_unicode had failed, you would ++first test the following sequence:

          ++
          [  1/353] test_augassign
++[  2/353] test_functools
++[  3/353] test_bool
++[  6/353] test_unicode
++
          ++
          ++

          And, if it succeeds, the following one instead (which, hopefully, shall ++fail):

          ++
          [  4/353] test_contains
++[  5/353] test_compileall
++[  6/353] test_unicode
++
          ++
          ++

          Then, recursively, narrow down the search until you get a single pair of ++tests which triggers the failure. It is very rare that such an interference ++involves more than two tests. If this is the case, we can only wish you ++good luck!

          ++
          ++

          Note

          ++

          You cannot use the -j option (for parallel testing) when diagnosing ++ordering-dependent failures. Using -j isolates each test in a ++pristine subprocess and, therefore, prevents you from reproducing any ++interference between tests.

          ++
          ++
          ++
          ++

          19.5. Transient failures

          ++

          While we try to make the test suite as reliable as possible, some tests do ++not reach a perfect level of reproducibility. Some of them will sometimes ++display spurious failures, depending on various conditions. Here are common ++offenders:

          ++
            ++
          • Network-related tests, such as test_poplib, test_urllibnet, etc. ++Their failures can stem from adverse network conditions, or imperfect ++thread synchronization in the test code, which often has to run a ++server in a separate thread.
            • ++
          • Tests dealing with delicate issues such as inter-thread or inter-process ++synchronization, or Unix signals: test_multiprocessing, ++test_threading, test_subprocess, test_threadsignals.
            • ++
          ++

          When you think a failure might be transient, it is recommended you confirm by ++waiting for the next build. Still, even if the failure does turn out sporadic ++and unpredictable, the issue should be reported on the bug tracker; even ++better if it can be diagnosed and suppressed by fixing the test’s implementation, ++or by making its parameters - such as a timeout - more robust.

          ++
          ++
          ++

          19.6. Custom builders

          ++

          When working on a long-lived feature branch, or on a bugfix branch which ++enables issue-specific debugging, you will probably want to test your ++work on one or several buildbots. Since your work is hosted in a distinct ++repository, you can’t trigger builds on the regular builders. Instead, ++you have to use one of the custom builders.

          ++

          When creating (“forcing”) a build on a custom builder, you have to provide ++at least two parameters:

          ++
            ++
          • The repository path, relative to http://hg.python.org. For example, ++sandbox/myfixes if http://hg.python.org/sandbox/myfixes is the ++full path to the repository.
            • ++
          • The Mercurial id of the changeset you want to build. To make things less ++tedious, we suggest you do your changes in a separate named branch: you can ++then supply the branch name instead of a specific changeset id.
            • ++
          ++

          If you are interested in the results of a specific test file only, we ++recommend you change (temporarily, of course) the contents of the ++buildbottest clause in Makefile.pre.in; or, for Windows builders, ++the Tools/buildbot/test.bat and Tools/buildbot/test-amd64.bat ++scripts.

          ++
          ++

          Note

          ++

          For security reasons, it is impossible to build repositories from outside ++the http://hg.python.org realm.

          ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          18. Development Cycle

          ++

          Next topic

          ++

          20. Adding to the Stdlib

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/clang.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/clang.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,444 @@ ++ ++ ++ ++ ++ ++ ++ ++ 28. Dynamic Analysis with Clang — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          28. Dynamic Analysis with Clang

          ++

          This document describes how to use Clang to perform analysis on Python and its ++libraries. In addition to performing the analysis, the document will cover ++downloading, building and installing the the latest Clang/LLVM combination ++(which is currently 3.4).

          ++

          This document does not cover interpreting the findings. For a discussion of ++interpreting results, see Marshall Clow’s Testing libc++ with ++-fsanitize=undefined. The ++blog posting is a detailed examinations of issues uncovered by Clang in ++libc++.

          ++
          ++

          28.1. What is Clang?

          ++

          Clang is the C, C++ and Objective C front-end for the LLVM compiler. The ++front-end provides access to LLVM’s optimizer and code generator. The ++sanitizers - or checkers - are hooks into the code generation phase to ++instrument compiled code so suspicious behavior is flagged.

          ++
          ++
          ++

          28.2. What are Sanitizers?

          ++

          Clang sanitizers are runtime checkers used to identify suspicious and undefined ++behavior. The checking occurs at runtime with actual runtime parameters so false ++positives are kept to a minimum.

          ++

          There are a number of sanitizers available, but two that should be used on a ++regular basis are the Address Sanitizer (or ASan) and the Undefined Behavior ++Sanitizer (or UBSan). ASan is invoked with the compiler option ++-fsanitize=address, and UBSan is invoked with -fsanitize=undefined. The ++flags are passed through CFLAGS and CXXFLAGS, and sometimes through ++CC and CXX (in addition to the compiler).

          ++

          A complete list of sanitizers can be found at Controlling Code Generation.

          ++
          ++

          Note

          ++

          Because sanitizers operate at runtime on real program parameters, its ++important to provide a complete set of positive and negative self tests.

          ++
          ++

          Clang and its sanitizers have strengths (and weaknesses). Its just one tool in ++the war chest to uncovering bugs and improving code quality. Clang should be ++used to compliment other methods, including Code Reviews, Valgrind, Coverity, ++etc.

          ++
          ++
          ++

          28.3. Clang/LLVM Setup

          ++

          This portion of the document covers downloading, building and installing Clang ++and LLVM. There are three components to download and build. They are the LLVM ++compiler, the compiler front end and the compiler runtime library.

          ++

          In preparation you should create a scratch directory. Also ensure you are using ++Python 2 and not Python 3. Python 3 will cause the build to fail.

          ++
          ++

          28.3.1. Download, Build and Install

          ++

          Perform the following to download, build and install the Clang/LLVM 3.4.

          ++
          # Download
++wget http://llvm.org/releases/3.4/llvm-3.4.src.tar.gz
++wget http://llvm.org/releases/3.4/clang-3.4.src.tar.gz
++wget http://llvm.org/releases/3.4/compiler-rt-3.4.src.tar.gz
++
++# LLVM
++tar xvf llvm-3.4.src.tar.gz
++cd llvm-3.4/tools
++
++# Clang Front End
++tar xvf ../../clang-3.4.src.tar.gz
++mv clang-3.4 clang
++
++# Compiler RT
++cd ../projects
++tar xvf ../../compiler-rt-3.4.src.tar.gz
++mv compiler-rt-3.4/ compiler-rt
++
++# Build
++cd ..
++./configure --enable-optimized --prefix=/usr/local
++make -j4
++sudo make install
++
          ++
          ++
          ++

          Note

          ++

          If you receive an error 'LibraryDependencies.inc' file not found, then ++ensure you are utilizing Python 2 and not Python 3. If you encounter the ++error after switching to Python 2, then delete everything and start over.

          ++
          ++

          After make install executes, the compilers will be installed in ++/usr/local/bin and the various libraries will be installed in ++/usr/local/lib/clang/3.4/lib/linux/:

          ++
          $ ls /usr/local/lib/clang/3.4/lib/linux/
++libclang_rt.asan-x86_64.a   libclang_rt.profile-x86_64.a
++libclang_rt.dfsan-x86_64.a  libclang_rt.san-x86_64.a
++libclang_rt.full-x86_64.a   libclang_rt.tsan-x86_64.a
++libclang_rt.lsan-x86_64.a   libclang_rt.ubsan_cxx-x86_64.a
++libclang_rt.msan-x86_64.a   libclang_rt.ubsan-x86_64.a
++
          ++
          ++

          On Mac OS X, the libraries are installed in ++/usr/local/lib/clang/3.3/lib/darwin/:

          ++
          $ ls /usr/local/lib/clang/3.3/lib/darwin/
++libclang_rt.10.4.a                    libclang_rt.ios.a
++libclang_rt.asan_osx.a                libclang_rt.osx.a
++libclang_rt.asan_osx_dynamic.dylib    libclang_rt.profile_ios.a
++libclang_rt.cc_kext.a                 libclang_rt.profile_osx.a
++libclang_rt.cc_kext_ios5.a            libclang_rt.ubsan_osx.a
++libclang_rt.eprintf.a
++
          ++
          ++
          ++

          Note

          ++

          You should never have to add the libraries to a project. Clang will handle ++it for you. If you find you cannot pass the -fsanitize=XXX flag through ++make‘s implicit variables (CFLAGS, CXXFLAGS, CC, ++CXXFLAGS, LDFLAGS) during configure, then you should modify the ++makefile after configuring to ensure the flag is passed through the ++compiler.

          ++
          ++

          The installer does not install all the components needed on occasion. For ++example, you might want to run a scan-build or examine the results with ++scan-veiw. You can copy the components by hand with:

          ++
          sudo mkdir /usr/local/bin/scan-build
++sudo cp -r llvm-3.4/tools/clang/tools/scan-build /usr/local/bin
++sudo mkdir /usr/local/bin/scan-view
++sudo cp -r llvm-3.4/tools/clang/tools/scan-view /usr/local/bin
++
          ++
          ++
          ++

          Note

          ++

          Because the installer does not install all the components needed on ++occasion, you should not delete the scratch directory until you are sure ++things work as expected. If a library is missing, then you should search for ++it in the Clang/LLVM build directory.

          ++
          ++
          ++
          ++
          ++

          28.4. Python Build Setup

          ++

          This portion of the document covers invoking Clang and LLVM with the options ++required so the sanitizers analyze Python with under its test suite. Two ++checkers are used - ASan and UBSan.

          ++

          Because the sanitizers are runtime checkers, its best to have as many positive ++and negative self tests as possible. You can never have enough self tests.

          ++

          The general idea is to compile and link with the sanitizer flags. At link time, ++Clang will include the needed runtime libraries. However, you can’t use ++CFLAGS and CXXFLAGS to pass the options through the compiler to the ++linker because the makefile rules for BUILDPYTHON, _testembed and ++_freeze_importlib don’t use the implicit variables.

          ++

          As a workaround to the absence of flags to the linker, you can pass the ++sanitizer options by way of the compilers - CC and CXX. Passing the ++flags though the compiler is used below, but passing them through LDFLAGS is ++also reported to work.

          ++
          ++

          28.4.1. Building Python

          ++

          To begin, export the variables of interest with the desired sanitizers. Its OK ++to specify both sanitizers:

          ++
          # ASan
++export CC="/usr/local/bin/clang -fsanitize=address"
++export CXX="/usr/local/bin/clang++ -fsanitize=address -fno-sanitize=vptr"
++
          ++
          ++

          Or:

          ++
          # UBSan
++export CC="/usr/local/bin/clang -fsanitize=undefined"
++export CXX="/usr/local/bin/clang++ -fsanitize=undefined -fno-sanitize=vptr"
++
          ++
          ++

          The -fno-sanitize=vptr removes vtable checks that are part of UBSan from C++ ++projects due to noise. Its not needed with Python, but you will likely need it ++for other C++ projects.

          ++

          After exporting CC and CXX, configure as normal:

          ++
          $ ./configure
++checking build system type... x86_64-unknown-linux-gnu
++checking host system type... x86_64-unknown-linux-gnu
++checking for --enable-universalsdk... no
++checking for --with-universal-archs... 32-bit
++checking MACHDEP... linux
++checking for --without-gcc... no
++checking for gcc... /usr/local/bin/clang -fsanitize=undefined
++checking whether the C compiler works... yes
++...
++
          ++
          ++

          Next is a standard make (formatting added for clarity):

          ++
          $ make
++/usr/local/bin/clang -fsanitize=undefined -c -Wno-unused-result
++    -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes -I.
++    -IInclude -I./Include -DPy_BUILD_CORE -o Modules/python.o
++    ./Modules/python.c
++/usr/local/bin/clang -fsanitize=undefined -c -Wno-unused-result
++    -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes -I.
++    -IInclude -I./Include -DPy_BUILD_CORE -o Parser/acceler.o
++    Parser/acceler.c
++...
++
          ++
          ++

          Finally is make test (formatting added for clarity):

          ++
          Objects/longobject.c:39:42: runtime error: index -1 out of bounds
++    for type 'PyLongObject [262]'
++Objects/tupleobject.c:188:13: runtime error: member access within
++    misaligned address 0x2b76be018078 for type 'PyGC_Head' (aka
++    'union _gc_head'), which requires 16 byte alignment
++    0x2b76be018078: note: pointer points here
++    00 00 00 00  40 53 5a b6 76 2b 00 00  60 52 5a b6 ...
++                 ^
++...
++
          ++
          ++

          If you are using the address sanitizer, its important to pipe the output through ++asan_symbolize.py to get a good trace. For example, from Issue 20953 during ++compile (formatting added for clarity):

          ++
          $ make test 2>&1 | asan_symbolize.py
++...
++
++/usr/local/bin/clang -fsanitize=address -Xlinker -export-dynamic
++    -o python Modules/python.o libpython3.3m.a -ldl -lutil
++    /usr/local/ssl/lib/libssl.a /usr/local/ssl/lib/libcrypto.a -lm
++./python -E -S -m sysconfig --generate-posix-vars
++=================================================================
++==24064==ERROR: AddressSanitizer: heap-buffer-overflow on address
++0x619000004020 at pc 0x4ed4b2 bp 0x7fff80fff010 sp 0x7fff80fff008
++READ of size 4 at 0x619000004020 thread T0
++  #0 0x4ed4b1 in PyObject_Free Python-3.3.5/./Objects/obmalloc.c:987
++  #1 0x7a2141 in code_dealloc Python-3.3.5/./Objects/codeobject.c:359
++  #2 0x620c00 in PyImport_ImportFrozenModuleObject
++       Python-3.3.5/./Python/import.c:1098
++  #3 0x620d5c in PyImport_ImportFrozenModule
++       Python-3.3.5/./Python/import.c:1114
++  #4 0x63fd07 in import_init Python-3.3.5/./Python/pythonrun.c:206
++  #5 0x63f636 in _Py_InitializeEx_Private
++       Python-3.3.5/./Python/pythonrun.c:369
++  #6 0x681d77 in Py_Main Python-3.3.5/./Modules/main.c:648
++  #7 0x4e6894 in main Python-3.3.5/././Modules/python.c:62
++  #8 0x2abf9a525eac in __libc_start_main
++       /home/aurel32/eglibc/eglibc-2.13/csu/libc-start.c:244
++  #9 0x4e664c in _start (Python-3.3.5/./python+0x4e664c)
++
++AddressSanitizer can not describe address in more detail (wild
++memory access suspected).
++SUMMARY: AddressSanitizer: heap-buffer-overflow
++  Python-3.3.5/./Objects/obmalloc.c:987 PyObject_Free
++Shadow bytes around the buggy address:
++  0x0c327fff87b0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
++  0x0c327fff87c0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
++  0x0c327fff87d0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
++  0x0c327fff87e0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
++  0x0c327fff87f0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
++=>0x0c327fff8800: fa fa fa fa[fa]fa fa fa fa fa fa fa fa fa fa fa
++  0x0c327fff8810: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
++  0x0c327fff8820: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
++  0x0c327fff8830: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
++  0x0c327fff8840: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
++  0x0c327fff8850: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
++Shadow byte legend (one shadow byte represents 8 application bytes):
++  Addressable:           00
++  Partially addressable: 01 02 03 04 05 06 07
++  Heap left redzone:     fa
++  Heap right redzone:    fb
++  Freed heap region:     fd
++  Stack left redzone:    f1
++  Stack mid redzone:     f2
++  Stack right redzone:   f3
++  Stack partial redzone: f4
++  Stack after return:    f5
++  Stack use after scope: f8
++  Global redzone:        f9
++  Global init order:     f6
++  Poisoned by user:      f7
++  ASan internal:         fe
++==24064==ABORTING
++make: *** [pybuilddir.txt] Error 1
++
          ++
          ++
          ++

          Note

          ++

          asan_symbolize.py is supposed to be installed during make install. ++If its not installed, then look in the Clang/LLVM build directory for it and ++copy it to /usr/local/bin.

          ++
          ++
          ++
          ++

          28.4.2. Blacklisting (Ignoring) Findings

          ++

          Clang allows you to alter the behavior of sanitizer tools for certain ++source-level by providing a special blacklist file at compile-time. The ++blacklist is needed because it reports every instance of an issue, even if the ++issue is reported 10’s of thousands of time in un-managed library code.

          ++

          You specify the blacklist with -fsanitize-blacklist=XXX. For example:

          ++
          -fsanitize-blacklist=my_blacklist.txt
++
          ++
          ++

          my_blacklist.txt would then contain entries such as the following. The entry ++will ignore a bug in libc++‘s ios formatting functions:

          ++
          fun:_Ios_Fmtflags
++
          ++
          ++

          As an example with Python 3.4.0, audioop.c will produce a number of ++findings:

          ++
          ./Modules/audioop.c:422:11: runtime error: left shift of negative value -1
++./Modules/audioop.c:446:19: runtime error: left shift of negative value -1
++./Modules/audioop.c:476:19: runtime error: left shift of negative value -1
++./Modules/audioop.c:504:16: runtime error: left shift of negative value -1
++./Modules/audioop.c:533:22: runtime error: left shift of negative value -128
++./Modules/audioop.c:775:19: runtime error: left shift of negative value -70
++./Modules/audioop.c:831:19: runtime error: left shift of negative value -70
++./Modules/audioop.c:881:19: runtime error: left shift of negative value -1
++./Modules/audioop.c:920:22: runtime error: left shift of negative value -70
++./Modules/audioop.c:967:23: runtime error: left shift of negative value -70
++./Modules/audioop.c:968:23: runtime error: left shift of negative value -70
++...
++
          ++
          ++

          One of the function of interest is audioop_getsample_impl (flagged at line ++422), and the blacklist entry would include:

          ++
          fun:audioop_getsample_imp
++
          ++
          ++

          Or, you could ignore the entire file with:

          ++
          src:Modules/audioop.c
++
          ++
          ++

          Unfortunately, you won’t know what to blacklist until you run the sanitizer.

          ++

          The documentation is available at Sanitizer special case list.

          ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          27. Coverity Scan

          ++

          Next topic

          ++

          29. Python Developer FAQ

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/committing.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/committing.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,615 @@ ++ ++ ++ ++ ++ ++ ++ ++ 16. Committing and Pushing Changes — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          16. Committing and Pushing Changes

          ++
          ++

          16.1. Is the change ready for committing?

          ++

          Before a change is committed, you must make sure it is ready to enter the ++public source tree. Draft commits are prohibited. Therefore, you must ++ensure your changes fulfill several mandatory criteria.

          ++
          ++

          Note

          ++

          If you want to share your work-in-progress code on a feature or bugfix, ++either publish patches or create a public fork of the repository.

          ++
          ++
          ++

          16.1.1. Does the test suite still pass?

          ++

          You must run the whole test suite to ensure that it ++passes before pushing any code changes.

          ++
          ++

          Note

          ++

          You really need to run the entire test suite. Running a single test ++is not enough as your changes may have unforeseen effects on other tests ++or library modules.

          ++

          Running the entire test suite doesn’t guarantee that your changes ++will pass the continuous integration tests, as those ++will exercise more possibilities still (such as different platforms or ++build options). But it will at least catch non-build specific, ++non-platform specific errors, therefore minimizing the chance for ++breakage.

          ++
          ++
          ++
          ++

          16.1.2. Patch checklist

          ++

          Apart from running the tests, there’s a simple patch checklist that ++make patchcheck (or ./python.exe Tools/scripts/patchcheck.py on ++Windows) will run through:

          ++
            ++
          • Are there any whitespace problems in Python files? ++(using Tools/scripts/reindent.py)
            • ++
          • Are there any whitespace problems in C files?
            • ++
          • Are there any whitespace problems in the documentation? ++(using Tools/scripts/reindent-rst.py)
            • ++
          • Has the documentation been updated?
            • ++
          • Has the test suite been updated?
            • ++
          • Has Misc/NEWS been updated?
            • ++
          • Has Misc/ACKS been updated?
            • ++
          • Has configure been regenerated, if necessary?
            • ++
          • Has pyconfig.h.in been regenerated, if necessary?
            • ++
          ++

          Note that the automated patch check can’t actually answer all of these ++questions, and even if it could, it still wouldn’t know whether or not ++those answers were appropriate. Aside from the whitespace checks, it is just ++a memory aid to help with remembering the various elements that can go into ++making a complete patch.

          ++
          ++
          ++
          ++

          16.2. Commit Style

          ++

          Once a change patch is ready and tested, it can be committed to the repository. ++We usually prefer to put a whole feature or bugfix into a single commit, but no ++more. In particular:

          ++
            ++
          • Do not fix more than one issue in the same commit (except, of course, if ++one code change fixes all of them).
            • ++
          • Do not do cosmetic changes to unrelated code in the same commit as some ++feature/bugfix.
            • ++
          ++

          It is of course okay to pile up several commits to one branch and merge them ++into another in one merge commit.

          ++
          ++
          ++

          16.3. Handling Others’ Code

          ++

          As a core developer you will occasionally want to commit a patch created by ++someone else. When doing so you will want to make sure of some things.

          ++

          First, make sure the patch is in a good state. Both Lifecycle of a Patch and ++Helping Triage Issues ++explain what is to be expected of a patch. Typically patches that get cleared by ++triagers are good to go except maybe lacking Misc/ACKS and Misc/NEWS ++entries.

          ++

          Second, make sure the patch does not break backwards-compatibility without a ++good reason. This means running the entire test suite to ++make sure everything still passes. It also means that if semantics do change ++there must be a good reason for the breakage of code the change will cause ++(and it will break someone’s code). If you are unsure if the breakage ++is worth it, ask on python-dev.

          ++

          Third, ensure the patch is attributed correctly by adding the contributor’s ++name to Misc/ACKS if they aren’t already there (and didn’t add themselves ++in their patch) and by mentioning “Patch by <x>” in the Misc/NEWS entry ++and the checkin message. If the patch has been heavily modified then “Initial ++patch by <x>” is an appropriate alternate wording.

          ++

          If you omit correct attribution in the initial checkin, then update ACKS ++and NEWS in a subsequent checkin (don’t worry about trying to fix the ++original checkin message in that case).

          ++

          Finally, especially for larger patches, check if the submitter of the ++patch has a CLA in place (indicated by an asterisk following their username ++in the issue tracker). If the asterisk is missing and the patch is ++non-trivial, direct them to the electronic Contributor Licensing Agreement ++to ensure the PSF has the appropriate authorizations in place to relicense ++and redistribute their code.

          ++
          ++
          ++

          16.4. Contributor Licensing Agreements

          ++

          It’s unlikely bug fixes will require a Contributor Licensing Agreement ++unless they touch a lot of code. For new features, it is preferable to ++ask that the contributor submit a signed CLA to the PSF as the associated ++comments, docstrings and documentation are far more likely to reach a ++copyrightable standard.

          ++

          These days, the CLA can be signed electronically through the form linked ++above, and this process is strongly preferred to the old mechanism that ++involved sending a scanned copy of the signed paper form.

          ++

          As discussed on the PSF Contribution page, it is the CLA itself that gives ++the PSF the necessary relicensing rights to redistribute contributions under ++the Python license stack. This is an additional permission granted above and ++beyond the normal permissions provided by the chosen open source license.

          ++

          Some developers may object to the relicensing permissions granted to the PSF ++by the CLA. They’re entirely within their rights to refuse to sign the CLA ++on that basis, but that refusal does mean we can’t accept their patches ++for inclusion.

          ++
          ++
          ++

          16.5. NEWS Entries

          ++

          Almost all changes made to the code base deserve an entry in Misc/NEWS. ++If the change is particularly interesting for end users (e.g. new features, ++significant improvements, or backwards-incompatible changes), an entry in ++the What's New in Python document (in Doc/whatsnew/) should be added ++as well. There are two notable exceptions to this general principle, and they ++both relate to changes that already have a NEWS entry, and have not yet ++been included in any formal release (including alpha and beta releases). ++These exceptions are:

          ++
            ++
          • If a change is reverted prior to release, then the corresponding entry ++is simply removed. Otherwise, a new entry must be added noting that the ++change has been reverted (e.g. when a feature is released in an alpha and ++then cut prior to the first beta).
            • ++
          • If a change is a fix (or other adjustment) to an earlier unreleased change ++and the original NEWS entry remains valid, then no additional entry is ++needed.
            • ++
          ++

          New NEWS entries are customarily added at or near the top of their ++respective sections, so that entries within a section appear in approximate ++order from newest to oldest. However, this is customary and not a ++requirement.

          ++

          The NEWS file is now read by Sphinx to produce the “Changelog” page; accordingly ++it should be valid reStructuredText. The “default role” (single backticks) can ++be used to refer to objects in the documentation. Example NEWS entry:

          ++
          - Issue #15304: Fix warning message when `os.chdir()` fails inside
++  `test.support.temp_cwd()`.  Patch by Chris Jerdonek.
++
          ++
          ++

          (In all other .rst files, the single backticks should not be used. They are ++allowed here because NEWS is meant to be as readable as possible unprocessed.)

          ++

          A nice trick to make Mercurial’s automatic file merge work more smoothly is to ++put a new entry after the first or first two entries rather than at the very ++top. This way if you commit, pull new changesets and merge, the merge will ++succeed automatically.

          ++
          ++
          ++

          16.6. Commit Messages

          ++

          Every commit has a commit message to document why a change was made and to ++communicate that reason to other core developers. Python core developers have ++developed a standard way of formatting commit messages that everyone is ++expected to follow.

          ++

          Our usual convention mimics that used in the Misc/NEWS file. Actually, ++it is common to simply paste the NEWS entry into the commit message. Here ++is an example:

          ++
          Issue #42: the spam module is now more spammy.
++The spam module sporadically came up short on spam. This change
++raises the amount of spam in the module by making it more spammy.
++Thanks to Monty Python for the patch.
++
          ++
          ++

          The first line or sentence is meant to be a dense, to-the-point explanation ++of what the purpose of the commit is. If this is not enough detail for a commit, ++a new paragraph(s) can be added to explain in proper depth what has happened ++(detail should be good enough that a core developer reading the commit message ++understands the justification for the change). Also, if a non-core developer ++contributed to the resolution, it is good practice to credit them.

          ++
          ++

          16.6.1. Mercurial hooks

          ++

          Special hooks have been added to the Mercurial repository to enable notifying ++the issue tracker of a commit related to an issue.

          ++

          A commit message can mention one or several issues in one of the following ++ways:

          ++
          #12345
++issue12345
++issue 12345
++bug12345
++bug 12345
++
          ++
          ++

          where 12345 is the number of the issue. The commit details (including its ++changeset, branch and commit message) will then be posted as a message to the ++issue’s page in the tracker, for each mentioned issue.

          ++

          If “closes” (or “closed”, or “closing”) is prepended, the issue is ++automatically closed as “fixed”.

          ++
          ++
          ++
          ++
          ++

          17. Working with Mercurial

          ++

          As a core developer, the ability to push changes to the official Python ++repositories means you have to be more careful with your workflow:

          ++
            ++
          • You should not push new named branches to the main repository. You can ++still use them in clones that you use for development of patches; you can ++also push these branches to a separate public repository that will be ++dedicated to maintenance of the work before the work gets integrated in the ++main repository.
            • ++
          • You should collapse changesets of a single feature or bugfix before pushing ++the result to the main repository. The reason is that we don’t want the ++history to be full of intermediate commits recording the private history ++of the person working on a patch. If you are using the rebase extension, ++consider adding the --collapse option to hg rebase. The collapse ++extension is another choice.
            • ++
          ++

          Because of these constraints, it can be practical to use other approaches ++such as mq (Mercurial Queues), in order to maintain patches in a single ++local repository and to push them seamlessly when they are ready.

          ++

          It can also be useful to keep a pristine clone of the main repository around, ++as it allows simple reversion of all local changes (even “committed” ones) if ++your local clone gets into a state you aren’t happy with.

          ++
          ++

          17.1. Minimal Configuration

          ++

          To use Mercurial as a committer (both of your and others’ patches), you should ++set up some basic options in your configuration file. Under Windows, ++TortoiseHg has a graphical settings dialog for most options, meaning you ++don’t need to edit the file directly (it is still available in ++%USERPROFILE%\Mercurial.ini). Under other platforms, you must edit ++~/.hgrc.

          ++

          Here are the minimal options you need to activate:

          ++
            ++

          • your username: this setting defines the name that will be used when you ++commit changes. The usual convention is to also include ++an e-mail contact address in there:

            ++
            [ui]
++username = Your Name <email@example.org>
++
            ++
            ++
            • ++

          • extended diffing: this setting enables an extended diff format ++which is more useful than the standard unified diff format as it includes ++metadata about file copies, permission bits, and is able to represent ++binary files:

            ++
            [diff]
++git = on
++
            ++
            ++
            • ++
          ++

          Under Windows, you should also enable the eol extension, which will ++fix any Windows-specific line endings your text editor might insert when you ++create or modify versioned files. The public repository has a hook which ++will reject all changesets having the wrong line endings, so enabling this ++extension on your local computer is in your best interest.

          ++
          ++
          ++

          17.2. Clones Setup

          ++

          There are several possible ways to set up your Mercurial clone(s). If you are ++a core developer, you often need to work on the different branches, so the best ++approach is to have a separate clone/directory for each active branch. If you ++are a contributor, having a single clone might be enough.

          ++
          ++

          17.2.1. Single Clone Approach

          ++

          This approach has the advantage of being simpler because it requires a single ++clone/directory, but, on the other hand, it requires you to recompile Python ++every time you need to switch branch. For this reason, this approach is not ++suggested to core developers, but it’s usually suitable for contributors.

          ++

          See Getting the Source Code to find information about cloning and switching branches.

          ++
          ++
          ++

          17.2.2. Multiple Clones Approach

          ++

          This approach requires you to keep a separate clone/directory for each active ++branch, but, on the other hand, it doesn’t require you to switch branches and ++recompile Python, so it saves times while merging and testing a patch on the ++different branches. For this reason, this approach is suggested to core ++developers.

          ++

          The easiest way to do this is by using the share extension, that can be ++enabled by adding the following lines to your ~/.hgrc:

          ++
          [extensions]
++share =
++
          ++
          ++

          Once you have cloned the hg.python.org/cpython repository ++you can create the other shared clones using:

          ++
          $ hg share cpython 2.7  # create a new shared clone
++$ cd 2.7                # enter the directory
++$ hg up 2.7             # switch to the 2.7 branch
++
          ++
          ++

          You can then repeat the same operation for the other active branches. ++This will create different clones/directories that share the same history. ++This means that once you commit or pull new changesets in one of the clones, ++they will be immediately available in all the other clones (note however that ++while you only need to use hg pull once, you still need to use hg up ++in each clone to update its working copy).

          ++

          If you don’t want to specify ssh://hg@hg.python.org/cpython every time you pull ++or push, you should add to the .hg/hgrc files of the clones:

          ++
          [paths]
++default = ssh://hg@hg.python.org/cpython
++
          ++
          ++

          In order to apply a patch, commit, and merge it on all the branches, you can do ++as follow:

          ++
          $ cd 2.7
++$ hg pull
++$ hg up
++$ hg import --no-c http://bugs.python.org/url/to/the/patch.diff
++$ # review, run tests, run `make patchcheck`
++$ hg ci -m '#12345: fix some issue.'
++$ # switch to 3.4 and port the changeset using `hg graft`
++$ cd ../3.4
++$ hg up
++$ hg graft 2.7
++$ # switch to 3.x, merge, commit, and push everything
++$ cd ../3.x
++$ hg up
++$ hg merge 3.4
++$ hg ci -m '#12345: merge with 3.4.'
++$ hg push
++
          ++
          ++

          Unless noted otherwise, the rest of the page will assume you are using the ++multiple clone approach, and explain in more detail these basic steps.

          ++

          For more advanced explanations about null merges, ++heads merges, merge conflicts, etc., see the FAQs for core developers.

          ++
          ++
          ++
          ++

          17.3. Active branches

          ++

          If you do hg branches you will see a list of branches. ++default is the in-development branch, and is the only branch that receives ++new features. The other branches only receive bug fixes or security fixes. ++Depending on what you are committing (feature, bug fix, or security fix), you ++should commit to the oldest branch applicable, and then forward-port until the ++in-development branch.

          ++
          ++
          ++

          17.4. Merging order

          ++

          There are two separate lines of development: one for Python 2 (the 2.x ++branches) and one for Python 3 (the 3.x branches and default). ++You should never merge between the two major versions (2.x and 3.x) — ++only between minor versions (e.g. 3.x->3.y). The merge always happens from ++the oldest applicable branch to the newest branch within the same major ++Python version.

          ++
          ++
          ++

          17.5. Merging between different branches (within the same major version)

          ++

          Assume that Python 3.5 is the current in-development version of Python and that ++you have a patch that should also be applied to Python 3.4. To properly port ++the patch to both versions of Python, you should first apply the patch to ++Python 3.4:

          ++
          cd 3.4
++hg import --no-commit patch.diff
++# Compile; run the test suite
++hg ci -m '#12345: fix some issue.'
++
          ++
          ++

          Then you can switch to the 3.5 clone, merge, run the tests and commit:

          ++
          cd ../3.5
++hg merge 3.4
++# Fix any conflicts (e.g. ``hg revert -r default Misc/NEWS``); compile; run the test suite
++hg ci -m '#12345: merge with 3.4.'
++
          ++
          ++

          If you are not using the share extension, you will need to use ++hg pull ../3.4 before being able to merge.

          ++
          ++

          Note

          ++

          Even when porting an already committed patch, you should still check the ++test suite runs successfully before committing the patch to another branch. ++Subtle differences between two branches sometimes make a patch bogus if ++ported without any modifications.

          ++
          ++
          ++
          ++

          17.6. Porting changesets between the two major Python versions (2.x and 3.x)

          ++

          Assume you just committed something on 2.7, and want to port it to 3.4. ++You can use hg graft as follow:

          ++
          cd ../3.4
++hg graft 2.7
++
          ++
          ++

          This will port the latest changeset committed in the 2.7 clone to the 3.4 clone. ++hg graft always commits automatically, except in case of conflicts, when ++you have to resolve them and run hg graft --continue afterwards. ++Instead of the branch name you can also specify a changeset id, and you can ++also graft changesets from 3.x to 2.7.

          ++

          On older version of Mercurial where hg graft is not available, you can use:

          ++
          cd ../3.4
++hg export 2.7 | hg import -
++
          ++
          ++

          The result will be the same, but in case of conflict this will create .rej ++files rather than using Mercurial merge capabilities.

          ++

          A third option is to apply manually the patch on 3.4. This is convenient ++when there are too many differences with 2.7 or when there is already a ++specific patch for 3.4.

          ++
          ++

          Warning

          ++

          Never use hg merge to port changes between 2.x and 3.x (or vice versa).

          ++
          ++
          ++
          ++

          17.7. Long-term development of features

          ++

          If you want to work on a feature long-term (perhaps you’re implementing a ++PEP), you will probably want to publish your work in a dedicated repository. ++The following instructions will help you do so on hg.python.org‘s infrastructure without requiring a lot of upload ++bandwidth.

          ++

          Go to the main repository’s Web page (http://hg.python.org/cpython/); there ++you find a button labelled “server-side clone”, which you can click on to ++display a Web form. Enter the relative path of the repository you want to ++create on the server, for example features/mywork; and press the button. ++A new repository gets created on the server with all the changesets of the ++original repository (it will seem very fast; this is normal).

          ++

          You can now do a local clone of this repository on your disk:

          ++
          $ hg clone ssh://hg@hg.python.org/features/mywork
++$ cd mywork
++
          ++
          ++

          It is recommended that you create a new named branch for your work, so as ++to easily track changes. That named branch will exist in your feature ++repository, but not in the main repository:

          ++
          $ hg branch mywork
++$ hg commit -m "Creating branch mywork"
++$ hg push --new-branch
++
          ++
          ++

          You can now work on your feature, commit changes as you will, and push them ++when desired:

          ++
          $ hg push
++
          ++
          ++

          When you push them, they will land in the public repository at ++ssh://hg@hg.python.org/features/mywork (or ++http://hg.python.org/features/mywork for the read-only URL). Other ++people can clone the public repository and work on the code too.

          ++

          When you want to synchronize with CPython’s upstream changes, you can pull ++from the main repository, either from its remote URL:

          ++
          $ hg pull http://hg.python.org/cpython
++
          ++
          ++

          or from a local clone that you may have on your disk (which is of course ++faster):

          ++
          $ hg pull ../cpython
++
          ++
          ++

          and merge all new changes from branch default to branch mywork:

          ++
          $ hg branch
++mywork
++$ hg merge default
++
          ++
          ++

          Rather than using a clone on python.org (which isn’t particularly useful ++for collaboration with folks that don’t already have CPython commit rights), ++Bitbucket also maintain an up to date clone of the main cpython ++repository that can be used as the basis for a new clone or patch queue.

          ++
          ++

          17.7.1. Uploading a patch for review

          ++

          In this scheme, your work will probably consist of many commits (some of ++them merges). If you want to upload a patch for review somewhere, you need ++a single aggregate patch. This is where having a dedicated named branch ++mywork gets handy.

          ++

          First ensure that you have pulled and merged all changes from the main ++repository, as explained above. Then, assuming your currently checked ++out branch is still mywork, simply do:

          ++
          $ hg diff -r default > mywork.patch
++
          ++
          ++

          This will write to mywork.patch all the changes between default and ++mywork.

          ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          15. Developer Log

          ++

          Next topic

          ++

          18. Development Cycle

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/communication.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/communication.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,173 @@ ++ ++ ++ ++ ++ ++ ++ ++ 13. Following Python’s Development — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          13. Following Python’s Development

          ++

          Python’s development is communicated through a myriad of ways, mostly through ++mailing lists, but also other forms.

          ++
          ++

          13.1. Mailing Lists

          ++

          The primary mailing list where discussions about Python’s development occur is ++python-dev. The list is open to the public and is subscribed to by all core ++developers plus many people simply interested in following Python’s ++development. Discussion is focused on issues related to Python’s development, ++such as how to handle a specific issue, a PEP, etc. Ideas about new ++functionality should not start here and instead should be sent to ++python-ideas. Technical support questions should also not be asked here and ++instead should go to python-list or python-help.

          ++

          The python-committers mailing list is a private mailing list for core ++developers (the archives are publicly available). ++If something only affects core developers (e.g., the ++tree is frozen for commits, etc.), it is discussed here instead of python-dev ++to keep traffic down on the latter.

          ++

          Python-ideas is a mailing list open to the public to discuss ideas on changing ++Python. If a new idea does not start here (or python-list, discussed below), ++it will get redirected here.

          ++

          Python-checkins sends out an email for every commit to Python’s various ++repositories from http://hg.python.org. All core developers ++subscribe to this list and are known to reply to these emails to make comments ++about various issues they catch in the commit. Replies get redirected to ++python-dev.

          ++

          There are two mailing lists related to issues on the issue tracker. If you ++only want an email for when a new issue is open, subscribe to ++new-bugs-announce. If you would rather receive an email for all changes made ++to any issue, subscribe to python-bugs-list.

          ++

          Sometimes people post new ideas to python-list to gather community opinion before ++heading to python-ideas. The list is also sometimes known as comp.lang.python, ++the name of the newsgroup is mirrors (it is also known by the abbreviation ++c.l.py).

          ++

          A complete list of Python mailing lists can be found at http://mail.python.org. ++Most lists are also mirrored at http://news.gmane.org/ and can be read and ++posted to in various ways, including via web browsers, NNTP newsreaders, and ++RSS feed readers.

          ++
          ++
          ++

          13.2. IRC

          ++

          Some core developers enjoy spending time on IRC discussing various issues ++regarding Python’s development in the #python-dev channel on ++irc.freenode.net. This is not a place to ask for help with Python, but to ++discuss issues related to Python’s own development. You can use freenode’s ++Web interface if you don’t have an IRC ++client.

          ++
          ++
          ++

          13.3. Blogs

          ++

          Several core developers are active bloggers and discuss Python’s development ++that way. You can find their blogs (and various other developers who use Python) ++at http://planet.python.org/.

          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          12. Triaging an Issue

          ++

          Next topic

          ++

          14. How to Become a Core Developer

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/compiler.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/compiler.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,664 @@ ++ ++ ++ ++ ++ ++ ++ ++ 26. Design of CPython’s Compiler — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          26. Design of CPython’s Compiler

          ++
          ++

          26.1. Abstract

          ++

          Historically (through 2.4), compilation from source code to bytecode ++involved two steps:

          ++
            ++
          1. Parse the source code into a parse tree (Parser/pgen.c)
            2. ++
          2. Emit bytecode based on the parse tree (Python/compile.c)
            3. ++
          ++

          Historically, this is not how a standard compiler works. The usual ++steps for compilation are:

          ++
            ++
          1. Parse source code into a parse tree (Parser/pgen.c)
            2. ++
          2. Transform parse tree into an Abstract Syntax Tree (Python/ast.c)
            3. ++
          3. Transform AST into a Control Flow Graph (Python/compile.c)
            4. ++
          4. Emit bytecode based on the Control Flow Graph (Python/compile.c)
            5. ++
          ++

          Starting with Python 2.5, the above steps are now used. This change ++was done to simplify compilation by breaking it into three steps. ++The purpose of this document is to outline how the latter three steps ++of the process work.

          ++

          This document does not touch on how parsing works beyond what is needed ++to explain what is needed for compilation. It is also not exhaustive ++in terms of the how the entire system works. You will most likely need ++to read some source to have an exact understanding of all details.

          ++
          ++
          ++

          26.2. Parse Trees

          ++

          Python’s parser is an LL(1) parser mostly based off of the ++implementation laid out in the Dragon Book [Aho86].

          ++

          The grammar file for Python can be found in Grammar/Grammar with the ++numeric value of grammar rules are stored in Include/graminit.h. The ++numeric values for types of tokens (literal tokens, such as :, ++numbers, etc.) are kept in Include/token.h). The parse tree made up of ++node * structs (as defined in Include/node.h).

          ++

          Querying data from the node structs can be done with the following ++macros (which are all defined in Include/node.h):

          ++
          ++
          CHILD(node *, int)
          ++
          Returns the nth child of the node using zero-offset indexing
          ++
          RCHILD(node *, int)
          ++
          Returns the nth child of the node from the right side; use ++negative numbers!
          ++
          NCH(node *)
          ++
          Number of children the node has
          ++
          STR(node *)
          ++
          String representation of the node; e.g., will return : for a ++COLON token
          ++
          TYPE(node *)
          ++
          The type of node as specified in Include/graminit.h
          ++
          REQ(node *, TYPE)
          ++
          Assert that the node is the type that is expected
          ++
          LINENO(node *)
          ++
          retrieve the line number of the source code that led to the ++creation of the parse rule; defined in Python/ast.c
          ++
          ++

          To tie all of this example, consider the rule for ‘while’:

          ++
          while_stmt: 'while' test ':' suite ['else' ':' suite]
++
          ++
          ++

          The node representing this will have TYPE(node) == while_stmt and ++the number of children can be 4 or 7 depending on if there is an ‘else’ ++statement. To access what should be the first ‘:’ and require it be an ++actual ‘:’ token, (REQ(CHILD(node, 2), COLON)`.

          ++
          ++
          ++

          26.3. Abstract Syntax Trees (AST)

          ++

          The abstract syntax tree (AST) is a high-level representation of the ++program structure without the necessity of containing the source code; ++it can be thought of as an abstract representation of the source code. The ++specification of the AST nodes is specified using the Zephyr Abstract ++Syntax Definition Language (ASDL) [Wang97].

          ++

          The definition of the AST nodes for Python is found in the file ++Parser/Python.asdl .

          ++

          Each AST node (representing statements, expressions, and several ++specialized types, like list comprehensions and exception handlers) is ++defined by the ASDL. Most definitions in the AST correspond to a ++particular source construct, such as an ‘if’ statement or an attribute ++lookup. The definition is independent of its realization in any ++particular programming language.

          ++

          The following fragment of the Python ASDL construct demonstrates the ++approach and syntax:

          ++
          module Python
++{
++      stmt = FunctionDef(identifier name, arguments args, stmt* body,
++                          expr* decorators)
++            | Return(expr? value) | Yield(expr value)
++            attributes (int lineno)
++}
++
          ++
          ++

          The preceding example describes three different kinds of statements; ++function definitions, return statements, and yield statements. All ++three kinds are considered of type stmt as shown by ‘|’ separating the ++various kinds. They all take arguments of various kinds and amounts.

          ++

          Modifiers on the argument type specify the number of values needed; ‘?’ ++means it is optional, ‘*’ means 0 or more, no modifier means only one ++value for the argument and it is required. FunctionDef, for instance, ++takes an identifier for the name, ‘arguments’ for args, zero or more ++stmt arguments for ‘body’, and zero or more expr arguments for ++‘decorators’.

          ++

          Do notice that something like ‘arguments’, which is a node type, is ++represented as a single AST node and not as a sequence of nodes as with ++stmt as one might expect.

          ++

          All three kinds also have an ‘attributes’ argument; this is shown by the ++fact that ‘attributes’ lacks a ‘|’ before it.

          ++

          The statement definitions above generate the following C structure type:

          ++
          typedef struct _stmt *stmt_ty;
++
++struct _stmt {
++      enum { FunctionDef_kind=1, Return_kind=2, Yield_kind=3 } kind;
++      union {
++              struct {
++                      identifier name;
++                      arguments_ty args;
++                      asdl_seq *body;
++              } FunctionDef;
++
++              struct {
++                      expr_ty value;
++              } Return;
++
++              struct {
++                      expr_ty value;
++              } Yield;
++      } v;
++      int lineno;
++ }
++
          ++
          ++

          Also generated are a series of constructor functions that allocate (in ++this case) a stmt_ty struct with the appropriate initialization. The ++‘kind’ field specifies which component of the union is initialized. The ++FunctionDef() constructor function sets ‘kind’ to FunctionDef_kind and ++initializes the ‘name’, ‘args’, ‘body’, and ‘attributes’ fields.

          ++
          ++
          ++

          26.4. Memory Management

          ++

          Before discussing the actual implementation of the compiler, a discussion of ++how memory is handled is in order. To make memory management simple, an arena ++is used. This means that a memory is pooled in a single location for easy ++allocation and removal. What this gives us is the removal of explicit memory ++deallocation. Because memory allocation for all needed memory in the compiler ++registers that memory with the arena, a single call to free the arena is all ++that is needed to completely free all memory used by the compiler.

          ++

          In general, unless you are working on the critical core of the compiler, memory ++management can be completely ignored. But if you are working at either the ++very beginning of the compiler or the end, you need to care about how the arena ++works. All code relating to the arena is in either Include/pyarena.h or ++Python/pyarena.c .

          ++

          PyArena_New() will create a new arena. The returned PyArena structure will ++store pointers to all memory given to it. This does the bookkeeping of what ++memory needs to be freed when the compiler is finished with the memory it used. ++That freeing is done with PyArena_Free(). This needs to only be called in ++strategic areas where the compiler exits.

          ++

          As stated above, in general you should not have to worry about memory ++management when working on the compiler. The technical details have been ++designed to be hidden from you for most cases.

          ++

          The only exception comes about when managing a PyObject. Since the rest ++of Python uses reference counting, there is extra support added ++to the arena to cleanup each PyObject that was allocated. These cases ++are very rare. However, if you’ve allocated a PyObject, you must tell ++the arena about it by calling PyArena_AddPyObject().

          ++
          ++
          ++

          26.5. Parse Tree to AST

          ++

          The AST is generated from the parse tree (see Python/ast.c) using the ++function PyAST_FromNode().

          ++

          The function begins a tree walk of the parse tree, creating various AST ++nodes as it goes along. It does this by allocating all new nodes it ++needs, calling the proper AST node creation functions for any required ++supporting functions, and connecting them as needed.

          ++

          Do realize that there is no automated nor symbolic connection between ++the grammar specification and the nodes in the parse tree. No help is ++directly provided by the parse tree as in yacc.

          ++

          For instance, one must keep track of which node in the parse tree ++one is working with (e.g., if you are working with an ‘if’ statement ++you need to watch out for the ‘:’ token to find the end of the conditional).

          ++

          The functions called to generate AST nodes from the parse tree all have ++the name ast_for_xx where xx is what the grammar rule that the function ++handles (alias_for_import_name is the exception to this). These in turn ++call the constructor functions as defined by the ASDL grammar and ++contained in Python/Python-ast.c (which was generated by ++Parser/asdl_c.py) to create the nodes of the AST. This all leads to a ++sequence of AST nodes stored in asdl_seq structs.

          ++

          Function and macros for creating and using asdl_seq * types as found ++in Python/asdl.c and Include/asdl.h:

          ++
          ++
          asdl_seq_new()
          ++
          Allocate memory for an asdl_seq for the specified length
          ++
          asdl_seq_GET()
          ++
          Get item held at a specific position in an asdl_seq
          ++
          asdl_seq_SET()
          ++
          Set a specific index in an asdl_seq to the specified value
          ++
          asdl_seq_LEN(asdl_seq *)
          ++
          Return the length of an asdl_seq
          ++
          ++

          If you are working with statements, you must also worry about keeping ++track of what line number generated the statement. Currently the line ++number is passed as the last parameter to each stmt_ty function.

          ++
          ++
          ++

          26.6. Control Flow Graphs

          ++

          A control flow graph (often referenced by its acronym, CFG) is a ++directed graph that models the flow of a program using basic blocks that ++contain the intermediate representation (abbreviated “IR”, and in this ++case is Python bytecode) within the blocks. Basic blocks themselves are ++a block of IR that has a single entry point but possibly multiple exit ++points. The single entry point is the key to basic blocks; it all has ++to do with jumps. An entry point is the target of something that ++changes control flow (such as a function call or a jump) while exit ++points are instructions that would change the flow of the program (such ++as jumps and ‘return’ statements). What this means is that a basic ++block is a chunk of code that starts at the entry point and runs to an ++exit point or the end of the block.

          ++

          As an example, consider an ‘if’ statement with an ‘else’ block. The ++guard on the ‘if’ is a basic block which is pointed to by the basic ++block containing the code leading to the ‘if’ statement. The ‘if’ ++statement block contains jumps (which are exit points) to the true body ++of the ‘if’ and the ‘else’ body (which may be NULL), each of which are ++their own basic blocks. Both of those blocks in turn point to the ++basic block representing the code following the entire ‘if’ statement.

          ++

          CFGs are usually one step away from final code output. Code is directly ++generated from the basic blocks (with jump targets adjusted based on the ++output order) by doing a post-order depth-first search on the CFG ++following the edges.

          ++
          ++
          ++

          26.7. AST to CFG to Bytecode

          ++

          With the AST created, the next step is to create the CFG. The first step ++is to convert the AST to Python bytecode without having jump targets ++resolved to specific offsets (this is calculated when the CFG goes to ++final bytecode). Essentially, this transforms the AST into Python ++bytecode with control flow represented by the edges of the CFG.

          ++

          Conversion is done in two passes. The first creates the namespace ++(variables can be classified as local, free/cell for closures, or ++global). With that done, the second pass essentially flattens the CFG ++into a list and calculates jump offsets for final output of bytecode.

          ++

          The conversion process is initiated by a call to the function ++PyAST_Compile() in Python/compile.c . This function does both the ++conversion of the AST to a CFG and ++outputting final bytecode from the CFG. The AST to CFG step is handled ++mostly by two functions called by PyAST_Compile(); PySymtable_Build() and ++compiler_mod() . The former is in Python/symtable.c while the latter is in ++Python/compile.c .

          ++

          PySymtable_Build() begins by entering the starting code block for the ++AST (passed-in) and then calling the proper symtable_visit_xx function ++(with xx being the AST node type). Next, the AST tree is walked with ++the various code blocks that delineate the reach of a local variable ++as blocks are entered and exited using symtable_enter_block() and ++symtable_exit_block(), respectively.

          ++

          Once the symbol table is created, it is time for CFG creation, whose ++code is in Python/compile.c . This is handled by several functions ++that break the task down by various AST node types. The functions are ++all named compiler_visit_xx where xx is the name of the node type (such ++as stmt, expr, etc.). Each function receives a struct compiler * ++and xx_ty where xx is the AST node type. Typically these functions ++consist of a large ‘switch’ statement, branching based on the kind of ++node type passed to it. Simple things are handled inline in the ++‘switch’ statement with more complex transformations farmed out to other ++functions named compiler_xx with xx being a descriptive name of what is ++being handled.

          ++

          When transforming an arbitrary AST node, use the VISIT() macro. ++The appropriate compiler_visit_xx function is called, based on the value ++passed in for <node type> (so VISIT(c, expr, node) calls ++compiler_visit_expr(c, node)). The VISIT_SEQ macro is very similar, ++but is called on AST node sequences (those values that were created as ++arguments to a node that used the ‘*’ modifier). There is also ++VISIT_SLICE() just for handling slices.

          ++

          Emission of bytecode is handled by the following macros:

          ++
          ++
          ADDOP()
          ++
          add a specified opcode
          ++
          ADDOP_I()
          ++
          add an opcode that takes an argument
          ++
          ADDOP_O(struct compiler *c, int op, PyObject *type, PyObject *obj)
          ++
          add an opcode with the proper argument based on the position of the ++specified PyObject in PyObject sequence object, but with no handling of ++mangled names; used for when you ++need to do named lookups of objects such as globals, consts, or ++parameters where name mangling is not possible and the scope of the ++name is known
          ++
          ADDOP_NAME()
          ++
          just like ADDOP_O, but name mangling is also handled; used for ++attribute loading or importing based on name
          ++
          ADDOP_JABS()
          ++
          create an absolute jump to a basic block
          ++
          ADDOP_JREL()
          ++
          create a relative jump to a basic block
          ++
          ++

          Several helper functions that will emit bytecode and are named ++compiler_xx() where xx is what the function helps with (list, boolop, ++etc.). A rather useful one is compiler_nameop(). ++This function looks up the scope of a variable and, based on the ++expression context, emits the proper opcode to load, store, or delete ++the variable.

          ++

          As for handling the line number on which a statement is defined, is ++handled by compiler_visit_stmt() and thus is not a worry.

          ++

          In addition to emitting bytecode based on the AST node, handling the ++creation of basic blocks must be done. Below are the macros and ++functions used for managing basic blocks:

          ++
          ++
          NEW_BLOCK()
          ++
          create block and set it as current
          ++
          NEXT_BLOCK()
          ++
          basically NEW_BLOCK() plus jump from current block
          ++
          compiler_new_block()
          ++
          create a block but don’t use it (used for generating jumps)
          ++
          ++

          Once the CFG is created, it must be flattened and then final emission of ++bytecode occurs. Flattening is handled using a post-order depth-first ++search. Once flattened, jump offsets are backpatched based on the ++flattening and then a PyCodeObject file is created. All of this is ++handled by calling assemble() .

          ++
          ++
          ++

          26.8. Introducing New Bytecode

          ++

          Sometimes a new feature requires a new opcode. But adding new bytecode is ++not as simple as just suddenly introducing new bytecode in the AST -> ++bytecode step of the compiler. Several pieces of code throughout Python depend ++on having correct information about what bytecode exists.

          ++

          First, you must choose a name and a unique identifier number. The official ++list of bytecode can be found in Include/opcode.h . If the opcode is to take ++an argument, it must be given a unique number greater than that assigned to ++HAVE_ARGUMENT (as found in Include/opcode.h).

          ++

          Once the name/number pair ++has been chosen and entered in Include/opcode.h, you must also enter it into ++Lib/opcode.py and Doc/library/dis.rst .

          ++

          With a new bytecode you must also change what is called the magic number for ++.pyc files. The variable MAGIC in Python/import.c contains the number. ++Changing this number will lead to all .pyc files with the old MAGIC ++to be recompiled by the interpreter on import.

          ++

          Finally, you need to introduce the use of the new bytecode. Altering ++Python/compile.c and Python/ceval.c will be the primary places to change. ++But you will also need to change the ‘compiler’ package. The key files ++to do that are Lib/compiler/pyassem.py and Lib/compiler/pycodegen.py .

          ++

          If you make a change here that can affect the output of bytecode that ++is already in existence and you do not change the magic number constantly, make ++sure to delete your old .py(c|o) files! Even though you will end up changing ++the magic number if you change the bytecode, while you are debugging your work ++you will be changing the bytecode output without constantly bumping up the ++magic number. This means you end up with stale .pyc files that will not be ++recreated. Running ++find . -name '*.py[co]' -exec rm -f {} ';' should delete all .pyc files you ++have, forcing new ones to be created and thus allow you test out your new ++bytecode properly.

          ++
          ++
          ++

          26.9. Code Objects

          ++

          The result of PyAST_Compile() is a PyCodeObject which is defined in ++Include/code.h . And with that you now have executable Python bytecode!

          ++

          The code objects (byte code) is executed in Python/ceval.c . This file ++will also need a new case statement for the new opcode in the big switch ++statement in PyEval_EvalFrameEx().

          ++
          ++
          ++

          26.10. Important Files

          ++
            ++

          • Parser/

            ++
            ++
            ++
            Python.asdl
            ++

            ASDL syntax file

            ++
            ++
            asdl.py
            ++

            “An implementation of the Zephyr Abstract Syntax Definition ++Language.” Uses SPARK to parse the ASDL files.

            ++
            ++
            asdl_c.py
            ++

            “Generate C code from an ASDL description.” Generates ++Python/Python-ast.c and Include/Python-ast.h .

            ++
            ++
            spark.py
            ++

            SPARK parser generator

            ++
            ++
            ++
            ++
            • ++

          • Python/

            ++
            ++
            ++
            Python-ast.c
            ++

            Creates C structs corresponding to the ASDL types. Also ++contains code for marshaling AST nodes (core ASDL types have ++marshaling code in asdl.c). “File automatically generated by ++Parser/asdl_c.py”. This file must be committed separately ++after every grammar change is committed since the __version__ ++value is set to the latest grammar change revision number.

            ++
            ++
            asdl.c
            ++

            Contains code to handle the ASDL sequence type. Also has code ++to handle marshalling the core ASDL types, such as number and ++identifier. used by Python-ast.c for marshaling AST nodes.

            ++
            ++
            ast.c
            ++

            Converts Python’s parse tree into the abstract syntax tree.

            ++
            ++
            ceval.c
            ++

            Executes byte code (aka, eval loop).

            ++
            ++
            compile.c
            ++

            Emits bytecode based on the AST.

            ++
            ++
            symtable.c
            ++

            Generates a symbol table from AST.

            ++
            ++
            pyarena.c
            ++

            Implementation of the arena memory manager.

            ++
            ++
            import.c
            ++

            Home of the magic number (named MAGIC) for bytecode versioning

            ++
            ++
            ++
            ++
            • ++

          • Include/

            ++
            ++
            ++
            Python-ast.h
            ++

            Contains the actual definitions of the C structs as generated by ++Python/Python-ast.c . ++“Automatically generated by Parser/asdl_c.py”.

            ++
            ++
            asdl.h
            ++

            Header for the corresponding Python/ast.c .

            ++
            ++
            ast.h
            ++

            Declares PyAST_FromNode() external (from Python/ast.c).

            ++
            ++
            code.h
            ++

            Header file for Objects/codeobject.c; contains definition of ++PyCodeObject.

            ++
            ++
            symtable.h
            ++

            Header for Python/symtable.c . struct symtable and ++PySTEntryObject are defined here.

            ++
            ++
            pyarena.h
            ++

            Header file for the corresponding Python/pyarena.c .

            ++
            ++
            opcode.h
            ++

            Master list of bytecode; if this file is modified you must modify ++several other files accordingly (see “Introducing New Bytecode”)

            ++
            ++
            ++
            ++
            • ++

          • Objects/

            ++
            ++
            ++
            codeobject.c
            ++

            Contains PyCodeObject-related code (originally in ++Python/compile.c).

            ++
            ++
            ++
            ++
            • ++

          • Lib/

            ++
            ++
            ++
            opcode.py
            ++

            One of the files that must be modified if Include/opcode.h is.

            ++
            ++
            ++

            compiler/

            ++
            ++
            ++
            pyassem.py
            ++

            One of the files that must be modified if Include/opcode.h is ++changed.

            ++
            ++
            pycodegen.py
            ++

            One of the files that must be modified if Include/opcode.h is ++changed.

            ++
            ++
            ++
            ++
            ++
            • ++
          ++
          ++ ++
          ++

          26.12. References

          ++
          ++ ++ ++ ++ ++
          [Aho86]Alfred V. Aho, Ravi Sethi, Jeffrey D. Ullman. ++Compilers: Principles, Techniques, and Tools, ++http://www.amazon.com/exec/obidos/tg/detail/-/0201100886/104-0162389-6419108
          ++ ++ ++ ++ ++ ++
          [Wang97]Daniel C. Wang, Andrew W. Appel, Jeff L. Korn, and Chris ++S. Serra. The Zephyr Abstract Syntax Description Language. ++In Proceedings of the Conference on Domain-Specific Languages, pp. ++213–227, 1997.
          ++ ++ ++ ++ ++ ++
          [1]Skip Montanaro’s Peephole Optimizer Paper ++(http://www.python.org/workshops/1998-11/proceedings/papers/montanaro/montanaro.html)
          ++ ++ ++ ++ ++ ++
          [2]Bytecodehacks Project ++(http://bytecodehacks.sourceforge.net/bch-docs/bch/index.html)
          ++ ++ ++ ++ ++ ++
          [3]CALL_ATTR opcode ++(http://www.python.org/sf/709744)
          ++ ++ ++ ++ ++ ++ ++ ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          25. Changing CPython’s Grammar

          ++

          Next topic

          ++

          27. Coverity Scan

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++ ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/coredev.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/coredev.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,244 @@ ++ ++ ++ ++ ++ ++ ++ ++ 14. How to Become a Core Developer — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          14. How to Become a Core Developer

          ++
          ++

          14.1. What it Takes

          ++

          When you have consistently contributed patches which meet quality standards ++without requiring extensive rewrites prior to being committed, ++you may qualify for ++commit privileges and become a core developer of Python. You must also work ++well with other core developers (and people in general) as you become an ++ambassador for the Python project.

          ++

          Typically a core developer will offer you the chance to gain commit privilege. ++The person making the offer will become your mentor and watch your commits for ++a while to make sure you understand the development process. If other core ++developers agree that you should gain commit privileges you are then extended ++an official offer.

          ++

          You may request commit privileges yourself, but do not be surprised if your ++request is turned down. Do not take this personally! It simply means that other ++core developers think you need more time contributing patches before you are ++able to commit them without supervision.

          ++

          A complete list of core developer usernames can be found at ++http://hg.python.org/committers.txt. Developer Log lists when and why ++someone received commit privileges.

          ++
          ++
          ++

          14.2. Gaining Commit Privileges

          ++

          When you have been extended an official offer to become a Python core ++developer, there are several things you must do.

          ++
          ++

          14.2.1. Mailing Lists

          ++

          You are expected to subscribe to python-committers, python-dev, ++python-checkins, and one of new-bugs-announce or python-bugs-list. See ++Following Python’s Development for links to these mailing lists.

          ++
          ++
          ++

          14.2.2. Issue Tracker

          ++

          If you did not gain the Developer role in the issue tracker before gaining ++commit privileges, please say so. This will allow issues to be assigned to you. ++A tracker admin should also flip your “is committer” bit in the tracker’s ++account screen.

          ++

          It is expected that on the issue tracker you have a username in the form of ++“first_name.last_name”. If your initial issue tracker username is not of this ++form, please change it. This is so that it is easier to assign issues to the ++right person.

          ++
          ++
          ++

          14.2.3. SSH

          ++

          You need to generate an SSH 2 RSA key to be able to commit code. You may have ++multiple keys if you wish (e.g., for work and home). Send your key as an ++attachment in an email to hgaccounts@python.org. Help in generating an SSH key ++can be found in the Python Developer FAQ.

          ++

          Your SSH key will be set to a username in the form of “first_name.last_name”. ++This should match your username on the issue tracker.

          ++

          You can verify your commit access by looking at ++http://hg.python.org/committers.txt which lists all core developers by ++username. If you want to practice, there is a test repository where you can freely commit and push any ++changes you like:

          ++
          hg clone ssh://hg@hg.python.org/test/ hgtest
++
          ++
          ++

          An entry in the Developer Log should also be entered for you. ++Typically the person who sponsored your application to become a core developer ++makes sure an entry is created for you.

          ++
          ++
          ++

          14.2.4. Sign a Contributor Agreement

          ++

          Submitting a contributor form for Python licenses any code you contribute to ++the Python Software Foundation. While you retain the copyright, giving the PSF ++the ability to license your code means it can be put under the PSF license so ++it can be legally distributed with Python.

          ++

          This is a very important step! Hopefully you have already submitted a ++contributor agreement if you have been submitting patches. But if you have not ++done this yet, it is best to do this ASAP, probably before you even do your ++first commit so as to not forget.

          ++
          ++
          ++

          14.2.5. Read/Write Checkout

          ++

          With your commit privileges working and your contributor form submitted, you ++can now get a read/write checkout of the code. URLs for read/write checkouts ++are different than those for read-only checkouts as SSH is used instead of ++HTTP.

          ++

          You can clone the repository (which contains all active branches) with:

          ++
          hg clone ssh://hg@hg.python.org/cpython
++
          ++
          ++

          The default branch in that repository is the current development branch. ++You can of course switch your working copy to one of the maintenance branches, ++for example:

          ++
          hg update 2.7
++
          ++
          ++
          ++
          ++
          ++

          14.3. Responsibilities

          ++

          As a core developer, there are certain things that are expected of you.

          ++

          First and foremost, be a good person. This might sound melodramatic, but you ++are now a member of the Python project and thus represent the project and your ++fellow core developers whenever you discuss Python with anyone. We have a ++reputation for being a very nice group of people and we would like to keep it ++that way.

          ++

          Second, please be prompt in responding to questions. We are all volunteers so ++what little free time one can dedicate to Python should be spent being ++productive. If you have been asked to respond to an issue or answer a question ++and you put it off it ends up stalling other people’s work. It is completely ++acceptable to say you are too busy, but you need to say that instead of ++stringing people along. This obviously applies to anything you do on the issue ++tracker as well.

          ++

          Third, please list what areas you want to be considered an expert in the ++Experts Index. This allows triagers to direct issues to you which involve ++an area you are an expert in. But, ++as stated in the second point above, if you do not have the time to answer ++questions promptly then please remove yourself as needed from the file so that ++you will not be bothered in the future. Once again, we all understand how life ++gets in the way, so no one will be insulted if you remove yourself from the ++list.

          ++

          And finally, enjoy yourself! Contributing to open source software should be fun ++(overall). If you find yourself no longer enjoying the work then either take a ++break or figure out what you need to do to make it enjoyable again.

          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          13. Following Python’s Development

          ++

          Next topic

          ++

          15. Developer Log

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/coverage.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/coverage.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,345 @@ ++ ++ ++ ++ ++ ++ ++ ++ 6. Increase Test Coverage — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          6. Increase Test Coverage

          ++

          Python development follows a practice that all semantic changes and additions ++to the language and stdlib are accompanied by ++appropriate unit tests. Unfortunately Python was in existence for a long time ++before the practice came into effect. This has left chunks of the stdlib ++untested which is not a desirable situation to be in.

          ++

          A good, easy way to become acquainted with Python’s code and to help out is to ++help increase the test coverage for Python’s stdlib. Ideally we would like to ++have 100% coverage, but any increase is a good one. Do realize, though, that ++getting 100% coverage is not always possible. There could be platform-specific ++code that simply will not execute for you, errors in the output, etc. You can ++use your judgement as to what should and should not be covered, but being ++conservative and assuming something should be covered is generally a good rule ++to follow.

          ++

          Choosing what module you want to increase test coverage for can be done in a ++couple of ways. ++A third-party website at http://coverage.livinglogic.de/ provides an ++overall view of how good coverage is for various modules (you will want to ++focus on those in the Lib directory as those are the pure Python modules ++from Python’s stdlib, and thus easier to work with than the C extension ++modules). But since this is a third-party site we cannot promise that it will ++always be accessible or have useful information (i.e., be working properly).

          ++

          Another is to follow the examples below and simply see what ++coverage your favorite module has. This is “stabbing in the dark”, though, and ++so it might take some time to find a module that needs coverage help.

          ++

          Finally, you can simply run the entire test suite yourself with coverage turned ++on and see what modules need help. This has the drawback of running the entire ++test suite under coverage measuring which takes some time to complete, but you ++will have an accurate, up-to-date notion of what modules need the most work.

          ++

          Do make sure, though, that for any module you do decide to work on that you run ++coverage for just that module. This will make sure you know how good the ++explicit coverage of the module is from its own set of tests instead of from ++implicit testing by other code that happens to use the module.

          ++
          ++

          6.1. Common Gotchas

          ++

          Please realize that coverage reports on modules already imported before coverage ++data starts to be recorded will be wrong. Typically you can tell a module falls ++into this category by the coverage report saying that global statements that ++would obviously be executed upon import have gone unexecuted while local ++statements have been covered. In these instances you can ignore the global ++statement coverage and simply focus on the local statement coverage.

          ++

          When writing new tests to increase coverage, do take note of the style of tests ++already provided for a module (e.g., whitebox, blackbox, etc.). As ++some modules are primarily maintained by a single core developer they may have ++a specific preference as to what kind of test is used (e.g., whitebox) and ++prefer that other types of tests not be used (e.g., blackbox). When in doubt, ++stick with whitebox testing in order to properly exercise the code.

          ++
          ++
          ++

          6.2. Measuring Coverage

          ++

          It should be noted that a quirk of running coverage over Python’s own stdlib is ++that certain modules are imported as part of interpreter startup. Those modules ++required by Python itself will not be viewed as executed by the coverage tools ++and thus look like they have very poor coverage (e.g., the stat ++module). In these instances the module will appear to not have any coverage of ++global statements but will have proper coverage of local statements (e.g., ++function definitions will be not be traced, but the function bodies will). ++Calculating the coverage of modules in this situation will simply require ++manually looking at what local statements were not executed.

          ++
          ++

          6.2.1. Using coverage.py

          ++

          One of the most popular third-party coverage tools is coverage.py which ++provides very nice HTML output along with advanced features such as ++branch coverage. If you prefer to stay with tools only ++provided by the stdlib then you can by using test.regrtest.

          ++

          Because the in-development version of Python is bleeding-edge, it is possible ++that the latest release version of coverage.py will not work. In that case you ++should try using the in-development of coverage.py to see if it has been ++updated as needed. To do this you should clone/check out the development version ++of coverage.py:

          ++
          hg clone https://bitbucket.org/ned/coveragepy
++
          ++
          ++

          Another option is to use an installed copy of coverage.py if you already have an ++installed copy. But if you do not already have it installed then it is preferred ++you use a clone of coverage.py for gathering coverage results.

          ++

          If you are using a clone of coverage.py, the following should work (substitute ++COVERAGEDIR with the directory where your clone exists, e.g. ++../coveragepy):

          ++
          ./python COVERAGEDIR
++
          ++
          ++

          Coverage.py will print out a little bit of helper text verifying that ++everything is working. If you are using an installed copy, you can do the ++following instead:

          ++
          ./python -m coverage
++
          ++
          ++

          The rest of the examples on how to use coverage.py will assume you are using a ++cloned copy, but you can substitute the above and all instructions should still ++be valid.

          ++

          To run the test suite under coverage.py, do the following:

          ++
          ./python COVERAGEDIR run --pylib Lib/test/regrtest.py
++
          ++
          ++

          To run only a single test, specify the module/package being tested ++in the --source flag (so as to prune the coverage reporting to only the ++module/package you are interested in) and then append the name of the test you ++wish to run to the command:

          ++
          ./python COVERAGEDIR run --pylib --source=abc Lib/test/regrtest.py test_abc
++
          ++
          ++

          To see the results of the coverage run, you can view a text-based report with:

          ++
          ./python COVERAGEDIR report
++
          ++
          ++

          You can use the --show-missing flag to get a list of lines that were not ++executed:

          ++
          ./python COVERAGEDIR report --show-missing
++
          ++
          ++

          But one of the strengths of coverage.py is its HTML-based reports which let ++you visually see what lines of code were not tested:

          ++
          ./python COVERAGEDIR html -i --include=`pwd`/Lib/* --omit="Lib/test/*,Lib/*/tests/*"
++
          ++
          ++

          This will generate an HTML report in a directory named htmlcov which ++ignores any errors that may arise and ignores modules for which test coverage is ++unimportant (e.g. tests, temp files, etc.). You can then open the ++htmlcov/index.html file in a web browser to view the coverage results along ++with pages that visibly show what lines of code were or were not executed.

          ++
          ++

          6.2.1.1. Branch Coverage

          ++

          For the truly daring, you can use another powerful feature of coverage.py: ++branch coverage. Testing every possible branch path through code, while a great ++goal to strive for, is a secondary goal to getting 100% line ++coverage for the entire stdlib (for now).

          ++

          If you decide you want to try to improve branch coverage, simply add the ++--branch flag to your coverage run:

          ++
          ./python COVERAGEDIR run --pylib --branch <arguments to run test(s)>
++
          ++
          ++

          This will lead to the report stating not only what lines were not covered, but ++also what branch paths were not executed.

          ++
          ++
          ++

          6.2.1.2. Coverage Results For Modules Imported Early On

          ++

          For the truly truly daring, you can use a hack to get coverage.py to include ++coverage for modules that are imported early on during CPython’s startup (e.g. ++the encodings module). Do not worry if you can’t get this to work or it doesn’t ++make any sense; it’s entirely optional and only important for a small number of ++modules.

          ++

          If you still choose to try this, the first step is to build coverage.py’s C ++extension code. Assuming that coverage.py’s clone is at COVERAGEDIR and ++your clone of CPython is at CPYTHONDIR, you execute the following in your ++coverage.py clone:

          ++
          CPPFLAGS="-I CPYTHONDIR -I CPYTHONDIR/Include" CPYTHONDIR/python setup.py build_ext --inplace
++
          ++
          ++

          This will build coverage.py’s C extension code in-place, allowing the previous ++instructions on how to gather coverage to continue to work.

          ++

          To get coverage.py to be able to gather the most accurate coverage data on as ++many modules as possible ++with a HORRIBLE HACK that you should NEVER use in your own code, run the ++following from your CPython clone:

          ++
          PYTHONPATH=COVERAGEDIR/coverage/fullcoverage ./python COVERAGEDIR run --pylib Lib/test/regrtest.py
++
          ++
          ++

          This will give you the most complete coverage possible for CPython’s standard ++library.

          ++
          ++
          ++
          ++

          6.2.2. Using test.regrtest

          ++

          If you prefer to rely solely on the stdlib to generate coverage data, you can ++do so by passing the appropriate flags to test.regrtest (along with ++any other flags you want to):

          ++
          ./python -m test --coverage -D `pwd`/coverage_data <test arguments>
++
          ++
          ++

          Do note the argument to -D; if you do not specify an absolute path to where ++you want the coverage data to end up it will go somewhere you don’t expect.

          ++
          ++

          Note

          ++

          If you are running coverage over the entire test suite, make sure to ++add -x test_importlib test_runpy test_trace to exclude those tests as ++they trigger exceptions during coverage; see ++http://bugs.python.org/issue10541 and http://bugs.python.org/issue10991.

          ++
          ++

          Once the tests are done you will find the directory you specified contains ++files for each executed module along with which lines were executed how many ++times.

          ++
          ++
          ++
          ++

          6.3. Filing the Issue

          ++

          Once you have increased coverage, you need to ++generate the patch and submit it to the issue tracker. On the ++issue set the “Components” to “Test” and “Versions” to the version of Python you ++worked on (i.e., the in-development version).

          ++
          ++
          ++

          6.4. Measuring coverage of C code with gcov and lcov

          ++

          It’s also possible to measure the function, line and branch coverage of ++Python’s C code. Right now only GCC with gcov is supported. In order to ++create an instrumented build of Python with gcov, run:

          ++
          make coverage
++
          ++
          ++

          Then run some code and gather coverage data with the gcov command. In ++order to create a HTML report you can install lcov. The command:

          ++
          make coverage-lcov
++
          ++
          ++

          assembles coverage data, removes 3rd party and system libaries and finally ++creates a report. You can skip both steps and just run:

          ++
          make coverage-report
++
          ++
          ++

          if you like to generate a coverage report for Python’s stdlib tests. It takes ++about 20 to 30 minutes on a modern computer.

          ++
          ++

          Note

          ++

          Multiple test jobs may not work properly. C coverage reporting has only ++been tested with a single test process.

          ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          5. Running & Writing Tests

          ++

          Next topic

          ++

          7. Helping with Documentation

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/coverity.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/coverity.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,249 @@ ++ ++ ++ ++ ++ ++ ++ ++ 27. Coverity Scan — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          27. Coverity Scan

          ++

          Coverity Scan is a free service for static code analysis of Open Source ++projects. It is based on Coverity’s commercial product and is able to analyze ++C, C++ and Java code.

          ++

          Coverity’s static code analysis doesn’t run the code. Instead of that it uses ++abstract interpretation to gain information about the code’s control flow and ++data flow. It’s able to follow all possible code paths that a program may ++take. For example the analyzer understands that malloc() returns a memory ++that must be freed with free() later. It follows all branches and function ++calls to see if all possible combinations free the memory. The analyzer is ++able to detect all sorts of issues like resource leaks (memory, file ++descriptors), NULL dereferencing, use after free, unchecked return values, ++dead code, buffer overflows, integer overflows, uninitialized variables, and ++many more.

          ++
          ++

          27.1. Access to analysis reports

          ++

          The results are available on the Coverity Scan website. In order to ++access the results you have to create an account yourself. Then go to ++Projects using Scan and add yourself to the Python project. New members must ++be approved by an admin (see Contact).

          ++

          Access is restricted to Python core developers only. Other individuals may be ++given access at our own discretion, too. Every now and then Coverity detects a ++critical issue in Python’s code – new analyzers may even find new bugs in ++mature code. We don’t want to disclose issues prematurely.

          ++
          ++
          ++

          27.2. Building and uploading analysis

          ++

          The process is automated. A script runs hg pull, hg update, ++cov-build and uploads the latest analysis to Coverity. Since Coverity has ++limited the maximum number of builds per week Python is analyzed every second ++day. The build runs on a dedicated virtual machine on PSF’s infrastructure at ++OSU Open Source Labs. The process is maintained by Christian Heimes (see ++Contact). At present only the tip is analyzed with the 64bit Linux tools.

          ++
          ++
          ++

          27.3. Known limitations

          ++

          Some aspects of Python’s C code are not yet understood by Coverity.

          ++
          ++

          27.3.1. False positives

          ++
          ++
          Py_BuildValue("N", PyObject*)
          ++
          Coverity doesn’t understand that N format char passes the object along ++without touching its reference count. On this ground the analyzer detects ++a resource leak. CID 719685
          ++
          PyLong_FromLong() for negative values
          ++
          Coverity claims that PyLong_FromLong() and other PyLong_From*() ++functions cannot handle a negative value because the value might be used as ++an array index in get_small_int(). CID 486783
          ++
          PyLong_FromLong() for n in [-5 ... +255]
          ++
          For integers in the range of Python’s small int cache the PyLong_From*() ++function can never fail and never returns NULL. CID 1058291
          ++
          PyArg_ParseTupleAndKeywords(args, kwargs, "s#", &data, &length)
          ++
          Some functions use the format char combination such as s#, u# or ++z# to get data and length of a character array. Coverity doesn’t ++recognize the relation between data and length. Sometimes it detects a buffer ++overflow if data is written to a fixed size buffer although ++length <= sizeof(buffer). CID 486613
          ++
          path_converter() dereferencing after null check
          ++
          The path_converter() function in posixmodule.c makes sure that ++either path_t.narrow or path_t.wide is filled unless ++path_t.nullable is explicitly enabled. CID 719648
          ++
          ++
          ++
          ++

          27.3.2. Intentionally

          ++
          ++
          Py_VA_COPY()
          ++
          Python is written in C89 (ANSI C), therefore it can’t use C99 features such ++as va_copy(). Python’s own variant Py_VA_COPY() uses memcpy() ++to make a copy of a va_list variable. Coverity detects two issues in ++this approach: “Passing argument “lva” of type “va_list” and sizeof(va_list) ++to function memcpy() is suspicious.” CID 486405 and “Uninitialized pointer ++read” CID 486630.
          ++
          ++
          ++
          ++
          ++

          27.4. Modeling

          ++

          Modeling is explained in the Coverity Help Center which is available in ++the help menu of Coverity Connect. coverity_model.c contains a copy of ++Python’s modeling file for Coverity. Please keep the copy in sync with the ++model file in Analysis Settings of Coverity Scan.

          ++
          ++
          ++

          27.5. Workflow

          ++
          ++

          27.5.1. False positive and intentional issues

          ++

          If the problem is listed under Known limitations then please set the ++classification to either “False positive” or “Intentional”, the action to ++“Ignore”, owner to your own account and add a comment why the issue ++is considered false positive or intentional.

          ++

          If you think it’s a new false positive or intentional then please contact an ++admin. The first step should be an updated to Python’s Modeling file.

          ++
          ++
          ++

          27.5.2. Positive issues

          ++

          You should always create an issue unless it’s really a trivial case. Please ++add the full url to the ticket under Ext. Reference and add the CID ++(Coverity ID) to both the ticket and the checkin message. It makes it much ++easier to understand the relation between tickets, fixes and Coverity issues.

          ++
          ++
          ++
          ++

          27.6. Contact

          ++

          Please include both Brett and Christian in any mail regarding Coverity. Mails ++to Coverity should go through Brett or Christian, too.

          ++
          ++
          Christian Heimes <christian (at) python (dot) org>
          ++
          admin, maintainer of build machine, intermediary between Python and Coverity
          ++
          Brett Cannon <brett (at) python (dot) org>
          ++
          co-admin
          ++
          Dakshesh Vyas <scan-admin@coverity.com>
          ++
          Technical Manager - Coverity Scan
          ++
          ++
          ++

          See also

          ++

          Coverity Scan FAQ

          ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          26. Design of CPython’s Compiler

          ++

          Next topic

          ++

          28. Dynamic Analysis with Clang

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/devcycle.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/devcycle.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,270 @@ ++ ++ ++ ++ ++ ++ ++ ++ 18. Development Cycle — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          18. Development Cycle

          ++

          The responsibilities of a core developer shift based on what kind of branch of ++Python a developer is working on and what stage the branch is in.

          ++

          To clarify terminology, Python uses a major.minor.micro nomenclature ++for production-ready releases. So for Python 3.1.2 final, that is a major ++version of 3, a minor version of 1, and a micro version of 2.

          ++
            ++
          • new major versions are exceptional; they only come when strongly ++incompatible changes are deemed necessary, and are planned very long ++in advance;
            • ++
          • new minor versions are feature releases; they get released roughly ++every 18 months, from the current in-development ++branch;
            • ++
          • new micro versions are bugfix releases; they get released roughly ++every 6 months, although they can come more often if necessary; they are ++prepared in maintenance branches.
            • ++
          ++

          We also publish non-final versions which get an additional qualifier: ++Alpha, Beta, release candidate. These versions ++are aimed at testing by advanced users, not production use.

          ++
          ++

          18.1. Branches

          ++

          There is a branch for each feature version, whether released or not (e.g. ++2.7, 3.5). Development is handled separately for Python 2 and Python 3: ++no merging happens between 2.x and 3.x branches.

          ++

          In each of the 2.x and 3.x realms, the branch for a feature version is always a ++descendant of the previous feature version: for example, the 3.3 branch is a ++descendant of the 3.2 branch.

          ++

          Therefore, each change should be made first in the oldest branch to which it ++applies and forward-ported as appropriate: if a bug must be fixed in both Python ++3.4 and 3.5, first fix it in 3.4 and then merge 3.4 into default ++(which holds the future 3.5).

          ++
          ++

          18.1.1. In-development (main) branch

          ++

          The default branch is the branch for the next feature release; it is ++under active development for all kinds of changes: new features, semantic ++changes, performance improvements, bug fixes. As the name indicates, it ++is the branch checked out by default by Mercurial.

          ++

          Once a Final release (say, 3.3) is made from the in-development branch, a ++new maintenance branch is created to host all bug fixing ++activity for further micro versions (3.3.1, 3.3.2, etc.).

          ++
          ++
          ++

          18.1.2. Maintenance branches

          ++

          A branch for a previous feature release, currently being maintained for bug ++fixes. There are usually two maintenance branches at any given time: one for ++Python 3.x and ++one for Python 2.x. At some point in the future, Python 2.x will be closed ++for bug fixes and there will be only one maintenance branch left.

          ++

          The only changes allowed to occur in a maintenance branch without debate are ++bug fixes. Also, a general rule for maintenance branches is that compatibility ++must not be broken at any point between sibling minor releases (3.3.1, 3.3.2, ++etc.). For both rules, only rare exceptions are accepted and must be ++discussed first.

          ++

          Sometime after a new maintenance branch is created (after a new minor version ++is released), the old maintenance branch on that major version will go into ++security mode, ++usually after one last maintenance release at the discretion of the ++release manager. For example, the 3.2 maintenance branch was put into ++security mode after the 3.2.4 final maintenance release ++following the release of 3.3.0.

          ++
          ++
          ++

          18.1.3. Security branches

          ++

          A branch less than 5 years old but no longer in maintenance mode.

          ++

          The only changes made to a security branch are those fixing issues exploitable ++by attackers such as crashes, privilege escalation and, optionally, other ++issues such as denial of service attacks. Any other changes are ++not considered a security risk and thus not backported to a security branch.

          ++

          Commits to security branches are to be coordinated with the release manager ++for the corresponding feature version, as listed below in the Summary. ++Any release made from a security branch is source-only and done only when actual ++security patches have been applied to the branch.

          ++
          ++
          ++

          18.1.4. Summary

          ++

          There are 5 open branches right now in the Mercurial repository:

          ++
            ++
          • the default branch holds the future 3.5 version and descends from 3.4 ++(future RM: Larry Hastings)
            • ++
          • the 3.4 branch holds bug fixes for future 3.4.x maintenance releases ++and descends from 3.3 (RM: Larry Hastings)
            • ++
          • the 3.3 branch holds security fixes for future 3.3.x maintenance releases ++and descends from 3.2 (RM: Georg Brandl)
            • ++
          • the 3.2 branch holds security fixes for future 3.2.x security releases ++(RM: Georg Brandl)
            • ++
          • the 3.1 branch holds security fixes for future 3.1.x security releases ++(RM: Benjamin Peterson)
            • ++
          • the 2.7 branch holds bug fixes for future 2.7.x maintenance releases and ++descends from 2.6 (RM: Benjamin Peterson)
            • ++
          ++
          ++
          ++
          ++

          18.2. Stages

          ++

          Based on what stage the in-development version of Python ++is in, the responsibilities of a core developer change in regards to commits ++to the VCS.

          ++
          ++

          18.2.1. Pre-alpha

          ++

          The branch is in this stage when no official release has been done since ++the latest final release. There are no special restrictions placed on ++commits, although the usual advice applies (getting patches reviewed, avoiding ++breaking the buildbots).

          ++
          ++
          ++

          18.2.2. Alpha

          ++

          Alpha releases typically serve as a reminder to core developers that they ++need to start getting in changes that change semantics or add something to ++Python as such things should not be added during a Beta. Otherwise no new ++restrictions are in place while in alpha.

          ++
          ++
          ++

          18.2.3. Beta

          ++

          After a first beta release is published, no new features are accepted. Only ++bug fixes can now be committed. This is when core developers should concentrate ++on the task of fixing regressions and other new issues filed by users who have ++downloaded the alpha and beta releases.

          ++

          Being in beta can be viewed much like being in RC but without the extra overhead ++of needing commit reviews.

          ++
          ++
          ++

          18.2.4. Release Candidate (RC)

          ++

          A branch preparing for an RC release can only have bugfixes applied that have ++been reviewed by other core developers. Generally, these issues must be ++severe enough (e.g. crashes) that they deserve fixing before the final release. ++All other issues should be deferred to the next development cycle, since stability ++is the strongest concern at this point.

          ++

          You cannot skip the peer review during an RC, no matter how small! Even if ++it is a simple copy-and-paste change, everything requires peer review from ++a core developer.

          ++
          ++
          ++

          18.2.5. Final

          ++

          When a final release is being cut, only the release manager (RM) can make ++changes to the branch. After the final release is published, the full ++development cycle starts again for the next minor version.

          ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          16. Committing and Pushing Changes

          ++

          Next topic

          ++

          19. Continuous Integration

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/developers.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/developers.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,525 @@ ++ ++ ++ ++ ++ ++ ++ ++ 15. Developer Log — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          15. Developer Log

          ++

          This file is a running log of developers given commit privileges for Python.

          ++

          The purpose is to provide some institutional memory of who was given access ++and why.

          ++

          The first entry starts in April 2005. In keeping with the style of ++Misc/NEWS, newer entries should be added to the top. ++Entries should include the initials of the ++project admin who made the change or granted access.

          ++

          Note, when giving new commit permissions, be sure to get a contributor agreement ++from the committer. See http://www.python.org/psf/contrib/ for details. When ++the agreement is signed, please note it in this log. SSH keys of the committer ++should be sent to hgaccounts@python.org.

          ++

          This file is encoded in UTF-8. If the usual form for a name is not in ++a Latin or extended Latin alphabet, make sure to include an ASCII ++transliteration too.

          ++
          ++

          15.1. Permissions History

          ++
            ++

          • Yury Selivanov was given push privileges on Jan 23 2014 by GFB, for “inspect” ++module and general contributions, on recommendation by Nick Coghlan.

            ++
            • ++

          • Donald Stufft was given push privileges on Aug 14 2013 by BAC, for PEP ++editing, on the recommendation of Nick Coghlan.

            ++
            • ++

          • Ethan Furman was given push privileges on May 11 2013 by BAC, for PEP 435 ++work, on the recommendation of Eli Bendersky.

            ++
            • ++

          • Roger Serwy was given push privileges on Mar 21 2013 by GFB, for IDLE ++contributions, on recommendation by Ned Deily.

            ++
            • ++

          • Serhiy Storchaka was given push privileges on Dec 26 2012 by GFB, for general ++contributions, on recommendation by Trent Nelson.

            ++
            • ++

          • Chris Jerdonek was given push privileges on Sep 24 2012 by GFB, for general ++contributions, on recommendation by Ezio Melotti.

            ++
            • ++

          • Daniel Holth was given push privileges on Sep 9 2012 by GFB, for PEP editing.

            ++
            • ++

          • Eric Snow was given push privileges on Sep 5 2012 by Antoine Pitrou for ++general contributions, on recommendation by Nick Coghlan.

            ++
            • ++

          • Peter Moody was given push privileges on May 20 2012 by Antoine Pitrou for ++authorship and maintenance of the ipaddress module (accepted in PEP 3144 by ++Nick Coghlan).

            ++
            • ++

          • Hynek Schlawack was given push privileges on May 14 2012 by Antoine Pitrou ++for general contributions.

            ++
            • ++

          • Richard Oudkerk was given push privileges on Apr 29 2012 by Antoine Pitrou ++on recommendation by Charles-François Natali and Jesse Noller, for various ++contributions to multiprocessing (and original authorship of ++multiprocessing’s predecessor, the processing package).

            ++
            • ++

          • Andrew Svetlov was given push privileges on Mar 13 2012 by MvL at ++the PyCon sprint.

            ++
            • ++

          • Petri Lehtinen was given push privileges on Oct 22 2011 by GFB, for ++general contributions, on recommendation by Antoine Pitrou.

            ++
            • ++

          • Meador Inge was given push privileges on Sep 19 2011 by GFB, for ++general contributions, on recommendation by Mark Dickinson.

            ++
            • ++

          • Sandro Tosi was given push privileges on Aug 1 2011 by Antoine Pitrou, ++for documentation and other contributions, on recommendation by Ezio ++Melotti, R. David Murray and others.

            ++
            • ++

          • Charles-François Natali was given push privileges on May 19 2011 by Antoine ++Pitrou, for general contributions, on recommendation by Victor Stinner, ++Brian Curtin and others.

            ++
            • ++

          • Nadeem Vawda was given push privileges on Apr 10 2011 by GFB, for ++general contributions, on recommendation by Antoine Pitrou.

            ++
            • ++

          • Carl Friedrich Bolz was given push privileges on Mar 21 2011 by BAC, for ++stdlib compatibility work for PyPy.

            ++
            • ++

          • Alexis Métaireau, Elson Rodriguez, Kelsey Hightower, Michael Mulich and ++Walker Hale were given push privileges on Mar 16 2011 by GFB, for ++contributions to the packaging module.

            ++
            • ++

          • Jeff Hardy was given push privileges on Mar 14 2011 by BAC, for stdlib ++compatibility work for IronPython.

            ++
            • ++

          • Alex Gaynor and Maciej Fijalkowski were given push privileges on Mar 13 2011 ++by BAC, for stdlib compatibility work for PyPy.

            ++
            • ++

          • Ross Lagerwall was given push privileges on Mar 13 2011 by GFB, ++on recommendation by Antoine Pitrou and Ned Deily.

            ++
            • ++

          • Eli Bendersky was given commit access on Jan 11 2011 by BAC, ++on recommendation by Terry Reedy and Nick Coghlan.

            ++
            • ++

          • Ned Deily was given commit access on Jan 9 2011 by MvL, ++on recommendation by Antoine Pitrou.

            ++
            • ++

          • David Malcolm was given commit access on Oct 27 2010 by GFB, ++at recommendation by Antoine Pitrou and Raymond Hettinger.

            ++
            • ++

          • Tal Einat was given commit access on Oct 4 2010 by MvL, ++for improving IDLE.

            ++
            • ++

          • Łukasz Langa was given commit access on Sep 08 2010 by GFB, ++at suggestion of Antoine Pitrou, for general bug fixing.

            ++
            • ++

          • Daniel Stutzbach was given commit access on Aug 22 2010 by MvL, ++for general bug fixing.

            ++
            • ++

          • Ask Solem was given commit access on Aug 17 2010 by MvL, ++on recommendation by Jesse Noller, for work on the multiprocessing ++library.

            ++
            • ++

          • George Boutsioukis was given commit access on Aug 10 2010 ++by MvL, for work on 2to3.

            ++
            • ++

          • Éric Araujo was given commit access on Aug 10 2010 by BAC, ++at suggestion of Tarek Ziadé.

            ++
            • ++

          • Terry Reedy was given commit access on Aug 04 2010 by MvL, ++at suggestion of Nick Coghlan.

            ++
            • ++

          • Brian Quinlan was given commit access on Jul 26 2010 by GFB, ++for work related to PEP 3148.

            ++
            • ++

          • Reid Kleckner was given commit access on Jul 11 2010 by GFB, ++for work on the py3k-jit branch, at suggestion of the Unladen ++Swallow team.

            ++
            • ++

          • Alexander Belopolsky was given commit access on May 25 2010 ++by MvL at suggestion of Mark Dickinson.

            ++
            • ++

          • Tim Golden was given commit access on April 21 2010 by MvL, ++at suggestion of Michael Foord.

            ++
            • ++

          • Giampaolo Rodolà was given commit access on April 17 2010 by ++MvL, at suggestion of R. David Murray.

            ++
            • ++

          • Jean-Paul Calderone was given commit access on April 6 2010 by ++GFB, at suggestion of Michael Foord and others.

            ++
            • ++

          • Brian Curtin was given commit access on March 24 2010 by MvL.

            ++
            • ++

          • Florent Xicluna was given commit access on February 25 2010 by ++MvL, based on Antoine Pitrou’s recommendation.

            ++
            • ++

          • Dino Viehland was given SVN access on February 23 2010 by Brett ++Cannon, for backporting tests from IronPython.

            ++
            • ++

          • Larry Hastings was given SVN access on February 22 2010 by ++Andrew Kuchling, based on Brett Cannon’s recommendation.

            ++
            • ++

          • Victor Stinner was given SVN access on January 30 2010 by MvL, ++at recommendation by Mark Dickinson and Amaury Forgeot d’Arc.

            ++
            • ++

          • Stefan Krah was given SVN access on January 5 2010 by GFB, at ++suggestion of Mark Dickinson, for work on the decimal module.

            ++
            • ++

          • Doug Hellmann was given SVN access on September 19 2009 by GFB, at ++suggestion of Jesse Noller, for documentation work.

            ++
            • ++

          • Ezio Melotti was given SVN access on June 7 2009 by GFB, for work on and ++fixes to the documentation.

            ++
            • ++

          • Paul Kippes was given commit privileges at PyCon 2009 by BAC to work on 3to2.

            ++
            • ++

          • Ron DuPlain was given commit privileges at PyCon 2009 by BAC to work on 3to2.

            ++
            • ++

          • Several developers of alternative Python implementations where ++given access for test suite and library adaptions by MvL: ++Allison Randal (Parrot), Michael Foord (IronPython), ++Jim Baker, Philip Jenvey, and Frank Wierzbicki (all Jython).

            ++
            • ++

          • R. David Murray was given SVN access on March 30 2009 by MvL, after ++recommendation by BAC.

            ++
            • ++

          • Chris Withers was given SVN access on March 8 2009 by MvL, ++after recommendation by GvR.

            ++
            • ++

          • Tarek Ziadé was given SVN access on December 21 2008 by NCN, ++for maintenance of distutils.

            ++
            • ++

          • Hirokazu Yamamoto was given SVN access on August 12 2008 by MvL, ++for contributions to the Windows build.

            ++
            • ++

          • Antoine Pitrou was given SVN access on July 16 2008, by recommendation ++from GvR, for general contributions to Python.

            ++
            • ++

          • Jesse Noller was given SVN access on 16 June 2008 by GFB, ++for work on the multiprocessing module.

            ++
            • ++

          • Gregor Lingl was given SVN access on 10 June 2008 by MvL, ++for work on the turtle module.

            ++
            • ++

          • Robert Schuppenies was given SVN access on 21 May 2008 by MvL, ++for GSoC contributions.

            ++
            • ++

          • Rodrigo Bernardo Pimentel was given SVN access on 29 April 2008 by MvL, ++for GSoC contributions.

            ++
            • ++

          • Heiko Weinen was given SVN access on 29 April 2008 by MvL, ++for GSoC contributions.

            ++
            • ++

          • Jesus Cea was given SVN access on 24 April 2008 by MvL, ++for maintenance of bsddb.

            ++
            • ++

          • Guilherme Polo was given SVN access on 24 April 2008 by MvL, ++for GSoC contributions.

            ++
            • ++

          • Thomas Lee was given SVN access on 21 April 2008 by NCN, ++for work on branches (ast/optimizer related).

            ++
            • ++

          • Jeroen Ruigrok van der Werven was given SVN access on 12 April 2008 ++by GFB, for documentation work.

            ++
            • ++

          • Josiah Carlson was given SVN access on 26 March 2008 by GFB, ++for work on asyncore/asynchat.

            ++
            • ++

          • Benjamin Peterson was given SVN access on 25 March 2008 by GFB, ++for bug triage work.

            ++
            • ++

          • Jerry Seutter was given SVN access on 20 March 2008 by BAC, for ++general contributions to Python.

            ++
            • ++

          • Jeff Rush was given SVN access on 18 March 2008 by AMK, for Distutils work.

            ++
            • ++

          • David Wolever was given SVN access on 17 March 2008 by MvL, ++for 2to3 work.

            ++
            • ++

          • Trent Nelson was given SVN access on 17 March 2008 by MvL, ++for general contributions to Python.

            ++
            • ++

          • Mark Dickinson was given SVN access on 6 January 2008 by Facundo ++Batista for his work on mathematics and number related issues.

            ++
            • ++

          • Amaury Forgeot d’Arc was given SVN access on 9 November 2007 by MvL, ++for general contributions to Python.

            ++
            • ++

          • Christian Heimes was given SVN access on 31 October 2007 by MvL, ++for general contributions to Python.

            ++
            • ++

          • Chris Monson was given SVN access on 20 October 2007 by NCN, ++for his work on editing PEPs.

            ++
            • ++

          • Bill Janssen was given SVN access on 28 August 2007 by NCN, ++for his work on the SSL module and other things related to (SSL) sockets.

            ++
            • ++

          • Jeffrey Yasskin was given SVN access on 9 August 2007 by NCN, ++for his work on PEPs and other general patches.

            ++
            • ++

          • Mark Summerfield was given SVN access on 1 August 2007 by GFB, ++for work on documentation.

            ++
            • ++

          • Armin Ronacher was given SVN access on 23 July 2007 by GFB, ++for work on the documentation toolset. He now maintains the ++ast module.

            ++
            • ++

          • Senthil Kumaran was given SVN access on 16 June 2007 by MvL, ++for his Summer-of-Code project, mentored by Skip Montanaro.

            ++
            • ++

          • Alexandre Vassalotti was given SVN access on 21 May 2007 by MvL, ++for his Summer-of-Code project, mentored by Brett Cannon.

            ++
            • ++

          • Travis Oliphant was given SVN access on 17 Apr 2007 by MvL, ++for implementing the extended buffer protocol.

            ++
            • ++

          • Ziga Seilnacht was given SVN access on 09 Mar 2007 by MvL, ++for general maintenance.

            ++
            • ++

          • Pete Shinners was given SVN access on 04 Mar 2007 by NCN, ++for PEP 3101 work in the sandbox.

            ++
            • ++

          • Pat Maupin and Eric V. Smith were given SVN access on 28 Feb 2007 by NCN, ++for PEP 3101 work in the sandbox.

            ++
            • ++

          • Steven Bethard (SF name “bediviere”) added to the SourceForge Python ++project 26 Feb 2007, by NCN, as a tracker tech.

            ++
            • ++

          • Josiah Carlson (SF name “josiahcarlson”) added to the SourceForge Python ++project 06 Jan 2007, by NCN, as a tracker tech. He will maintain asyncore.

            ++
            • ++

          • Collin Winter was given SVN access on 05 Jan 2007 by NCN, for PEP ++update access.

            ++
            • ++

          • Lars Gustaebel was given SVN access on 20 Dec 2006 by NCN, for tarfile.py ++related work.

            ++
            • ++

          • 2006 Summer of Code entries: SoC developers are expected to work ++primarily in nondist/sandbox or on a branch of their own, and will ++have their work reviewed before changes are accepted into the trunk.

            ++
              ++
            • Matt Fleming was added on 25 May 2006 by AMK; he’ll be working on ++enhancing the Python debugger.
              • ++
            • Jackilyn Hoxworth was added on 25 May 2006 by AMK; she’ll be adding logging ++to the standard library.
              • ++
            • Mateusz Rukowicz was added on 30 May 2006 by AMK; he’ll be ++translating the decimal module into C.
              • ++
            ++
            • ++

          • SVN access granted to the “Need for Speed” Iceland sprint attendees, ++between May 17 and 21, 2006, by Tim Peters. All work is to be done ++in new sandbox projects or on new branches, with merging to the ++trunk as approved:

            ++

            Andrew Dalke ++Christian Tismer ++Jack Diederich ++John Benediktsson ++Kristján V. Jónsson ++Martin Blais ++Richard Emslie ++Richard Jones ++Runar Petursson ++Steve Holden ++Richard M. Tew

            ++
            • ++

          • Steven Bethard was given SVN access on 27 Apr 2006 by DJG, for PEP ++update access.

            ++
            • ++

          • Talin was given SVN access on 27 Apr 2006 by DJG, for PEP update ++access.

            ++
            • ++

          • George Yoshida (SF name “quiver”) added to the SourceForge Python ++project 14 Apr 2006, by Tim Peters, as a tracker admin. See ++contemporaneous python-checkins thread with the unlikely Subject: ++r45329 - python/trunk/Doc/whatsnew/whatsnew25.tex

            ++
            • ++

          • Ronald Oussoren was given SVN access on 3 Mar 2006 by NCN, for Mac ++related work.

            ++
            • ++

          • Bob Ippolito was given SVN access on 2 Mar 2006 by NCN, for Mac ++related work.

            ++
            • ++

          • Nick Coghlan requested CVS access so he could update his PEP directly. ++Granted by GvR on 16 Oct 2005.

            ++
            • ++

          • Added two new developers for the Summer of Code project. 8 July 2005 ++by RDH. Andrew Kuchling will be mentoring Gregory K Johnson for a ++project to enhance mailbox. Brett Cannon requested access for Flovis ++Bruynooghe (sirolf) to work on pstats, profile, and hotshot. Both users ++are expected to work primarily in nondist/sandbox and have their work ++reviewed before making updates to active code.

            ++
            • ++

          • Georg Brandl was given SF tracker permissions on 28 May 2005 ++by RDH. Since the beginning of 2005, he has been active in discussions ++on python-dev and has submitted a dozen patch reviews. The permissions ++add the ability to change tracker status and to attach patches. On ++3 June 2005, this was expanded by RDH to include checkin permissions.

            ++
            • ++

          • Terry Reedy was given SF tracker permissions on 7 Apr 2005 by RDH.

            ++
            • ++

          • Nick Coghlan was given SF tracker permissions on 5 Apr 2005 by RDH. ++For several months, he has been active in reviewing and contributing ++patches. The added permissions give him greater flexibility in ++working with the tracker.

            ++
            • ++

          • Eric Price was made a developer on 2 May 2003 by TGP. This was ++specifically to work on the new decimal package, which lived in ++nondist/sandbox/decimal/ at the time.

            ++
            • ++

          • Eric S. Raymond was made a developer on 2 Jul 2000 by TGP, for general ++library work. His request is archived here: ++http://mail.python.org/pipermail/python-dev/2000-July/005314.html

            ++
            • ++
          ++
          ++
          ++

          15.2. Permissions Dropped on Request

          ++
            ++
          • Roy Smith, Matt Fleming and Richard Emslie sent drop requests. ++4 Aug 2008 GFB
            • ++
          • Per note from Andrew Kuchling, the permissions for Gregory K Johnson ++and the Summer Of Code project are no longer needed. 4 Aug 2008 GFB
            • ++
          • Per note from Andrew Kuchling, the permissions for Gregory K Johnson ++and the Summer Of Code project are no longer needed. AMK will make ++any future checkins directly. 16 Oct 2005 RDH
            • ++
          • Johannes Gijsbers sent a drop request. 27 July 2005 RDH
            • ++
          • Flovis Bruynooghe sent a drop request. 14 July 2005 RDH
            • ++
          • Paul Prescod sent a drop request. 30 Apr 2005 RDH
            • ++
          • Finn Bock sent a drop request. 13 Apr 2005 RDH
            • ++
          • Eric Price sent a drop request. 10 Apr 2005 RDH
            • ++
          • Irmen de Jong requested dropping CVS access while keeping tracker ++access. 10 Apr 2005 RDH
            • ++
          • Moshe Zadka and Ken Manheimer sent drop requests. 8 Apr 2005 by RDH
            • ++
          • Steve Holden, Gerhard Haring, and David Cole sent email stating that ++they no longer use their access. 7 Apr 2005 RDH
            • ++
          ++
          ++
          ++

          15.3. Permissions Dropped after Loss of Contact

          ++
            ++
          • Several unsuccessful efforts were made to contact Charles G Waldman. ++Removed on 8 Apr 2005 by RDH.
            • ++
          ++
          ++
          ++

          15.4. Initials of Project Admins

          ++
            ++
          • TGP: Tim Peters
            • ++
          • GFB: Georg Brandl
            • ++
          • BAC: Brett Cannon
            • ++
          • NCN: Neal Norwitz
            • ++
          • DJG: David Goodger
            • ++
          • MvL: Martin v. Loewis
            • ++
          • GvR: Guido van Rossum
            • ++
          • RDH: Raymond Hettinger
            • ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          14. How to Become a Core Developer

          ++

          Next topic

          ++

          16. Committing and Pushing Changes

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/docquality.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/docquality.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,187 @@ ++ ++ ++ ++ ++ ++ ++ ++ 7. Helping with Documentation — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          7. Helping with Documentation

          ++

          Python is known for having good documentation. But maintaining all of it and ++keeping a high level of quality takes a lot of effort. Help is always ++appreciated with the documentation, and it requires little programming ++experience (with or without Python).

          ++

          Documenting Python covers the details of how Python’s documentation works. ++It includes an explanation of the markup used (although you can figure a lot ++out simply by looking at pre-existing documentation) and how to build the documentation (which allows you to see how your changes ++will look along with validating that your new markup is correct).

          ++

          The documentation built from the in-development and ++maintenance branches can be viewed from ++http://docs.python.org/dev/. The in-development and most recent 2.x and 3.x ++maintenance branches are rebuilt once per day.

          ++

          If you care to get more involved with documentation, you may also consider ++subscribing to the ++docs@python.org mailing list. ++Documentation issues reported on the issue tracker are sent here as well as ++some bug reports being directly emailed to the mailing list. There is also the ++docs-sig@python.org mailing list which discusses the ++documentation toolchain, projects, standards, etc.

          ++
          ++

          7.1. Helping with issues filed on the issue tracker

          ++

          If you look at documentation issues on the issue tracker, you ++will find various documentation problems that need work. Issues vary from ++typos, to unclear documentation, to something completely lacking documentation.

          ++

          If you decide to tackle a documentation issue, you simply create a patch for the issue and upload it. If you are worried that someone else might ++be working simultaneously on the issue, simply leave a comment on the issue ++saying you are going to try and create a patch and roughly how long you think ++you will take to do it (this allows others to take on the issue if you happen ++to forget or lose interest).

          ++
          ++
          ++

          7.2. Proofreading

          ++

          While an issue filed on the issue tracker means there is a known issue ++somewhere, that does not mean there are not other issues lurking about in the ++documentation. Simply proofreading parts of the documentation is enough to ++uncover problems (e.g., documentation that needs to be updated for Python 3 ++from Python 2).

          ++

          If you decide to proofread, then read a section of the documentation from start ++to finish, filing issues in the issue tracker for each problem you find. Don’t ++file a single issue for an entire section containing multiple problems as that ++makes it harder to break the work up for multiple people to help with.

          ++
          ++
          ++

          7.3. Helping with the Developer’s Guide

          ++

          The Developer’s Guide uses the same process as the main Python documentation, ++except for some small differences. The source lives in a separate ++repository. Bug reports and patches should be submitted to the Python ++bug tracker using the devguide component. Changes to the devguide ++are normally published within a day, on a schedule that may be different from ++the main documentation.

          ++

          To clone the Developer’s Guide:

          ++
          $ hg clone http://hg.python.org/devguide
++
          ++
          ++

          Core developers should use:

          ++
          $ hg clone ssh://hg@hg.python.org/devguide
++
          ++
          ++

          instead so that they can push back their edits to the server.

          ++

          To build the devguide, you must have Sphinx installed. The devguide HTML ++can be built by running:

          ++
          $ make html
++
          ++
          ++

          in the checkout directory, which will write the files to the _build/html ++directory.

          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          6. Increase Test Coverage

          ++

          Next topic

          ++

          8. Documenting Python

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/documenting.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/documenting.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,1666 @@ ++ ++ ++ ++ ++ ++ ++ ++ 8. Documenting Python — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          8. Documenting Python

          ++

          The Python language has a substantial body of documentation, much of it ++contributed by various authors. The markup used for the Python documentation is ++reStructuredText, developed by the docutils project, amended by custom ++directives and using a toolset named Sphinx to post-process the HTML output.

          ++

          This document describes the style guide for our documentation as well as the ++custom reStructuredText markup introduced by Sphinx to support Python ++documentation and how it should be used.

          ++

          The documentation in HTML, PDF or EPUB format is generated from text files ++written using the reStructuredText format and contained in the ++CPython Mercurial repository.

          ++
          ++

          Note

          ++

          If you’re interested in contributing to Python’s documentation, there’s no ++need to write reStructuredText if you’re not so inclined; plain text ++contributions are more than welcome as well. Send an e-mail to ++docs@python.org or open an issue on the tracker.

          ++
          ++
          ++

          8.1. Introduction

          ++

          Python’s documentation has long been considered to be good for a free ++programming language. There are a number of reasons for this, the most ++important being the early commitment of Python’s creator, Guido van Rossum, to ++providing documentation on the language and its libraries, and the continuing ++involvement of the user community in providing assistance for creating and ++maintaining documentation.

          ++

          The involvement of the community takes many forms, from authoring to bug reports ++to just plain complaining when the documentation could be more complete or ++easier to use.

          ++

          This document is aimed at authors and potential authors of documentation for ++Python. More specifically, it is for people contributing to the standard ++documentation and developing additional documents using the same tools as the ++standard documents. This guide will be less useful for authors using the Python ++documentation tools for topics other than Python, and less useful still for ++authors not using the tools at all.

          ++

          If your interest is in contributing to the Python documentation, but you don’t ++have the time or inclination to learn reStructuredText and the markup structures ++documented here, there’s a welcoming place for you among the Python contributors ++as well. Any time you feel that you can clarify existing documentation or ++provide documentation that’s missing, the existing documentation team will ++gladly work with you to integrate your text, dealing with the markup for you. ++Please don’t let the material in this document stand between the documentation ++and your desire to help out!

          ++
          ++
          ++

          8.2. Style guide

          ++
          ++

          8.2.1. Use of whitespace

          ++

          All reST files use an indentation of 3 spaces; no tabs are allowed. The ++maximum line length is 80 characters for normal text, but tables, deeply ++indented code samples and long links may extend beyond that. Code example ++bodies should use normal Python 4-space indentation.

          ++

          Make generous use of blank lines where applicable; they help grouping things ++together.

          ++

          A sentence-ending period may be followed by one or two spaces; while reST ++ignores the second space, it is customarily put in by some users, for example ++to aid Emacs’ auto-fill mode.

          ++
          ++
          ++

          8.2.2. Footnotes

          ++

          Footnotes are generally discouraged, though they may be used when they are the ++best way to present specific information. When a footnote reference is added at ++the end of the sentence, it should follow the sentence-ending punctuation. The ++reST markup should appear something like this:

          ++
          This sentence has a footnote reference. [#]_ This is the next sentence.
++
          ++
          ++

          Footnotes should be gathered at the end of a file, or if the file is very long, ++at the end of a section. The docutils will automatically create backlinks to ++the footnote reference.

          ++

          Footnotes may appear in the middle of sentences where appropriate.

          ++
          ++
          ++

          8.2.3. Capitalization

          ++
          ++

          Sentence case

          ++

          Sentence case is a set of capitalization rules used in English ++sentences: the first word is always capitalized and other words are ++only capitalized if there is a specific rule requiring it.

          ++
          ++

          In the Python documentation, the use of sentence case in section titles is ++preferable, but consistency within a unit is more important than ++following this rule. If you add a section to a chapter where most ++sections are in title case, you can either convert all titles to ++sentence case or use the dominant style in the new section title.

          ++

          Sentences that start with a word for which specific rules require ++starting it with a lower case letter should be avoided.

          ++
          ++

          Note

          ++

          Sections that describe a library module often have titles in the ++form of “modulename — Short description of the module.” In this ++case, the description should be capitalized as a stand-alone ++sentence.

          ++
          ++

          Many special names are used in the Python documentation, including the names of ++operating systems, programming languages, standards bodies, and the like. Most ++of these entities are not assigned any special markup, but the preferred ++spellings are given here to aid authors in maintaining the consistency of ++presentation in the Python documentation.

          ++

          Other terms and words deserve special mention as well; these conventions should ++be used to ensure consistency throughout the documentation:

          ++
          ++
          CPU
          ++
          For “central processing unit.” Many style guides say this should be ++spelled out on the first use (and if you must use it, do so!). For ++the Python documentation, this abbreviation should be avoided since ++there’s no reasonable way to predict which occurrence will be the ++first seen by the reader. It is better to use the word “processor” ++instead.
          ++
          POSIX
          ++
          The name assigned to a particular group of standards. This is always ++uppercase.
          ++
          Python
          ++
          The name of our favorite programming language is always capitalized.
          ++
          reST
          ++
          For “reStructuredText,” an easy to read, plaintext markup syntax ++used to produce Python documentation. When spelled out, it is ++always one word and both forms start with a lower case ‘r’.
          ++
          Unicode
          ++
          The name of a character coding system. This is always written ++capitalized.
          ++
          Unix
          ++
          The name of the operating system developed at AT&T Bell Labs in the early ++1970s.
          ++
          ++
          ++
          ++

          8.2.4. Affirmative Tone

          ++

          The documentation focuses on affirmatively stating what the language does and ++how to use it effectively.

          ++

          Except for certain security risks or segfault risks, the docs should avoid ++wording along the lines of “feature x is dangerous” or “experts only”. These ++kinds of value judgments belong in external blogs and wikis, not in the core ++documentation.

          ++

          Bad example (creating worry in the mind of a reader):

          ++
          ++
          Warning: failing to explicitly close a file could result in lost data or ++excessive resource consumption. Never rely on reference counting to ++automatically close a file.
          ++

          Good example (establishing confident knowledge in the effective use of the language):

          ++
          ++
          A best practice for using files is use a try/finally pair to explicitly ++close a file after it is used. Alternatively, using a with-statement can ++achieve the same effect. This assures that files are flushed and file ++descriptor resources are released in a timely manner.
          ++
          ++
          ++

          8.2.5. Economy of Expression

          ++

          More documentation is not necessarily better documentation. Err on the side ++of being succinct.

          ++

          It is an unfortunate fact that making documentation longer can be an impediment ++to understanding and can result in even more ways to misread or misinterpret the ++text. Long descriptions full of corner cases and caveats can create the ++impression that a function is more complex or harder to use than it actually is.

          ++
          ++
          ++

          8.2.6. Security Considerations (and Other Concerns)

          ++

          Some modules provided with Python are inherently exposed to security issues ++(e.g. shell injection vulnerabilities) due to the purpose of the module ++(e.g. ssl). Littering the documentation of these modules with red ++warning boxes for problems that are due to the task at hand, rather than ++specifically to Python’s support for that task, doesn’t make for a good ++reading experience.

          ++

          Instead, these security concerns should be gathered into a dedicated ++“Security Considerations” section within the module’s documentation, and ++cross-referenced from the documentation of affected interfaces with a note ++similar to "Please refer to the :ref:`security-considerations` section ++for important information on how to avoid common mistakes.".

          ++

          Similarly, if there is a common error that affects many interfaces in a ++module (e.g. OS level pipe buffers filling up and stalling child processes), ++these can be documented in a “Common Errors” section and cross-referenced ++rather than repeated for every affected interface.

          ++
          ++
          ++

          8.2.7. Code Examples

          ++

          Short code examples can be a useful adjunct to understanding. Readers can often ++grasp a simple example more quickly than they can digest a formal description in ++prose.

          ++

          People learn faster with concrete, motivating examples that match the context of ++a typical use case. For instance, the str.rpartition() method is better ++demonstrated with an example splitting the domain from a URL than it would be ++with an example of removing the last word from a line of Monty Python dialog.

          ++

          The ellipsis for the sys.ps2 secondary interpreter prompt should only be ++used sparingly, where it is necessary to clearly differentiate between input ++lines and output lines. Besides contributing visual clutter, it makes it ++difficult for readers to cut-and-paste examples so they can experiment with ++variations.

          ++
          ++
          ++

          8.2.8. Code Equivalents

          ++

          Giving pure Python code equivalents (or approximate equivalents) can be a useful ++adjunct to a prose description. A documenter should carefully weigh whether the ++code equivalent adds value.

          ++

          A good example is the code equivalent for all(). The short 4-line code ++equivalent is easily digested; it re-emphasizes the early-out behavior; and it ++clarifies the handling of the corner-case where the iterable is empty. In ++addition, it serves as a model for people wanting to implement a commonly ++requested alternative where all() would return the specific object ++evaluating to False whenever the function terminates early.

          ++

          A more questionable example is the code for itertools.groupby(). Its code ++equivalent borders on being too complex to be a quick aid to understanding. ++Despite its complexity, the code equivalent was kept because it serves as a ++model to alternative implementations and because the operation of the “grouper” ++is more easily shown in code than in English prose.

          ++

          An example of when not to use a code equivalent is for the oct() function. ++The exact steps in converting a number to octal doesn’t add value for a user ++trying to learn what the function does.

          ++
          ++
          ++

          8.2.9. Audience

          ++

          The tone of the tutorial (and all the docs) needs to be respectful of the ++reader’s intelligence. Don’t presume that the readers are stupid. Lay out the ++relevant information, show motivating use cases, provide glossary links, and do ++your best to connect-the-dots, but don’t talk down to them or waste their time.

          ++

          The tutorial is meant for newcomers, many of whom will be using the tutorial to ++evaluate the language as a whole. The experience needs to be positive and not ++leave the reader with worries that something bad will happen if they make a ++misstep. The tutorial serves as guide for intelligent and curious readers, ++saving details for the how-to guides and other sources.

          ++

          Be careful accepting requests for documentation changes from the rare but vocal ++category of reader who is looking for vindication for one of their programming ++errors (“I made a mistake, therefore the docs must be wrong ...”). Typically, ++the documentation wasn’t consulted until after the error was made. It is ++unfortunate, but typically no documentation edit would have saved the user from ++making false assumptions about the language (“I was surprised by ...”).

          ++
          ++
          ++
          ++

          8.3. reStructuredText Primer

          ++

          This section is a brief introduction to reStructuredText (reST) concepts and ++syntax, intended to provide authors with enough information to author documents ++productively. Since reST was designed to be a simple, unobtrusive markup ++language, this will not take too long.

          ++
          ++

          See also

          ++

          The authoritative reStructuredText User ++Documentation.

          ++
          ++
          ++

          8.3.1. Paragraphs

          ++

          The paragraph is the most basic block in a reST document. Paragraphs are simply ++chunks of text separated by one or more blank lines. As in Python, indentation ++is significant in reST, so all lines of the same paragraph must be left-aligned ++to the same level of indentation.

          ++
          ++
          ++

          8.3.2. Inline markup

          ++

          The standard reST inline markup is quite simple: use

          ++
            ++
          • one asterisk: *text* for emphasis (italics),
            • ++
          • two asterisks: **text** for strong emphasis (boldface), and
            • ++
          • backquotes: ``text`` for code samples.
            • ++
          ++

          If asterisks or backquotes appear in running text and could be confused with ++inline markup delimiters, they have to be escaped with a backslash.

          ++

          Be aware of some restrictions of this markup:

          ++
            ++
          • it may not be nested,
            • ++
          • content may not start or end with whitespace: * text* is wrong,
            • ++
          • it must be separated from surrounding text by non-word characters. Use a ++backslash escaped space to work around that: thisis\ *one*\ word.
            • ++
          ++

          These restrictions may be lifted in future versions of the docutils.

          ++

          reST also allows for custom “interpreted text roles”’, which signify that the ++enclosed text should be interpreted in a specific way. Sphinx uses this to ++provide semantic markup and cross-referencing of identifiers, as described in ++the appropriate section. The general syntax is :rolename:`content`.

          ++
          ++
          ++

          8.3.3. Lists and Quotes

          ++

          List markup is natural: just place an asterisk at the start of a paragraph and ++indent properly. The same goes for numbered lists; they can also be ++automatically numbered using a # sign:

          ++
          * This is a bulleted list.
++* It has two items, the second
++  item uses two lines.
++
++1. This is a numbered list.
++2. It has two items too.
++
++#. This is a numbered list.
++#. It has two items too.
++
          ++
          ++

          Nested lists are possible, but be aware that they must be separated from the ++parent list items by blank lines:

          ++
          * this is
++* a list
++
++  * with a nested list
++  * and some subitems
++
++* and here the parent list continues
++
          ++
          ++

          Definition lists are created as follows:

          ++
          term (up to a line of text)
++   Definition of the term, which must be indented
++
++   and can even consist of multiple paragraphs
++
++next term
++   Description.
++
          ++
          ++

          Paragraphs are quoted by just indenting them more than the surrounding ++paragraphs.

          ++
          ++
          ++

          8.3.4. Source Code

          ++

          Literal code blocks are introduced by ending a paragraph with the special marker ++::. The literal block must be indented:

          ++
          This is a normal text paragraph. The next paragraph is a code sample::
++
++   It is not processed in any way, except
++   that the indentation is removed.
++
++   It can span multiple lines.
++
++This is a normal text paragraph again.
++
          ++
          ++

          The handling of the :: marker is smart:

          ++
            ++
          • If it occurs as a paragraph of its own, that paragraph is completely left ++out of the document.
            • ++
          • If it is preceded by whitespace, the marker is removed.
            • ++
          • If it is preceded by non-whitespace, the marker is replaced by a single ++colon.
            • ++
          ++

          That way, the second sentence in the above example’s first paragraph would be ++rendered as “The next paragraph is a code sample:”.

          ++
          ++ ++
          ++

          8.3.6. Sections

          ++

          Section headers are created by underlining (and optionally overlining) the ++section title with a punctuation character, at least as long as the text:

          ++
          =================
++This is a heading
++=================
++
          ++
          ++

          Normally, there are no heading levels assigned to certain characters as the ++structure is determined from the succession of headings. However, for the ++Python documentation, here is a suggested convention:

          ++
            ++
          • # with overline, for parts
            • ++
          • * with overline, for chapters
            • ++
          • =, for sections
            • ++
          • -, for subsections
            • ++
          • ^, for subsubsections
            • ++
          • ", for paragraphs
            • ++
          ++
          ++
          ++

          8.3.7. Explicit Markup

          ++

          “Explicit markup” is used in reST for most constructs that need special ++handling, such as footnotes, specially-highlighted paragraphs, comments, and ++generic directives.

          ++

          An explicit markup block begins with a line starting with .. followed by ++whitespace and is terminated by the next paragraph at the same level of ++indentation. (There needs to be a blank line between explicit markup and normal ++paragraphs. This may all sound a bit complicated, but it is intuitive enough ++when you write it.)

          ++
          ++
          ++

          8.3.8. Directives

          ++

          A directive is a generic block of explicit markup. Besides roles, it is one of ++the extension mechanisms of reST, and Sphinx makes heavy use of it.

          ++

          Basically, a directive consists of a name, arguments, options and content. (Keep ++this terminology in mind, it is used in the next chapter describing custom ++directives.) Looking at this example,

          ++
          .. function:: foo(x)
++              foo(y, z)
++   :bar: no
++
++   Return a line of text input from the user.
++
          ++
          ++

          function is the directive name. It is given two arguments here, the ++remainder of the first line and the second line, as well as one option bar ++(as you can see, options are given in the lines immediately following the ++arguments and indicated by the colons).

          ++

          The directive content follows after a blank line and is indented relative to the ++directive start.

          ++
          ++
          ++

          8.3.9. Footnotes

          ++

          For footnotes, use [#]_ to mark the footnote location, and add the footnote ++body at the bottom of the document after a “Footnotes” rubric heading, like so:

          ++
          Lorem ipsum [#]_ dolor sit amet ... [#]_
++
++.. rubric:: Footnotes
++
++.. [#] Text of the first footnote.
++.. [#] Text of the second footnote.
++
          ++
          ++

          You can also explicitly number the footnotes for better context.

          ++
          ++
          ++

          8.3.10. Comments

          ++

          Every explicit markup block which isn’t a valid markup construct (like the ++footnotes above) is regarded as a comment.

          ++
          ++
          ++

          8.3.11. Source encoding

          ++

          Since the easiest way to include special characters like em dashes or copyright ++signs in reST is to directly write them as Unicode characters, one has to ++specify an encoding:

          ++

          All Python documentation source files must be in UTF-8 encoding, and the HTML ++documents written from them will be in that encoding as well.

          ++
          ++
          ++

          8.3.12. Gotchas

          ++

          There are some problems one commonly runs into while authoring reST documents:

          ++
            ++
          • Separation of inline markup: As said above, inline markup spans must be ++separated from the surrounding text by non-word characters, you have to use ++an escaped space to get around that.
            • ++
          ++
          ++
          ++
          ++

          8.4. Additional Markup Constructs

          ++

          Sphinx adds a lot of new directives and interpreted text roles to standard reST ++markup. This section contains the reference material for these facilities. ++Documentation for “standard” reST constructs is not included here, though ++they are used in the Python documentation.

          ++
          ++

          Note

          ++

          This is just an overview of Sphinx’ extended markup capabilities; full ++coverage can be found in its own documentation.

          ++
          ++
          ++

          8.4.1. Meta-information markup

          ++
          ++
          ++sectionauthor
          ++

          Identifies the author of the current section. The argument should include ++the author’s name such that it can be used for presentation (though it isn’t) ++and email address. The domain name portion of the address should be lower ++case. Example:

          ++
          .. sectionauthor:: Guido van Rossum <guido@python.org>
++
          ++
          ++

          Currently, this markup isn’t reflected in the output in any way, but it helps ++keep track of contributions.

          ++
          ++ ++
          ++
          ++

          8.4.2. Module-specific markup

          ++

          The markup described in this section is used to provide information about a ++module being documented. Each module should be documented in its own file. ++Normally this markup appears after the title heading of that file; a typical ++file might start like this:

          ++
          :mod:`parrot` -- Dead parrot access
++===================================
++
++.. module:: parrot
++   :platform: Unix, Windows
++   :synopsis: Analyze and reanimate dead parrots.
++.. moduleauthor:: Eric Cleese <eric@python.invalid>
++.. moduleauthor:: John Idle <john@python.invalid>
++
          ++
          ++

          As you can see, the module-specific markup consists of two directives, the ++module directive and the moduleauthor directive.

          ++
          ++
          ++module
          ++

          This directive marks the beginning of the description of a module, package, ++or submodule. The name should be fully qualified (i.e. including the ++package name for submodules).

          ++

          The platform option, if present, is a comma-separated list of the ++platforms on which the module is available (if it is available on all ++platforms, the option should be omitted). The keys are short identifiers; ++examples that are in use include “IRIX”, “Mac”, “Windows”, and “Unix”. It is ++important to use a key which has already been used when applicable.

          ++

          The synopsis option should consist of one sentence describing the ++module’s purpose – it is currently only used in the Global Module Index.

          ++

          The deprecated option can be given (with no value) to mark a module as ++deprecated; it will be designated as such in various locations then.

          ++
          ++ ++
          ++
          ++moduleauthor
          ++

          The moduleauthor directive, which can appear multiple times, names the ++authors of the module code, just like sectionauthor names the author(s) ++of a piece of documentation. It too does not result in any output currently.

          ++
          ++ ++
          ++

          Note

          ++

          It is important to make the section title of a module-describing file ++meaningful since that value will be inserted in the table-of-contents trees ++in overview files.

          ++
          ++
          ++
          ++

          8.4.3. Information units

          ++

          There are a number of directives used to describe specific features provided by ++modules. Each directive requires one or more signatures to provide basic ++information about what is being described, and the content should be the ++description. The basic version makes entries in the general index; if no index ++entry is desired, you can give the directive option flag :noindex:. The ++following example shows all of the features of this directive type:

          ++
          .. function:: spam(eggs)
++              ham(eggs)
++   :noindex:
++
++   Spam or ham the foo.
++
          ++
          ++

          The signatures of object methods or data attributes should not include the ++class name, but be nested in a class directive. The generated files will ++reflect this nesting, and the target identifiers (for HTML output) will use ++both the class and method name, to enable consistent cross-references. If you ++describe methods belonging to an abstract protocol such as context managers, ++use a class directive with a (pseudo-)type name too to make the ++index entries more informative.

          ++

          The directives are:

          ++
          ++
          ++c:function
          ++

          Describes a C function. The signature should be given as in C, e.g.:

          ++
          .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
++
          ++
          ++

          This is also used to describe function-like preprocessor macros. The names ++of the arguments should be given so they may be used in the description.

          ++

          Note that you don’t have to backslash-escape asterisks in the signature, ++as it is not parsed by the reST inliner.

          ++
          ++ ++
          ++
          ++c:member
          ++

          Describes a C struct member. Example signature:

          ++
          .. c:member:: PyObject* PyTypeObject.tp_bases
++
          ++
          ++

          The text of the description should include the range of values allowed, how ++the value should be interpreted, and whether the value can be changed. ++References to structure members in text should use the member role.

          ++
          ++ ++
          ++
          ++c:macro
          ++

          Describes a “simple” C macro. Simple macros are macros which are used ++for code expansion, but which do not take arguments so cannot be described as ++functions. This is not to be used for simple constant definitions. Examples ++of its use in the Python documentation include PyObject_HEAD and ++Py_BEGIN_ALLOW_THREADS.

          ++
          ++ ++
          ++
          ++c:type
          ++

          Describes a C type. The signature should just be the type name.

          ++
          ++ ++
          ++
          ++c:var
          ++

          Describes a global C variable. The signature should include the type, such ++as:

          ++
          .. cvar:: PyObject* PyClass_Type
++
          ++
          ++
          ++ ++
          ++
          ++data
          ++

          Describes global data in a module, including both variables and values used ++as “defined constants.” Class and object attributes are not documented ++using this directive.

          ++
          ++ ++
          ++
          ++exception
          ++

          Describes an exception class. The signature can, but need not include ++parentheses with constructor arguments.

          ++
          ++ ++
          ++
          ++function
          ++

          Describes a module-level function. The signature should include the ++parameters, enclosing optional parameters in brackets. Default values can be ++given if it enhances clarity. For example:

          ++
          .. function:: repeat([repeat=3[, number=1000000]])
++
          ++
          ++

          Object methods are not documented using this directive. Bound object methods ++placed in the module namespace as part of the public interface of the module ++are documented using this, as they are equivalent to normal functions for ++most purposes.

          ++

          The description should include information about the parameters required and ++how they are used (especially whether mutable objects passed as parameters ++are modified), side effects, and possible exceptions. A small example may be ++provided.

          ++
          ++ ++
          ++
          ++decorator
          ++

          Describes a decorator function. The signature should not represent the ++signature of the actual function, but the usage as a decorator. For example, ++given the functions

          ++
          def removename(func):
++    func.__name__ = ''
++    return func
++
++def setnewname(name):
++    def decorator(func):
++        func.__name__ = name
++        return func
++    return decorator
++
          ++
          ++

          the descriptions should look like this:

          ++
          .. decorator:: removename
++
++   Remove name of the decorated function.
++
++.. decorator:: setnewname(name)
++
++   Set name of the decorated function to *name*.
++
          ++
          ++

          There is no deco role to link to a decorator that is marked up with ++this directive; rather, use the :func: role.

          ++
          ++ ++
          ++
          ++class
          ++

          Describes a class. The signature can include parentheses with parameters ++which will be shown as the constructor arguments.

          ++
          ++ ++
          ++
          ++attribute
          ++

          Describes an object data attribute. The description should include ++information about the type of the data to be expected and whether it may be ++changed directly. This directive should be nested in a class directive, ++like in this example:

          ++
          .. class:: Spam
++
++      Description of the class.
++
++      .. data:: ham
++
++         Description of the attribute.
++
          ++
          ++

          If is also possible to document an attribute outside of a class directive, ++for example if the documentation for different attributes and methods is ++split in multiple sections. The class name should then be included ++explicitly:

          ++
          .. data:: Spam.eggs
++
          ++
          ++
          ++ ++
          ++
          ++method
          ++

          Describes an object method. The parameters should not include the self ++parameter. The description should include similar information to that ++described for function. This directive should be nested in a class ++directive, like in the example above.

          ++
          ++ ++
          ++
          ++decoratormethod
          ++

          Same as decorator, but for decorators that are methods.

          ++

          Refer to a decorator method using the :meth: role.

          ++
          ++ ++
          ++
          ++opcode
          ++

          Describes a Python bytecode instruction.

          ++
          ++ ++
          ++
          ++cmdoption
          ++

          Describes a Python command line option or switch. Option argument names ++should be enclosed in angle brackets. Example:

          ++
          .. cmdoption:: -m <module>
++
++   Run a module as a script.
++
          ++
          ++
          ++ ++
          ++
          ++envvar
          ++

          Describes an environment variable that Python uses or defines.

          ++
          ++ ++

          There is also a generic version of these directives:

          ++
          ++
          ++describe
          ++

          This directive produces the same formatting as the specific ones explained ++above but does not create index entries or cross-referencing targets. It is ++used, for example, to describe the directives in this document. Example:

          ++
          .. describe:: opcode
++
++   Describes a Python bytecode instruction.
++
          ++
          ++
          ++ ++
          ++
          ++

          8.4.4. Showing code examples

          ++

          Examples of Python source code or interactive sessions are represented using ++standard reST literal blocks. They are started by a :: at the end of the ++preceding paragraph and delimited by indentation.

          ++

          Representing an interactive session requires including the prompts and output ++along with the Python code. No special markup is required for interactive ++sessions. After the last line of input or output presented, there should not be ++an “unused” primary prompt; this is an example of what not to do:

          ++
          >>> 1 + 1
++2
++>>>
++
          ++
          ++

          Syntax highlighting is handled in a smart way:

          ++
            ++

          • There is a “highlighting language” for each source file. Per default, ++this is 'python' as the majority of files will have to highlight Python ++snippets.

            ++
            • ++

          • Within Python highlighting mode, interactive sessions are recognized ++automatically and highlighted appropriately.

            ++
            • ++

          • The highlighting language can be changed using the highlightlang ++directive, used as follows:

            ++
            .. highlightlang:: c
++
            ++
            ++

            This language is used until the next highlightlang directive is ++encountered.

            ++
            • ++

          • The code-block directive can be used to specify the highlight language ++of a single code block, e.g.:

            ++
            .. code-block:: c
++
++   #include <stdio.h>
++
++   void main() {
++       printf("Hello world!\n");
++   }
++
            ++
            ++
            • ++

          • The values normally used for the highlighting language are:

            ++
              ++
            • python (the default)
              • ++
            • c
              • ++
            • rest
              • ++
            • none (no highlighting)
              • ++
            ++
            • ++

          • If highlighting with the current language fails, the block is not highlighted ++in any way.

            ++
            • ++
          ++

          Longer displays of verbatim text may be included by storing the example text in ++an external file containing only plain text. The file may be included using the ++literalinclude directive. [1] For example, to include the Python source file ++example.py, use:

          ++
          .. literalinclude:: example.py
++
          ++
          ++

          The file name is relative to the current file’s path. Documentation-specific ++include files should be placed in the Doc/includes subdirectory.

          ++
          ++
          ++

          8.4.5. Inline markup

          ++

          As said before, Sphinx uses interpreted text roles to insert semantic markup in ++documents.

          ++

          Names of local variables, such as function/method arguments, are an exception, ++they should be marked simply with *var*.

          ++

          For all other roles, you have to write :rolename:`content`.

          ++

          There are some additional facilities that make cross-referencing roles more ++versatile:

          ++
            ++

          • You may supply an explicit title and reference target, like in reST direct ++hyperlinks: :role:`title <target>` will refer to target, but the link ++text will be title.

            ++
            • ++

          • If you prefix the content with !, no reference/hyperlink will be created.

            ++
            • ++

          • For the Python object roles, if you prefix the content with ~, the link ++text will only be the last component of the target. For example, ++:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only ++display get as the link text.

            ++

            In HTML output, the link’s title attribute (that is e.g. shown as a ++tool-tip on mouse-hover) will always be the full target name.

            ++
            • ++
          ++

          The following roles refer to objects in modules and are possibly hyperlinked if ++a matching identifier is found:

          ++
          ++
          ++mod
          ++

          The name of a module; a dotted name may be used. This should also be used for ++package names.

          ++
          ++ ++
          ++
          ++func
          ++

          The name of a Python function; dotted names may be used. The role text ++should not include trailing parentheses to enhance readability. The ++parentheses are stripped when searching for identifiers.

          ++
          ++ ++
          ++
          ++data
          ++

          The name of a module-level variable or constant.

          ++
          ++ ++
          ++
          ++const
          ++

          The name of a “defined” constant. This may be a C-language #define ++or a Python variable that is not intended to be changed.

          ++
          ++ ++
          ++
          ++class
          ++

          A class name; a dotted name may be used.

          ++
          ++ ++
          ++
          ++meth
          ++

          The name of a method of an object. The role text should include the type ++name and the method name. A dotted name may be used.

          ++
          ++ ++
          ++
          ++attr
          ++

          The name of a data attribute of an object.

          ++
          ++ ++
          ++
          ++exc
          ++

          The name of an exception. A dotted name may be used.

          ++
          ++ ++

          The name enclosed in this markup can include a module name and/or a class name. ++For example, :func:`filter` could refer to a function named filter in ++the current module, or the built-in function of that name. In contrast, ++:func:`foo.filter` clearly refers to the filter function in the foo ++module.

          ++

          Normally, names in these roles are searched first without any further ++qualification, then with the current module name prepended, then with the ++current module and class name (if any) prepended. If you prefix the name with a ++dot, this order is reversed. For example, in the documentation of the ++codecs module, :func:`open` always refers to the built-in function, ++while :func:`.open` refers to codecs.open().

          ++

          A similar heuristic is used to determine whether the name is an attribute of ++the currently documented class.

          ++

          The following roles create cross-references to C-language constructs if they ++are defined in the API documentation:

          ++
          ++
          ++c:data
          ++

          The name of a C-language variable.

          ++
          ++ ++
          ++
          ++c:func
          ++

          The name of a C-language function. Should include trailing parentheses.

          ++
          ++ ++
          ++
          ++c:macro
          ++

          The name of a “simple” C macro, as defined above.

          ++
          ++ ++
          ++
          ++c:type
          ++

          The name of a C-language type.

          ++
          ++ ++
          ++
          ++c:member
          ++

          The name of a C type member, as defined above.

          ++
          ++ ++

          The following role does possibly create a cross-reference, but does not refer ++to objects:

          ++
          ++
          ++token
          ++

          The name of a grammar token (used in the reference manual to create links ++between production displays).

          ++
          ++ ++

          The following role creates a cross-reference to the term in the glossary:

          ++
          ++
          ++term
          ++

          Reference to a term in the glossary. The glossary is created using the ++glossary directive containing a definition list with terms and ++definitions. It does not have to be in the same file as the term ++markup, in fact, by default the Python docs have one global glossary ++in the glossary.rst file.

          ++

          If you use a term that’s not explained in a glossary, you’ll get a warning ++during build.

          ++
          ++ ++
          ++

          The following roles don’t do anything special except formatting the text ++in a different style:

          ++
          ++
          ++command
          ++

          The name of an OS-level command, such as rm.

          ++
          ++ ++
          ++
          ++dfn
          ++

          Mark the defining instance of a term in the text. (No index entries are ++generated.)

          ++
          ++ ++
          ++
          ++envvar
          ++

          An environment variable. Index entries are generated.

          ++
          ++ ++
          ++
          ++file
          ++

          The name of a file or directory. Within the contents, you can use curly ++braces to indicate a “variable” part, for example:

          ++
          ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
++
          ++
          ++

          In the built documentation, the x will be displayed differently to ++indicate that it is to be replaced by the Python minor version.

          ++
          ++ ++
          ++
          ++guilabel
          ++

          Labels presented as part of an interactive user interface should be marked ++using guilabel. This includes labels from text-based interfaces such as ++those created using curses or other text-based libraries. Any label ++used in the interface should be marked with this role, including button ++labels, window titles, field names, menu and menu selection names, and even ++values in selection lists.

          ++
          ++ ++
          ++
          ++kbd
          ++

          Mark a sequence of keystrokes. What form the key sequence takes may depend ++on platform- or application-specific conventions. When there are no relevant ++conventions, the names of modifier keys should be spelled out, to improve ++accessibility for new users and non-native speakers. For example, an ++xemacs key sequence may be marked like :kbd:`C-x C-f`, but without ++reference to a specific application or platform, the same sequence should be ++marked as :kbd:`Control-x Control-f`.

          ++
          ++ ++
          ++
          ++keyword
          ++

          The name of a Python keyword. Using this role will generate a link to the ++documentation of the keyword. True, False and None do not use ++this role, but simple code markup (``True``), given that they’re ++fundamental to the language and should be known to any programmer.

          ++
          ++ ++
          ++
          ++mailheader
          ++

          The name of an RFC 822-style mail header. This markup does not imply that ++the header is being used in an email message, but can be used to refer to any ++header of the same “style.” This is also used for headers defined by the ++various MIME specifications. The header name should be entered in the same ++way it would normally be found in practice, with the camel-casing conventions ++being preferred where there is more than one common usage. For example: ++:mailheader:`Content-Type`.

          ++
          ++ ++
          ++
          ++makevar
          ++

          The name of a make variable.

          ++
          ++ ++
          ++
          ++manpage
          ++

          A reference to a Unix manual page including the section, ++e.g. :manpage:`ls(1)`.

          ++
          ++ ++
          ++
          ++menuselection
          ++

          Menu selections should be marked using the menuselection role. This is ++used to mark a complete sequence of menu selections, including selecting ++submenus and choosing a specific operation, or any subsequence of such a ++sequence. The names of individual selections should be separated by ++-->.

          ++

          For example, to mark the selection “Start > Programs”, use this markup:

          ++
          :menuselection:`Start --> Programs`
++
          ++
          ++

          When including a selection that includes some trailing indicator, such as the ++ellipsis some operating systems use to indicate that the command opens a ++dialog, the indicator should be omitted from the selection name.

          ++
          ++ ++
          ++
          ++mimetype
          ++

          The name of a MIME type, or a component of a MIME type (the major or minor ++portion, taken alone).

          ++
          ++ ++
          ++
          ++newsgroup
          ++

          The name of a Usenet newsgroup.

          ++
          ++ ++
          ++
          ++option
          ++

          A command-line option of Python. The leading hyphen(s) must be included. ++If a matching cmdoption directive exists, it is linked to. For options ++of other programs or scripts, use simple ``code`` markup.

          ++
          ++ ++
          ++
          ++program
          ++

          The name of an executable program. This may differ from the file name for ++the executable for some platforms. In particular, the .exe (or other) ++extension should be omitted for Windows programs.

          ++
          ++ ++
          ++
          ++regexp
          ++

          A regular expression. Quotes should not be included.

          ++
          ++ ++
          ++
          ++samp
          ++

          A piece of literal text, such as code. Within the contents, you can use ++curly braces to indicate a “variable” part, as in :file:.

          ++

          If you don’t need the “variable part” indication, use the standard ++``code`` instead.

          ++
          ++ ++

          The following roles generate external links:

          ++
          ++
          ++pep
          ++

          A reference to a Python Enhancement Proposal. This generates appropriate ++index entries. The text “PEP number” is generated; in the HTML output, ++this text is a hyperlink to an online copy of the specified PEP.

          ++
          ++ ++
          ++
          ++rfc
          ++

          A reference to an Internet Request for Comments. This generates appropriate ++index entries. The text “RFC number” is generated; in the HTML output, ++this text is a hyperlink to an online copy of the specified RFC.

          ++
          ++ ++

          Note that there are no special roles for including hyperlinks as you can use ++the standard reST markup for that purpose.

          ++
          ++
          ++

          8.4.6. Cross-linking markup

          ++

          To support cross-referencing to arbitrary sections in the documentation, the ++standard reST labels are “abused” a bit: Every label must precede a section ++title; and every label name must be unique throughout the entire documentation ++source.

          ++

          You can then reference to these sections using the :ref:`label-name` role.

          ++

          Example:

          ++
          .. _my-reference-label:
++
++Section to cross-reference
++--------------------------
++
++This is the text of the section.
++
++It refers to the section itself, see :ref:`my-reference-label`.
++
          ++
          ++

          The :ref: invocation is replaced with the section title.

          ++

          Alternatively, you can reference any label (not just section titles) ++if you provide the link text :ref:`link text <reference-label>`.

          ++
          ++
          ++

          8.4.7. Paragraph-level markup

          ++

          These directives create short paragraphs and can be used inside information ++units as well as normal text:

          ++
          ++
          ++note
          ++

          An especially important bit of information about an API that a user should be ++aware of when using whatever bit of API the note pertains to. The content of ++the directive should be written in complete sentences and include all ++appropriate punctuation.

          ++

          Example:

          ++
          .. note::
++
++   This function is not suitable for sending spam e-mails.
++
          ++
          ++
          ++ ++
          ++
          ++warning
          ++

          An important bit of information about an API that a user should be aware of ++when using whatever bit of API the warning pertains to. The content of the ++directive should be written in complete sentences and include all appropriate ++punctuation. In the interest of not scaring users away from pages filled ++with warnings, this directive should only be chosen over note for ++information regarding the possibility of crashes, data loss, or security ++implications.

          ++
          ++ ++
          ++
          ++versionadded
          ++

          This directive documents the version of Python which added the described ++feature, or a part of it, to the library or C API. When this applies to an ++entire module, it should be placed at the top of the module section before ++any prose.

          ++

          The first argument must be given and is the version in question; if the ++addition is only part of the described API element, you should add a second ++argument consisting of a brief explanation of the change.

          ++

          Example:

          ++
          .. versionadded:: 3.1
++   The *spam* parameter.
++
          ++
          ++

          Note that there must be no blank line between the directive head and the ++explanation; this is to make these blocks visually continuous in the markup.

          ++
          ++ ++
          ++
          ++versionchanged
          ++

          Similar to versionadded, but describes when and what changed in the named ++feature in some way (changed side effects, platform support, etc.). This one ++must have the second argument (explanation of the change).

          ++
          ++ ++
          ++
          ++
          ++impl-detail
          ++

          This directive is used to mark CPython-specific information. Use either with ++a block content or a single sentence as an argument, i.e. either

          ++
          .. impl-detail::
++
++   This describes some implementation detail.
++
++   More explanation.
++
          ++
          ++

          or

          ++
          .. impl-detail:: This shortly mentions an implementation detail.
++
          ++
          ++

          “CPython implementation detail:” is automatically prepended to the ++content.

          ++
          ++ ++
          ++
          ++seealso
          ++

          Many sections include a list of references to module documentation or ++external documents. These lists are created using the seealso directive.

          ++

          The seealso directive is typically placed in a section just before any ++sub-sections. For the HTML output, it is shown boxed off from the main flow ++of the text.

          ++

          The content of the seealso directive should be a reST definition list. ++Example:

          ++
          .. seealso::
++
++   Module :mod:`zipfile`
++      Documentation of the :mod:`zipfile` standard module.
++
++   `GNU tar manual, Basic Tar Format <http://link>`_
++      Documentation for tar archive files, including GNU tar extensions.
++
          ++
          ++
          ++ ++
          ++
          ++rubric
          ++

          This directive creates a paragraph heading that is not used to create a ++table of contents node. It is currently used for the “Footnotes” caption.

          ++
          ++ ++
          ++
          ++centered
          ++

          This directive creates a centered boldfaced paragraph. Use it as follows:

          ++
          .. centered::
++
++   Paragraph contents.
++
          ++
          ++
          ++ ++
          ++
          ++

          8.4.8. Table-of-contents markup

          ++

          Since reST does not have facilities to interconnect several documents, or split ++documents into multiple output files, Sphinx uses a custom directive to add ++relations between the single files the documentation is made of, as well as ++tables of contents. The toctree directive is the central element.

          ++
          ++
          ++toctree
          ++

          This directive inserts a “TOC tree” at the current location, using the ++individual TOCs (including “sub-TOC trees”) of the files given in the ++directive body. A numeric maxdepth option may be given to indicate the ++depth of the tree; by default, all levels are included.

          ++

          Consider this example (taken from the library reference index):

          ++
          .. toctree::
++   :maxdepth: 2
++
++   intro
++   strings
++   datatypes
++   numeric
++   (many more files listed here)
++
          ++
          ++

          This accomplishes two things:

          ++
            ++
          • Tables of contents from all those files are inserted, with a maximum depth ++of two, that means one nested heading. toctree directives in those ++files are also taken into account.
            • ++
          • Sphinx knows that the relative order of the files intro, ++strings and so forth, and it knows that they are children of the ++shown file, the library index. From this information it generates “next ++chapter”, “previous chapter” and “parent chapter” links.
            • ++
          ++

          In the end, all files included in the build process must occur in one ++toctree directive; Sphinx will emit a warning if it finds a file that is ++not included, because that means that this file will not be reachable through ++standard navigation.

          ++

          The special file contents.rst at the root of the source directory is the ++“root” of the TOC tree hierarchy; from it the “Contents” page is generated.

          ++
          ++ ++
          ++
          ++

          8.4.9. Index-generating markup

          ++

          Sphinx automatically creates index entries from all information units (like ++functions, classes or attributes) like discussed before.

          ++

          However, there is also an explicit directive available, to make the index more ++comprehensive and enable index entries in documents where information is not ++mainly contained in information units, such as the language reference.

          ++

          The directive is index and contains one or more index entries. Each entry ++consists of a type and a value, separated by a colon.

          ++

          For example:

          ++
          .. index::
++   single: execution; context
++   module: __main__
++   module: sys
++   triple: module; search; path
++
          ++
          ++

          This directive contains five entries, which will be converted to entries in the ++generated index which link to the exact location of the index statement (or, in ++case of offline media, the corresponding page number).

          ++

          The possible entry types are:

          ++
          ++
          single
          ++
          Creates a single index entry. Can be made a subentry by separating the ++subentry text with a semicolon (this notation is also used below to describe ++what entries are created).
          ++
          pair
          ++
          pair: loop; statement is a shortcut that creates two index entries, ++namely loop; statement and statement; loop.
          ++
          triple
          ++
          Likewise, triple: module; search; path is a shortcut that creates three ++index entries, which are module; search path, search; path, module and ++path; module search.
          ++
          module, keyword, operator, object, exception, statement, builtin
          ++
          These all create two index entries. For example, module: hashlib ++creates the entries module; hashlib and hashlib; module. The ++builtin entry type is slightly different in that “built-in function” is used ++in place of “builtin” when creating the two entries.
          ++
          ++

          For index directives containing only “single” entries, there is a shorthand ++notation:

          ++
          .. index:: BNF, grammar, syntax, notation
++
          ++
          ++

          This creates four index entries.

          ++
          ++
          ++

          8.4.10. Grammar production displays

          ++

          Special markup is available for displaying the productions of a formal grammar. ++The markup is simple and does not attempt to model all aspects of BNF (or any ++derived forms), but provides enough to allow context-free grammars to be ++displayed in a way that causes uses of a symbol to be rendered as hyperlinks to ++the definition of the symbol. There is this directive:

          ++
          ++
          ++productionlist
          ++

          This directive is used to enclose a group of productions. Each production is ++given on a single line and consists of a name, separated by a colon from the ++following definition. If the definition spans multiple lines, each ++continuation line must begin with a colon placed at the same column as in the ++first line.

          ++

          Blank lines are not allowed within productionlist directive arguments.

          ++

          The definition can contain token names which are marked as interpreted text ++(e.g. unaryneg ::= "-" `integer`) – this generates cross-references ++to the productions of these tokens.

          ++

          Note that no further reST parsing is done in the production, so that you ++don’t have to escape * or | characters.

          ++
          ++ ++

          The following is an example taken from the Python Reference Manual:

          ++
          .. productionlist::
++   try_stmt: try1_stmt | try2_stmt
++   try1_stmt: "try" ":" `suite`
++            : ("except" [`expression` ["," `target`]] ":" `suite`)+
++            : ["else" ":" `suite`]
++            : ["finally" ":" `suite`]
++   try2_stmt: "try" ":" `suite`
++            : "finally" ":" `suite`
++
          ++
          ++
          ++
          ++

          8.4.11. Substitutions

          ++

          The documentation system provides three substitutions that are defined by default. ++They are set in the build configuration file conf.py.

          ++
          ++
          ++|release|
          ++

          Replaced by the Python release the documentation refers to. This is the full ++version string including alpha/beta/release candidate tags, e.g. 2.5.2b3.

          ++
          ++ ++
          ++
          ++|version|
          ++

          Replaced by the Python version the documentation refers to. This consists ++only of the major and minor version parts, e.g. 2.5, even for version ++2.5.1.

          ++
          ++ ++
          ++
          ++|today|
          ++

          Replaced by either today’s date, or the date set in the build configuration ++file. Normally has the format April 14, 2007.

          ++
          ++ ++

          Footnotes

          ++ ++ ++ ++ ++ ++
          [1]There is a standard .. include directive, but it raises errors if the ++file is not found. This one only emits a warning.
          ++
          ++
          ++
          ++

          8.5. Building the documentation

          ++

          The toolset used to build the docs is written in Python and is called Sphinx. ++Sphinx is maintained separately and is not included in this tree. Also needed ++are docutils, supplying the base markup that Sphinx uses; Jinja, a templating ++engine; and optionally Pygments, a code highlighter.

          ++

          To build the documentation, follow the instructions from one of the sections ++below. You can view the documentation after building the HTML by pointing ++a browser at the file Doc/build/html/index.html.

          ++

          In the Python 2.7 and 3.3 branches, the Sphinx toolchain will be checked out ++using Subversion from svn.python.org by the Makefile. This toolchain will ++need an installed Python 2 to run.

          ++

          In the Python 3.4 and later branches, you are expected to have installed a ++recent version of Sphinx on your system, so that the Makefile can find the ++sphinx-build command.

          ++
          ++

          8.5.1. Using make / make.bat

          ++

          On Unix, run the following from the root of your repository clone:

          ++
          cd Doc
++make html
++
          ++
          ++

          or alternatively make -C Doc html. This builds the output as HTML.

          ++

          For Windows users there is a make.bat batchfile that tries to work like ++make does.

          ++

          Available make targets are:

          ++
          ++
            ++

          • “html”, which builds standalone HTML files for offline viewing.

            ++
            • ++

          • “htmlhelp”, which builds HTML files and a HTML Help project file usable to ++convert them into a single Compiled HTML (.chm) file – these are popular ++under Microsoft Windows, but very handy on every platform.

            ++

            To create the CHM file, you need to run the Microsoft HTML Help Workshop ++over the generated project (.hhp) file.

            ++
            • ++

          • “latex”, which builds LaTeX source files as input to “pdflatex” to produce ++PDF documents.

            ++
            • ++

          • “text”, which builds a plain text file for each source file.

            ++
            • ++

          • “linkcheck”, which checks all external references to see whether they are ++broken, redirected or malformed, and outputs this information to stdout ++as well as a plain-text (.txt) file.

            ++
            • ++

          • “changes”, which builds an overview over all versionadded/versionchanged/ ++deprecated items in the current version. This is meant as a help for the ++writer of the “What’s New” document.

            ++
            • ++

          • “coverage”, which builds a coverage overview for standard library modules ++and C API.

            ++
            • ++

          • “pydoc-topics”, which builds a Python module containing a dictionary with ++plain text documentation for the labels defined in ++Doc/tools/sphinxext/pyspecific.py – pydoc needs these to show topic ++and keyword help.

            ++
            • ++

          • “suspicious”, which checks the parsed markup for text that looks like ++malformed and thus unconverted reST.

            ++
            • ++
          ++
          ++
          ++
          ++

          8.5.2. Without make

          ++

          Install the Sphinx package and its dependencies from PyPI.

          ++

          Then, from the Docs directory, run

          ++
          sphinx-build -b<builder> . build/<builder>
++
          ++
          ++

          where <builder> is one of html, text, latex, or htmlhelp (for explanations ++see the make targets above).

          ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          7. Helping with Documentation

          ++

          Next topic

          ++

          9. Silence Warnings From the Test Suite

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/emacs.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/emacs.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,123 @@ ++ ++ ++ ++ ++ ++ ++ ++ 23. Emacs support — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          23. Emacs support

          ++

          If you want to edit Python code in Emacs, you should download python-mode.el ++and install it somewhere on your load-path. See the project page to download: ++https://launchpad.net/python-mode

          ++

          While Emacs comes with a python.el file, it is not recommended. ++python-mode.el is maintained by core Python developers and is generally ++considered more Python programmer friendly. For example, python-mode.el ++includes a killer feature called pdbtrack which allows you to set a pdb ++breakpoint in your code, run your program in an Emacs shell buffer, and do gud ++style debugging when the breakpoint is hit.

          ++

          python-mode.el is compatible with both GNU Emacs from the FSF, and XEmacs.

          ++

          For more information and bug reporting, see the above project page. For help, ++development, or discussions, see the python-mode mailing list: ++http://mail.python.org/mailman/listinfo/python-mode

          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Previous topic

          ++

          22. Experts Index

          ++

          Next topic

          ++

          24. gdb Support

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/experts.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/experts.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,1002 @@ ++ ++ ++ ++ ++ ++ ++ ++ 22. Experts Index — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          22. Experts Index

          ++

          This document has tables that list Python Modules, Tools, Platforms and ++Interest Areas and names for each item that indicate a maintainer or an ++expert in the field. This list is intended to be used by issue submitters, ++issue triage people, and other issue participants to find people to add to ++the nosy list or to contact directly by email for help and decisions on ++feature requests and bug fixes. People on this list may be asked to render ++final judgement on a feature or bug. If no active maintainer is listed for ++a given module, then questionable changes should go to python-dev, while ++any other issues can and should be decided by any committer.

          ++

          Unless a name is followed by a ‘*’, you should never assign an issue to ++that person, only make them nosy. Names followed by a ‘*’ may be assigned ++issues involving the module or topic.

          ++

          The Platform and Interest Area tables list broader fields in which various ++people have expertise. These people can also be contacted for help, ++opinions, and decisions when issues involve their areas.

          ++

          If a listed maintainer does not respond to requests for comment for an ++extended period (three weeks or more), they should be marked as inactive ++in this list by placing the word ‘inactive’ in parenthesis behind their ++tracker id. They are of course free to remove that inactive mark at ++any time.

          ++

          Committers should update these tables as their areas of expertise widen. ++New topics may be added to the Interest Area table at will.

          ++

          The existence of this list is not meant to indicate that these people ++must be contacted for decisions; it is, rather, a resource to be used ++by non-committers to find responsible parties, and by committers who do ++not feel qualified to make a decision in a particular context.

          ++

          See also PEP 291 and PEP 360 for information about certain modules ++with special rules.

          ++
          ++

          22.1. Stdlib

          ++ ++++++++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ModuleMaintainers
          __future__ 
          __main__gvanrossum, ncoghlan
          _dummy_threadbrett.cannon
          _threadpitrou
          abc 
          aifcr.david.murray
          argparsebethard
          array 
          astbenjamin.peterson
          asynchatjosiahcarlson, giampaolo.rodola, stutzbach
          asynciogvanrossum, haypo, pitrou, yselivanov
          asyncorejosiahcarlson, giampaolo.rodola, stutzbach
          atexit 
          audioop 
          base64 
          bdb 
          binascii 
          binhex 
          bisectrhettinger
          builtins 
          bz2nadeem.vawda
          calendarrhettinger
          cgi 
          cgitb 
          chunk 
          cmathmark.dickinson
          cmd 
          code 
          codecslemburg, doerwalter
          codeop 
          collectionsrhettinger
          collections.abcrhettinger, stutzbach
          colorsys 
          compileall 
          concurrent.futuresbquinlan
          configparserlukasz.langa*
          contextlibncoghlan*
          copyalexandre.vassalotti
          copyregalexandre.vassalotti
          cProfile 
          cryptjafo*
          csvskip.montanaro (inactive)
          ctypestheller (inactive), belopolsky, amaury.forgeotdarc, ++meador.inge
          curses 
          datetimebelopolsky
          dbm 
          decimalfacundobatista, rhettinger, mark.dickinson
          difflibtim.peters (inactive)
          disncoghlan*
          distutilseric.araujo
          doctesttim.peters (inactive)
          dummy_threadingbrett.cannon
          emailbarry, r.david.murray*
          encodingslemburg, loewis
          enumeli.bendersky*, barry, ethan.furman*
          errno 
          exceptions 
          fcntl 
          filecmp 
          fileinput 
          fnmatch 
          formatter 
          fpectl 
          fractionsmark.dickinson, rhettinger
          ftplibgiampaolo.rodola
          functoolsncoghlan, rhettinger
          gcpitrou
          getopt 
          getpass 
          gettextloewis
          glob 
          grp 
          gzip 
          hashlibchristian.heimes, gregory.p.smith
          heapqrhettinger, stutzbach
          hmacchristian.heimes, gregory.p.smith
          htmlezio.melotti
          http 
          idlelibkbk, terry.reedy, roger.serwy
          imaplib 
          imghdr 
          imp 
          importlibbrett.cannon
          inspectyselivanov
          iopitrou, benjamin.peterson, stutzbach
          ipaddresspmoody, ncoghlan
          itertoolsrhettinger
          jsonbob.ippolito (inactive), ezio.melotti, rhettinger, pitrou
          keyword 
          lib2to3benjamin.peterson
          linecache 
          localeloewis, lemburg
          loggingvinay.sajip
          lzmanadeem.vawda
          macpath 
          mailboxpetri.lehtinen
          mailcap 
          marshal 
          mathmark.dickinson, rhettinger, stutzbach
          mimetypes 
          mmap 
          modulefindertheller (inactive), jvr
          msilibloewis
          msvcrt 
          multiprocessingjnoller, sbt*
          netrc 
          nis 
          nntplibpitrou
          numbers 
          operator 
          optparsearonacher
          osloewis
          ossaudiodev 
          parserbenjamin.peterson
          pathlibpitrou*
          pdbgeorg.brandl*
          picklealexandre.vassalotti, pitrou
          pickletoolsalexandre.vassalotti
          pipes 
          pkgutil 
          platformlemburg
          plistlib 
          poplibgiampaolo.rodola
          posix 
          pprintfdrake
          profilegeorg.brandl
          pstatsgeorg.brandl
          pty 
          pwd 
          py_compile 
          pybenchlemburg, pitrou
          pyclbr 
          pydoc 
          queuerhettinger
          quopri 
          randomrhettinger, mark.dickinson
          reeffbot (inactive), pitrou, ezio.melotti
          readline 
          reprlib 
          resource 
          rlcompleter 
          runpyncoghlan
          schedgiampaolo.rodola
          select 
          selectors 
          shelve 
          shlex 
          shutiltarek, hynek
          signal 
          site 
          smtpdgiampaolo.rodola
          smtplib 
          sndhdr 
          socketpitrou
          socketserver 
          spwd 
          sqlite3ghaering
          ssljanssen, pitrou, giampaolo.rodola, christian.heimes
          statchristian.heimes
          statistics 
          stringgeorg.brandl*
          stringprep 
          structmark.dickinson, meador.inge
          subprocessastrand (inactive)
          sunau 
          symbol 
          symtablebenjamin.peterson
          sys 
          sysconfigtarek
          syslogjafo*
          tabnannytim.peters (inactive)
          tarfilelars.gustaebel
          telnetlib 
          tempfilegeorg.brandl, ncoghlan
          termios 
          testezio.melotti
          textwrapgeorg.brandl
          threadingpitrou
          timebelopolsky
          timeitgeorg.brandl
          tkintergpolo
          tokengeorg.brandl
          tokenizemeador.inge
          tracebelopolsky
          tracebackgeorg.brandl*
          tty 
          turtlegregorlingl
          types 
          unicodedataloewis, lemburg, ezio.melotti
          unittestmichael.foord*, ezio.melotti
          unittest.mockmichael.foord*
          urlliborsenthil
          uu 
          uuid 
          venvvinay.sajip
          warnings 
          wave 
          weakreffdrake, pitrou
          webbrowsergeorg.brandl
          winregstutzbach
          winsoundeffbot (inactive)
          wsgirefpje
          xdrlib 
          xml.dom 
          xml.dom.minidom 
          xml.dom.pulldom 
          xml.etreeeffbot (inactive), eli.bendersky*, scoder
          xml.parsers.expatchristian.heimes
          xml.saxchristian.heimes
          xml.sax.handler 
          xml.sax.saxutils 
          xml.sax.xmlreader 
          xmlrpcloewis
          zipfilealanmcintyre
          zipimport 
          zlibnadeem.vawda
          ++
          ++
          ++

          22.2. Tools

          ++ ++++++++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ToolMaintainers
          pybenchlemburg
          ++
          ++
          ++

          22.3. Platforms

          ++ ++++++++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          PlatformMaintainers
          AIXDavid.Edelsohn
          Cygwinjlt63, stutzbach
          FreeBSD 
          HP-UX 
          Linux 
          Mac OS Xronaldoussoren, ned.deily, hynek
          NetBSD1 
          OS2/EMXaimacintyre
          Solaris/OpenIndianajcea
          Windowstim.golden
          JVM/Javafrank.wierzbicki
          ++
          ++
          ++

          22.4. Miscellaneous

          ++ ++++++++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          Interest AreaMaintainers
          algorithms 
          ast/compilerncoghlan, benjamin.peterson, brett.cannon, georg.brandl
          autoconf/makefiles 
          bsd 
          benchmarkspitrou, brett.cannon
          bug trackerezio.melotti
          buildbotspitrou
          bytecodebenjamin.peterson, pitrou, georg.brandl
          context managersncoghlan
          coverity scanchristian.heimes, brett.cannon
          cryptographychristian.heimes, gregory.p.smith
          data formatsmark.dickinson, georg.brandl
          databaselemburg
          devguidencoghlan, eric.araujo, ezio.melotti
          documentationgeorg.brandl, ezio.melotti, eric.araujo
          GUI 
          i18nlemburg, eric.araujo
          import machinerybrett.cannon, ncoghlan, eric.snow
          iopitrou, benjamin.peterson, stutzbach, hynek
          localelemburg, loewis
          mathematicsmark.dickinson, eric.smith, lemburg, stutzbach
          memory managementtim.peters, lemburg
          networkinggiampaolo.rodola, pitrou
          object modelbenjamin.peterson
          packagingtarek, lemburg, alexis, eric.araujo
          py3 transitionbenjamin.peterson
          release managementtarek, lemburg, benjamin.peterson, barry, loewis, ++gvanrossum, anthonybaxter, eric.araujo, ned.deily, ++georg.brandl
          str.formateric.smith
          testingmichael.foord, pitrou, ezio.melotti
          test coveragencoghlan, giampaolo.rodola, christian.heimes
          threadspitrou
          time and dateslemburg, belopolsky
          unicodelemburg, ezio.melotti, haypo, benjamin.peterson, pitrou
          version controleric.araujo, georg.brandl, ezio.melotti
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          21. Changing the Python Language

          ++

          Next topic

          ++

          23. Emacs support

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/faq.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/faq.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,972 @@ ++ ++ ++ ++ ++ ++ ++ ++ 29. Python Developer FAQ — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          29. Python Developer FAQ

          ++
          ++ ++
          ++
          ++

          29.1. Communications

          ++
          ++

          29. Where should I ask general Python questions?

          ++

          General Python questions should still go to python-list or tutor ++or similar resources, such as StackOverflow or the #python IRC channel ++on Freenode.

          ++
          ++
          ++

          29. Where should I suggest new features and language changes?

          ++

          The python-ideas mailing list is specifically intended for discussion of ++new features and language changes. Please don’t be disappointed if your ++idea isn’t met with universal approval: as the long list of Rejected and ++Withdrawn PEPs in the PEP Index attests, and as befits a reasonably mature ++programming language, getting significant changes into Python isn’t a simple ++task.

          ++

          If the idea is reasonable, someone will suggest posting it as a feature ++request on the issue tracker, or, for larger changes, writing it up as ++a draft PEP.

          ++

          Sometimes core developers will differ in opinion, or merely be collectively ++unconvinced. When there isn’t an obvious victor then the ++Status Quo Wins a Stalemate as outlined in the linked post.

          ++

          For some examples on language changes that were accepted please read ++Justifying Python Language Changes.

          ++

          See also the Changing the Python Language section of this guide.

          ++
          ++
          ++

          29. Where should I ask general questions about contributing to CPython?

          ++

          The Python Mentors program is specifically about encouraging ++developers and others that would like to contribute to Python development in ++general, rather than necessarily being focused on one particular issue. ++Some core developers are also available on the #python-dev IRC channel on ++Freenode.

          ++
          ++
          ++

          29. Where should I report specific problems?

          ++

          Specific problems should be posted to the issue tracker.

          ++
          ++
          ++

          29. What if I’m not sure it is a bug?

          ++

          The general Python help locations listed above are the best place to start ++with that kind of question. If they agree it looks like a bug, then the ++next step is to either post it to the issue tracker or else to ask further ++on the core development mailing list, python-dev.

          ++
          ++
          ++

          29. What if I disagree with an issue resolution on the tracker?

          ++

          First, take some time to consider any comments made in association with the ++resolution of the tracker issue. On reflection, they may seem more reasonable ++than they first appeared.

          ++

          If you still feel the resolution is incorrect, then raise the question on ++python-dev. If the consensus there supports the disputed resolution, please ++take any further objections to python-ideas (or some other forum). Further ++argument on python-dev after a consensus has been reached amongst the core ++developers is unlikely to win any converts.

          ++
          ++
          ++

          29. How do I tell who is and isn’t a core developer?

          ++

          You can check their name against the full list of developers with commit ++rights to the main source control repository.

          ++

          On the issue tracker, most core developers will have the Python logo ++appear next to their name.

          ++
          ++
          ++

          29. What standards of behaviour are expected in these communication channels?

          ++

          We try to foster environments of mutual respect, tolerance and encouragement, ++as described in the PSF’s Diversity Statement. Abiding by the guidelines ++in this document and asking questions or posting suggestions in the ++appropriate channels are an excellent way to get started on the mutual respect ++part, greatly increasing the chances of receiving tolerance and encouragement ++in return.

          ++
          ++
          ++
          ++

          29.2. Version Control

          ++
          ++

          29. For everyone

          ++

          The following FAQs are intended for both core developers and contributors.

          ++
          ++

          29. Where can I learn about the version control system used, Mercurial (hg)?

          ++

          Mercurial‘s (also known as hg) official web site is at ++http://mercurial.selenic.com/. A book on Mercurial published by ++O’Reilly Media, Mercurial: The Definitive Guide, is available ++for free online. Another resource is Hg Init: a Mercurial tutorial ++by Joel Spolsky.

          ++

          With Mercurial installed, you can run the help tool that comes with ++Mercurial to get help:

          ++
          hg help
++
          ++
          ++

          The man page for hg provides a quick refresher on the details of ++various commands, but doesn’t provide any guidance on overall ++workflow.

          ++
          ++
          ++

          29. I already know how to use Git, can I use that instead?

          ++

          While the main workflow for core developers requires Mercurial, if ++you just want to generate patches with git diff and post them to the ++issue tracker, Petri Lehtinen maintains a git mirror of the main ++CPython repository. To create a local clone based on this mirror rather ++than the main repository:

          ++
          git clone git://github.com/akheron/cpython
++
          ++
          ++

          The mirror’s master branch tracks the main repository’s default branch, ++while the maintenance branch names (2.7, 3.3, etc) are mapped ++directly.

          ++

          Please only use this approach if you’re already an experienced Git user and ++don’t require assistance with the specifics of version control commands. All ++other parts of this developer’s guide assume the use of Mercurial for local ++version control.

          ++
          ++
          ++

          29. What do I need to use Mercurial?

          ++
          ++
          29. UNIX
          ++

          First, you need to download Mercurial. Most UNIX-based operating systems ++have binary packages available. Most package management systems also ++have native Mercurial packages available.

          ++

          If you have push rights, you need OpenSSH. This is needed to verify ++your identity when performing commits. As with Mercurial, binary packages ++are typically available either online or through the platform’s package ++management system.

          ++

          Mercurial does not use its own compression via SSH ++because it is better to enable compression at the SSH level. Enabling ++SSH compression can make cloning a remote repository much faster. ++You can configure it in your ~/.ssh/config file; for example:

          ++
          Host hg.python.org
++  Compression yes
++
          ++
          ++
          ++
          ++
          29. Windows
          ++

          The recommended option on Windows is to download TortoiseHg which ++integrates with Windows Explorer and also bundles the command line client ++(meaning you can type hg in a DOS box). Note that most ++entries in this FAQ only cover the command line client in detail - refer ++to the TortoiseHg documentation for assistance with its graphical interface.

          ++

          If you have push rights, you need to configure Mercurial to work with ++your SSH keys. For that, open your Mercurial configuration file ++(you can do so by opening the TortoiseHg Global Settings dialog and then ++clicking “Edit File”). If there is no [ui] section, create it by ++typing just that on a line by itself. Then add the following line:

          ++
          ssh = TortoisePlink.exe -ssh -2 -C -i C:\path\to\yourkey.ppk
++
          ++
          ++

          where C:\path\to\yourkey.ppk should be replaced with the actual path ++to your SSH private key.

          ++
          ++

          Note

          ++

          If your private key is in OpenSSH format, you must first convert it to ++PuTTY format by loading it into PuTTYgen.

          ++
          ++
          ++
          ++
          ++

          29. What’s a working copy? What’s a repository?

          ++

          Mercurial is a “distributed” version control system. This means that each ++participant, even casual contributors, download a complete copy (called a ++clone, since it is obtained by calling hg clone) of the central ++repository which can be treated as a stand-alone repository for all purposes. ++That copy is called in the FAQ the local repository, to differentiate ++with any remote repository you might also interact with.

          ++

          But you don’t modify files directly in the local repository; Mercurial doesn’t ++allow for it. You modify files in what’s called the working copy associated ++with your local repository: you also run compilations and tests there. ++Once you are satisfied with your changes, you can commit them; ++committing records the changes as a new revision in the local repository.

          ++

          Changes in your local repository don’t get automatically shared with the ++rest of the world. Mercurial ensures that you have to do so explicitly ++(this allows you to experiment quite freely with multiple branches of ++development, all on your private computer). The main commands for doing ++so are hg pull and hg push.

          ++
          ++
          ++

          29. Which branches are in my local repository?

          ++

          Typing hg branches displays the open branches in your local repository:

          ++
          $ hg branches
++default                    86781:52ec6a3eeda5
++2.7                        86776:dd12639b82bf
++3.3                        86779:544b654d000c (inactive)
++3.2                        86778:dda1a32748e0 (inactive)
++3.1                        86777:b1ddcb220a7f (inactive)
++
          ++
          ++
          ++
          ++

          29. Why are some branches marked “inactive”?

          ++

          Assuming you get the following output:

          ++
          $ hg branches
++default                    68042:8ff33af017ef
++3.3                        68039:c17d7772c638 (inactive)
++
          ++
          ++

          This means all changesets in the “3.3” branch have been merged into the ++“default” branch (or any other branch, if such exists).

          ++
          ++
          ++

          29. Which branch is currently checked out in my working copy?

          ++

          Use:

          ++
          $ hg branch
++default
++
          ++
          ++

          Or to get more information:

          ++
          $ hg summary
++parent: 68026:f12ef116dd10 tip
++ In FTP.close() method, make sure to also close the socket object, not only the file.
++branch: default
++commit: (clean)
++update: (current)
++
          ++
          ++
          ++
          ++

          29. How do I switch between branches inside my working copy?

          ++

          Simply use hg update to checkout another branch in the current directory:

          ++
          $ hg branch
++default
++$ hg update 3.3
++86 files updated, 0 files merged, 11 files removed, 0 files unresolved
++$ hg branch
++3.3
++
          ++
          ++

          Adding the -v option to hg update will list all updated files.

          ++

          Note that, due to some previously built executables being used as a part of ++the build process, you may sometimes run into issues when attempting to ++switch between Python 2.x and Python 3.x branches. In these cases, it is ++best to run a make distclean to ensure that all previously built files ++are removed.

          ++
          ++
          ++

          29. I want to keep a separate working copy per development branch, is it possible?

          ++

          There are two ways:

          ++
            ++
          1. Use the “share extension” as described in the Multiple Clones Approach ++section;
            2. ++
          2. Create several clones of your local repository;
            3. ++
          ++

          If you want to use the second way, you can do:

          ++
          $ hg clone cpython py33
++updating to branch default
++3434 files updated, 0 files merged, 0 files removed, 0 files unresolved
++$ cd py33
++$ hg update 3.3
++86 files updated, 0 files merged, 11 files removed, 0 files unresolved
++
          ++
          ++

          The current branch in a working copy is “sticky”: if you pull in some new ++changes, hg update will update to the head of the current branch.

          ++
          ++ ++
          ++

          29. How do I create a shorthand alias for a remote repository?

          ++

          In your global .hgrc file add a section similar to the following:

          ++
          [paths]
++dg = ssh://hg@hg.python.org/devguide
++
          ++
          ++

          This example creates a dg alias for the devguide repository ++on hg.python.org. This allows “dg” to be entered instead of the ++full URL for commands taking a repository argument (e.g. hg pull dg or ++hg outgoing dg).

          ++

          Anywhere that <remote repository> is used in the commands in this ++FAQ, hg should accept an alias in place of a complete remote URL.

          ++
          ++
          ++

          29. How do I compare my local repository to a remote repository?

          ++

          To display the list of changes that are in your local repository, but not ++in the remote, use:

          ++
          hg outgoing <remote repository>
++
          ++
          ++

          This is the list of changes that will be sent if you call ++hg push <remote repository>. It does not include any uncommitted ++changes in your working copy!

          ++

          Conversely, for the list of changes that are in the remote repository but ++not in the local, use:

          ++
          hg incoming <remote repository>
++
          ++
          ++

          This is the list of changes that will be retrieved if you call ++hg pull <remote repository>.

          ++
          ++

          Note

          ++

          In most daily use, you will work against the default remote repository, ++and therefore simply type hg outgoing and hg incoming.

          ++

          In this case, you can also get a synthetic summary using ++hg summary --remote.

          ++
          ++
          ++
          ++

          29. How do I update my local repository to be in sync with a remote repository?

          ++

          Run:

          ++
          hg pull <remote repository>
++
          ++
          ++

          from the repository you wish to pull the latest changes into. Most of the ++time, that repository is a clone of the repository you want to pull from, ++so you can simply type:

          ++
          hg pull
++
          ++
          ++

          This doesn’t update your working copy, though. See below:

          ++
          ++
          ++

          29. How do I update my working copy with the latest changes?

          ++

          Do:

          ++
          hg update
++
          ++
          ++

          This will update your working copy with the latest changes on the ++current branch. If you had uncommitted ++changes in your working copy, they will be merged in.

          ++

          If you find yourself typing often hg pull followed by hg update, ++be aware that you can combine them in a single command:

          ++
          hg pull -u
++
          ++
          ++
          ++
          ++

          29. How do I apply a patch?

          ++

          If you want to try out or review a patch generated using Mercurial, do:

          ++
          patch -p1 < somework.patch
++
          ++
          ++

          This will apply the changes in your working copy without committing them. ++If the patch was not created by Mercurial (for example, a patch created by ++Subversion and thus lacking any a/b directory prefixes in the patch), ++replace -p1 with -p0.

          ++

          If the patch contains renames, deletions or copies, and you intend committing ++it after your review, you might prefer using:

          ++
          hg import --no-commit somework.patch
++
          ++
          ++

          If you want to work on the patch using mq (Mercurial Queues), type instead:

          ++
          hg qimport somework.patch
++
          ++
          ++

          This will create a patch in your queue with a name that matches the filename. ++You can use the -n argument to specify a different name. To have the ++patch applied to the working copy, type:

          ++
          hg qpush
++
          ++
          ++

          Finally, to delete the patch, first un-apply it if necessary using hg qpop, ++then do:

          ++
          hg qdelete somework.patch
++
          ++
          ++
          ++
          ++

          29. How do I solve conflicts when applying a patch fails?

          ++

          The standard patch command, as well as hg import, will produce ++unhelpful *.rej files when it fails applying parts of a patch. ++We suggest you try the mpatch utility, which can help resolve a number of ++common causes of patch rejects.

          ++

          To make use of mpatch transparent, you can define a shell alias in one ++of your startup files. For example, if you want it to open the kdiff3 ++merge program to fix failing patch hunks:

          ++
          alias patch='mpatch --merge=kdiff3'
++
          ++
          ++

          or if you want it to automatically solve conflicts by using heuristics:

          ++
          alias patch='mpatch --auto --no-merge'
++
          ++
          ++
          ++
          ++

          29. How do I add a file or directory to the repository?

          ++

          Simply specify the path to the file or directory to add and run:

          ++
          hg add PATH
++
          ++
          ++

          If PATH is a directory, Mercurial will recursively add any files in that ++directory and its descendants.

          ++

          If you want Mercurial to figure out by itself which files should be added ++and/or removed, just run:

          ++
          hg addremove
++
          ++
          ++

          Be careful though, as it might add some files that are not desired in ++the repository (such as build products, cache files, or other data).

          ++

          You will then need to run hg commit (as discussed below) to commit ++the file(s) to your local repository.

          ++
          ++
          ++

          29. What’s the best way to split a file into several files?

          ++

          To split a file into several files (e.g. a module converted to a package or a ++long doc file divided in two separate documents) use hg copy:

          ++
          hg copy module.rst module2.rst
++
          ++
          ++

          and then remove the parts that are not necessary from module.rst and ++module2.rst. This allows Mercurial to know that the content of ++module2.rst used to be in module.rst, and will make subsequent merges ++easier. If necessary, you can also use hg copy several times.

          ++

          If you simply create module2.rst, add it with hg add, and copy part of ++the content from module.rst, Mercurial won’t know that the two file are ++related.

          ++
          ++
          ++

          29. How do I delete a file or directory in the repository?

          ++

          Specify the path to be removed with:

          ++
          hg remove PATH
++
          ++
          ++

          This will remove the file or the directory from your working copy; you will ++have to commit your changes for the removal to be recorded ++in your local repository.

          ++
          ++
          ++

          29. What files are modified in my working copy?

          ++

          Running:

          ++
          hg status
++
          ++
          ++

          will list any pending changes in the working copy. These changes will get ++committed to the local repository if you issue an hg commit without ++specifying any path.

          ++

          Some ++key indicators that can appear in the first column of output are:

          ++
          ++
          ++++++++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          AScheduled to be added
          RScheduled to be removed
          MModified locally
          ?Not under version control
          ++
          ++

          If you want a line-by-line listing of the differences, use:

          ++
          hg diff
++
          ++
          ++
          ++
          ++

          29. How do I revert a file I have modified back to the version in the repository?

          ++

          Running:

          ++
          hg revert PATH
++
          ++
          ++

          will revert PATH to its version in the repository, throwing away any ++changes you made locally. If you run:

          ++
          hg revert -a
++
          ++
          ++

          from the root of your working copy it will recursively restore everything ++to match up with the repository.

          ++
          ++
          ++

          29. How do I find out who edited or what revision changed a line last?

          ++

          You want:

          ++
          hg annotate PATH
++
          ++
          ++

          This will output to stdout every line of the file along with which revision ++last modified that line. When you have the revision number, it is then ++easy to display it in detail.

          ++
          ++
          ++

          29. How can I see a list of log messages for a file or specific revision?

          ++

          To see the history of changes for a specific file, run:

          ++
          hg log -v [PATH]
++
          ++
          ++

          That will list all messages of revisions which modified the file specified ++in PATH. If PATH is omitted, all revisions are listed.

          ++

          If you want to display line-by-line differences for each revision as well, ++add the -p option:

          ++
          hg log -vp [PATH]
++
          ++
          ++

          If you want to view the differences for a specific revision, run:

          ++
          hg log -vp -r <revision number>
++
          ++
          ++
          ++
          ++

          29. How can I see the changeset graph in my repository?

          ++

          In Mercurial repositories, changesets don’t form a simple list, but rather ++a graph: every changeset has one or two parents (it’s called a merge changeset ++in the latter case), and can have any number of children.

          ++

          The graphlog extension is very useful for examining the structure of the ++changeset graph. It is bundled with Mercurial.

          ++

          Graphical tools, such as TortoiseHG, will display the changeset graph ++by default.

          ++
          ++
          ++

          29. How do I update to a specific release tag?

          ++

          Run:

          ++
          hg tags
++
          ++
          ++

          to get a list of tags. To update your working copy to a specific tag, use:

          ++
          hg update <tag>
++
          ++
          ++
          ++
          ++

          29. How do I find which changeset introduced a bug or regression?

          ++

          hg bisect, as the name indicates, helps you do a bisection of a range of ++changesets.

          ++

          You need two changesets to start the search: one that is “good” ++(doesn’t have the bug), and one that is “bad” (has the bug). Usually, you ++have just noticed the bug in your working copy, so you can start with:

          ++
          hg bisect --bad
++
          ++
          ++

          Then you must update to a previous changeset that doesn’t have the bug. ++You can conveniently choose a faraway changeset (for example a former release), ++and check that it is indeed “good”. Then type:

          ++
          hg bisect --good
++
          ++
          ++

          Mercurial will automatically bisect so as to narrow the range of possible ++culprits, until a single changeset is isolated. Each time Mercurial presents ++you with a new changeset, re-compile Python and run the offending test, for ++example:

          ++
          make -j2
++./python -m test -uall test_sometest
++
          ++
          ++

          Then, type either hg bisect --good or hg bisect --bad depending on ++whether the test succeeded or failed.

          ++
          ++
          ++

          29. How come feature XYZ isn’t available in Mercurial?

          ++

          Mercurial comes with many bundled extensions which can be explicitly enabled. ++You can get a list of them by typing hg help extensions. Some of these ++extensions, such as color, can prettify output; others, such as fetch ++or graphlog, add new Mercurial commands.

          ++

          There are also many configuration options to tweak various aspects of the ++command line and other Mercurial behaviour; typing man hgrc displays ++their documentation inside your terminal.

          ++

          In the end, please refer to the Mercurial wiki, especially the pages about ++extensions (including third-party ones) and the tips and tricks.

          ++
          ++
          ++
          ++

          29. For core developers

          ++

          These FAQs are intended mainly for core developers.

          ++
          ++

          29. How do I commit a change to a file?

          ++

          To commit any changes to a file (which includes adding a new file or deleting ++an existing one), you use the command:

          ++
          hg commit [PATH]
++
          ++
          ++

          PATH is optional: if it is omitted, all changes in your working copy ++will be committed to the local repository. When you commit, be sure that all ++changes are desired by reviewing them first; ++also, when making commits that you intend to push to public repositories, ++you should not commit together unrelated changes.

          ++

          To abort a commit that you are in the middle of, leave the message ++empty (i.e., close the text editor without adding any text for the ++message). Mercurial will then abort the commit operation so that you can ++try again later.

          ++

          Once a change is committed to your local repository, it is still only visible ++by you. This means you are free to experiment with as many local commits ++you feel like.

          ++
          ++

          Note

          ++

          If you do not like the default text editor Mercurial uses for ++entering commit messages, you may specify a different editor, ++either by changing the EDITOR environment variable or by setting ++a Mercurial-specific editor in your global .hgrc with the editor ++option in the [ui] section.

          ++
          ++
          ++
          ++

          29. How do I solve merge conflicts?

          ++

          The easiest way is to install KDiff3 — Mercurial will open it automatically ++in case of conflicts, and you can then use it to solve the conflicts and ++save the resulting file(s). KDiff3 will also take care of marking the ++conflicts as resolved.

          ++

          If you don’t use a merge tool, you can use hg resolve --list to list the ++conflicting files, resolve the conflicts manually, and the use ++hg resolve --mark <file path> to mark these conflicts as resolved. ++You can also use hg resolve -am to mark all the conflicts as resolved.

          ++
          ++

          Note

          ++

          Mercurial will use KDiff3 automatically if it’s installed and it can find ++it — you don’t need to change any settings. KDiff3 is also already ++included in the installer of TortoiseHg. For more information, see ++http://mercurial.selenic.com/wiki/KDiff3.

          ++
          ++
          ++
          ++

          29. How do I make a null merge?

          ++

          If you committed something (e.g. on 3.3) that shouldn’t be ported on newer ++branches (e.g. on default), you have to do a null merge:

          ++
          cd 3.x
++hg merge 3.3
++hg revert -ar default
++hg resolve -am  # needed only if the merge created conflicts
++hg ci -m '#12345: null merge with 3.3.'
++
          ++
          ++

          Before committing, hg status should list all the merged files as M, ++but hg diff should produce no output. This will record the merge without ++actually changing the content of the files.

          ++
          ++
          ++

          29. I got “abort: push creates new remote heads!” while pushing, what do I do?

          ++

          If you see this message while pushing, it means that you committed something ++on a clone that was not up to date, thus creating a new head. ++This usually happens for two reasons:

          ++
            ++
          1. You forgot to run hg pull and/or hg up before committing;
            2. ++
          2. Someone else pushed on the main repo just before you, causing a push race;
            3. ++
          ++

          First of all you should pull the new changesets using hg pull. Then you can ++use hg heads to see which branches have multiple heads.

          ++

          If only one branch has multiple heads, you can do:

          ++
          cd default
++hg heads .
++hg up csid-of-the-other-head
++hg merge
++hg ci -m 'Merge heads.'
++
          ++
          ++

          hg heads . will show you the two heads of the current branch: the one you ++pulled and the one you created with your commit (you can also specify a branch ++with hg heads <branch>). While not strictly necessary, it is highly ++recommended to switch to the other head before merging. This way you will be ++merging only your changeset with the rest, and in case of conflicts it will be ++a lot easier.

          ++

          If more than one branch has multiple heads, you have to repeat these steps for ++each branch. Since this creates new changesets, you will also have to ++merge them between branches. For example, if both 3.3 ++and default have multiple heads, you should first merge heads in 3.3, ++then merge heads in default, and finally merge 3.3 with default ++using hg merge 3.3 as usual.

          ++

          In order to avoid this, you should always remember to pull and update before ++committing.

          ++
          ++
          ++

          29. How do I undo the changes made in a recent commit?

          ++

          First, this should not happen if you take the habit of reviewing changes before committing them.

          ++

          In any case, run:

          ++
          hg backout <revision number>
++
          ++
          ++

          This will modify your working copy so that all changes in <revision number> ++(including added or deleted files) are undone. You then need to commit these changes so that the backout gets permanently recorded.

          ++
          ++

          Note

          ++

          These instructions are for Mercurial 1.7 and higher. hg backout has ++a slightly different behaviour in versions before 1.7.

          ++
          ++
          ++
          ++
          ++
          ++

          29.3. SSH

          ++
          ++

          29. How do I generate an SSH 2 public key?

          ++

          All generated SSH keys should be sent to hgaccounts@python.org for ++adding to the list of keys.

          ++
          ++

          29. UNIX

          ++

          Run:

          ++
          ssh-keygen -t rsa
++
          ++
          ++

          This will generate two files; your public key and your private key. Your ++public key is the file ending in .pub.

          ++
          ++
          ++

          29. Windows

          ++

          Use PuTTYgen to generate your public key. Choose the “SSH2 DSA” radio button, ++have it create an OpenSSH formatted key, choose a password, and save the private ++key to a file. Copy the section with the public key (using Alt-P) to a file; ++that file now has your public key.

          ++
          ++
          ++
          ++

          29. Is there a way to avoid having to constantly enter my password for my SSH 2 public key?

          ++
          ++

          29. UNIX

          ++

          Use ssh-agent and ssh-add to register your private key with SSH for ++your current session. The simplest solution, though, is to use KeyChain, ++which is a shell script that will handle ssh-agent and ssh-add for you ++once per login instead of per session.

          ++
          ++
          ++

          29. Windows

          ++

          The Pageant program is bundled with TortoiseHg. You can find it in its ++installation directory (usually C:\Program Files (x86)\TortoiseHg\); ++you can also download it separately.

          ++

          Running Pageant will prevent you from having to type your password constantly. ++If you add a shortcut to Pageant to your Autostart group and edit the shortcut ++so that the command line includes an argument to your private key then Pageant ++will load the key every time you log in.

          ++
          ++
          ++
          ++

          29. Can I make commits from machines other than the one I generated the keys on?

          ++

          You can make commits from any machine, since they will be ++recorded in your local repository.

          ++

          However, to push these changes to the remote server, you will need proper ++credentials. All you need is to make sure that the machine you want to ++push changes from has both the public and private keys in the standard ++place that ssh will look for them (i.e. ~/.ssh on Unix machines). ++Please note that although the key file ending in .pub contains your ++user name and machine name in it, that information is not used by the ++verification process, therefore these key files can be moved to a ++different computer and used for verification. Please guard your keys ++and never share your private key with anyone. If you lose the media ++on which your keys are stored or the machine on which your keys are ++stored, be sure to report this to pydotorg@python.org at the same time ++that you change your keys.

          ++
          ++
          ++
          ++

          29.4. General

          ++
          ++

          29. How do I regenerate configure?

          ++

          If a change is made to Python which relies on some POSIX system-specific ++functionality (such as using a new system call), it is necessary to update the ++configure script to test for availability of the functionality.

          ++

          Python’s configure script is generated from configure.ac using Autoconf. ++Instead of editing configure, edit configure.ac and then run ++autoreconf to regenerate configure and a number of other files (such as ++pyconfig.h.

          ++

          When submitting a patch with changes made to configure.ac, it is preferred ++to leave out the generated files as differences between Autoconf versions ++frequently results in many spurious changes cluttering the patch. Instead, ++remind any potential reviewers on the tracker to run autoreconf.

          ++

          Note that running autoreconf is not the same as running autoconf. For ++example, autoconf by itself will not regenerate pyconfig.h.in. ++autoreconf runs autoconf and a number of other tools repeatedly as is ++appropriate.

          ++

          Python’s configure.ac script typically requires a specific version of ++Autoconf. At the moment, this reads: version_required(2.65)

          ++

          If the system copy of Autoconf does not match this version, you will need to ++install your own copy of Autoconf.

          ++
          ++
          ++

          29. How do I update my auto-load-safe-path to allow test_gdb to run?

          ++

          test_gdb attempts to automatically load additional Python specific ++hooks into gdb in order to test them. Unfortunately, the command line ++options it uses to do this aren’t always supported correctly.

          ++

          If test_gdb is being skipped with an “auto-loading has been declined” ++message, then it is necessary to identify any Python build directories as ++auto-load safe. One way to achieve this is to add a line like the following ++to ~/.gdbinit (edit the specific list of paths as appropriate):

          ++
          add-auto-load-safe-path ~/devel/py3k:~/devel/py32:~/devel/py27
++
          ++
          ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          28. Dynamic Analysis with Clang

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/fixingissues.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/fixingissues.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,125 @@ ++ ++ ++ ++ ++ ++ ++ ++ 10. Fixing “easy” Issues (and Beyond) — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          10. Fixing “easy” Issues (and Beyond)

          ++

          When you feel comfortable enough to want to help tackle issues by trying to ++create a patch to fix an issue, you can start by looking at the “easy” ++issues. These issues should be ones where it should take no longer than a day ++or weekend to fix. But because the “easy” classification is typically done at ++triage time it can turn out to be inaccurate, so do feel free to leave a ++comment if you think the classification no longer applies.

          ++

          For the truly adventurous looking for a challenge, you can look for issues that ++are not considered easy and try to fix those. It must be warned, though, that ++it is quite possible that a bug that has been left open has been left into that ++state because of the difficulty compared to the benefit of the fix. It could ++also still be open because no consensus has been reached on how to fix the ++issue (although having a patch that proposes a fix can turn the tides of the ++discussion to help bring it to a close). Regardless of why the issue is open, ++you can also always provide useful comments if you do attempt a fix, successful ++or not.

          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Previous topic

          ++

          9. Silence Warnings From the Test Suite

          ++

          Next topic

          ++

          11. Issue Tracking

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/gdb.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/gdb.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,399 @@ ++ ++ ++ ++ ++ ++ ++ ++ 24. gdb Support — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          24. gdb Support

          ++

          If you experience low-level problems such as crashes or deadlocks ++(e.g. when tinkering with parts of CPython which are written in C), ++it can be convenient to use a low-level debugger such as gdb in ++order to diagnose and fix the issue. By default, however, gdb (or any ++of its front-ends) doesn’t know about high-level information specific to the ++CPython interpreter, such as which Python function is currently executing, ++or what type or value has a given Python object represented by a standard ++PyObject * pointer. We hereafter present two ways to overcome this ++limitation.

          ++
          ++

          24.1. gdb 7 and later

          ++

          In gdb 7, support for extending gdb with Python was ++added. When CPython is built you will notice a python-gdb.py file in the ++root directory of your checkout. Read the module docstring for details on how ++to use the file to enhance gdb for easier debugging of a CPython process.

          ++

          This is what a backtrace looks like (truncated) when this extension is ++enabled:

          ++
          #0  0x000000000041a6b1 in PyObject_Malloc (nbytes=Cannot access memory at address 0x7fffff7fefe8
++) at Objects/obmalloc.c:748
++#1  0x000000000041b7c0 in _PyObject_DebugMallocApi (id=111 'o', nbytes=24) at Objects/obmalloc.c:1445
++#2  0x000000000041b717 in _PyObject_DebugMalloc (nbytes=24) at Objects/obmalloc.c:1412
++#3  0x000000000044060a in _PyUnicode_New (length=11) at Objects/unicodeobject.c:346
++#4  0x00000000004466aa in PyUnicodeUCS2_DecodeUTF8Stateful (s=0x5c2b8d "__lltrace__", size=11, errors=0x0, consumed=
++    0x0) at Objects/unicodeobject.c:2531
++#5  0x0000000000446647 in PyUnicodeUCS2_DecodeUTF8 (s=0x5c2b8d "__lltrace__", size=11, errors=0x0)
++    at Objects/unicodeobject.c:2495
++#6  0x0000000000440d1b in PyUnicodeUCS2_FromStringAndSize (u=0x5c2b8d "__lltrace__", size=11)
++    at Objects/unicodeobject.c:551
++#7  0x0000000000440d94 in PyUnicodeUCS2_FromString (u=0x5c2b8d "__lltrace__") at Objects/unicodeobject.c:569
++#8  0x0000000000584abd in PyDict_GetItemString (v=
++    {'Yuck': <type at remote 0xad4730>, '__builtins__': <module at remote 0x7ffff7fd5ee8>, '__file__': 'Lib/test/crashers/nasty_eq_vs_dict.py', '__package__': None, 'y': <Yuck(i=0) at remote 0xaacd80>, 'dict': {0: 0, 1: 1, 2: 2, 3: 3}, '__cached__': None, '__name__': '__main__', 'z': <Yuck(i=0) at remote 0xaace60>, '__doc__': None}, key=
++    0x5c2b8d "__lltrace__") at Objects/dictobject.c:2171
++
          ++
          ++

          (notice how the dictionary argument to PyDict_GetItemString is displayed ++as its repr(), rather than an opaque PyObject * pointer)

          ++

          The extension works by supplying a custom printing routine for values of type ++PyObject *. If you need to access lower-level details of an object, then ++cast the value to a pointer of the appropriate type. For example:

          ++
          (gdb) p globals
++$1 = {'__builtins__': <module at remote 0x7ffff7fb1868>, '__name__':
++'__main__', 'ctypes': <module at remote 0x7ffff7f14360>, '__doc__': None,
++'__package__': None}
++
++(gdb) p *(PyDictObject*)globals
++$2 = {ob_refcnt = 3, ob_type = 0x3dbdf85820, ma_fill = 5, ma_used = 5,
++ma_mask = 7, ma_table = 0x63d0f8, ma_lookup = 0x3dbdc7ea70
++<lookdict_string>, ma_smalltable = {{me_hash = 7065186196740147912,
++me_key = '__builtins__', me_value = <module at remote 0x7ffff7fb1868>},
++{me_hash = -368181376027291943, me_key = '__name__',
++me_value ='__main__'}, {me_hash = 0, me_key = 0x0, me_value = 0x0},
++{me_hash = 0, me_key = 0x0, me_value = 0x0},
++{me_hash = -9177857982131165996, me_key = 'ctypes',
++me_value = <module at remote 0x7ffff7f14360>},
++{me_hash = -8518757509529533123, me_key = '__doc__', me_value = None},
++{me_hash = 0, me_key = 0x0, me_value = 0x0}, {
++  me_hash = 6614918939584953775, me_key = '__package__', me_value = None}}}
++
          ++
          ++

          The pretty-printers try to closely match the repr() implementation of the ++underlying implementation of Python, and thus vary somewhat between Python 2 ++and Python 3.

          ++

          An area that can be confusing is that the custom printer for some types look a ++lot like gdb’s built-in printer for standard types. For example, the ++pretty-printer for a Python 3 int gives a repr() that is not ++distinguishable from a printing of a regular machine-level integer:

          ++
          (gdb) p some_machine_integer
++$3 = 42
++
++(gdb) p some_python_integer
++$4 = 42
++
++(gdb) p *(PyLongObject*)some_python_integer
++$5 = {ob_base = {ob_base = {ob_refcnt = 8, ob_type = 0x3dad39f5e0}, ob_size = 1},
++ob_digit = {42}}
++
          ++
          ++

          A similar confusion can arise with the str type, where the output looks a ++lot like gdb’s built-in printer for char *:

          ++
          (gdb) p ptr_to_python_str
++$6 = '__builtins__'
++
          ++
          ++

          The pretty-printer for str instances defaults to using single-quotes (as ++does Python’s repr for strings) whereas the standard printer for char * ++values uses double-quotes and contains a hexadecimal address:

          ++
          (gdb) p ptr_to_char_star
++$7 = 0x6d72c0 "hello world"
++
          ++
          ++

          Here’s how to see the implementation details of a str instance (for Python ++3, where a str is a PyUnicodeObject *):

          ++
          (gdb) p *(PyUnicodeObject*)$6
++$8 = {ob_base = {ob_refcnt = 33, ob_type = 0x3dad3a95a0}, length = 12,
++str = 0x7ffff2128500, hash = 7065186196740147912, state = 1, defenc = 0x0}
++
          ++
          ++

          As well as adding pretty-printing support for PyObject *, the extension adds a number of commands to gdb

          ++
          ++
          py-list
          ++

          List the Python source code (if any) for the current frame in the selected ++thread. The current line is marked with a “>”:

          ++
          (gdb) py-list
++ 901        if options.profile:
++ 902            options.profile = False
++ 903            profile_me()
++ 904            return
++ 905
++>906        u = UI()
++ 907        if not u.quit:
++ 908            try:
++ 909                gtk.main()
++ 910            except KeyboardInterrupt:
++ 911                # properly quit on a keyboard interrupt...
++
          ++
          ++

          Use py-list START to list at a different line number within the python ++source, and py-list START,END to list a specific range of lines within ++the python source.

          ++
          ++
          py-up and py-down
          ++

          The py-up and py-down commands are analogous to gdb’s regular up ++and down commands, but try to move at the level of CPython frames, rather ++than C frames.

          ++

          gdb is not always able to read the relevant frame information, depending on ++the optimization level with which CPython was compiled. Internally, the ++commands look for C frames that are executing PyEval_EvalFrameEx (which ++implements the core bytecode interpreter loop within CPython) and look up ++the value of the related PyFrameObject *.

          ++

          They emit the frame number (at the C level) within the thread.

          ++

          For example:

          ++
          (gdb) py-up
++#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/
++gnome_sudoku/main.py, line 906, in start_game ()
++    u = UI()
++(gdb) py-up
++#40 Frame 0x948e82c, for file /usr/lib/python2.6/site-packages/
++gnome_sudoku/gnome_sudoku.py, line 22, in start_game(main=<module at remote 0xb771b7f4>)
++    main.start_game()
++(gdb) py-up
++Unable to find an older python frame
++
          ++
          ++

          so we’re at the top of the python stack. Going back down:

          ++
          (gdb) py-down
++#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/gnome_sudoku/main.py, line 906, in start_game ()
++    u = UI()
++(gdb) py-down
++#34 (unable to read python frame information)
++(gdb) py-down
++#23 (unable to read python frame information)
++(gdb) py-down
++#19 (unable to read python frame information)
++(gdb) py-down
++#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/game_selector.py, line 201, in run_swallowed_dialog (self=<NewOrSavedGameSelector(new_game_model=<gtk.ListStore at remote 0x98fab44>, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, 'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\n7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': <float at remote 0x984b474>, 'gsd.hints': 0, 'timer.active_time': <float at remote 0x984b494>, 'timer.total_time': <float at remote 0x984b464>}], dialog=<gtk.Dialog at remote 0x98faaa4>, saved_game_model=<gtk.ListStore at remote 0x98fad24>, sudoku_maker=<SudokuMaker(terminated=False, played=[], batch_siz...(truncated)
++            swallower.run_dialog(self.dialog)
++(gdb) py-down
++#11 Frame 0x9aead74, for file /usr/lib/python2.6/site-packages/gnome_sudoku/dialog_swallower.py, line 48, in run_dialog (self=<SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>, main_page=0) at remote 0x98fa6e4>, d=<gtk.Dialog at remote 0x98faaa4>)
++            gtk.main()
++(gdb) py-down
++#8 (unable to read python frame information)
++(gdb) py-down
++Unable to find a newer python frame
++
          ++
          ++

          and we’re at the bottom of the python stack.

          ++
          ++
          py-bt
          ++

          The py-bt command attempts to display a Python-level backtrace of the ++current thread.

          ++

          For example:

          ++
          (gdb) py-bt
++#8 (unable to read python frame information)
++#11 Frame 0x9aead74, for file /usr/lib/python2.6/site-packages/gnome_sudoku/dialog_swallower.py, line 48, in run_dialog (self=<SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>, main_page=0) at remote 0x98fa6e4>, d=<gtk.Dialog at remote 0x98faaa4>)
++            gtk.main()
++#14 Frame 0x99262ac, for file /usr/lib/python2.6/site-packages/gnome_sudoku/game_selector.py, line 201, in run_swallowed_dialog (self=<NewOrSavedGameSelector(new_game_model=<gtk.ListStore at remote 0x98fab44>, puzzle=None, saved_games=[{'gsd.auto_fills': 0, 'tracking': {}, 'trackers': {}, 'notes': [], 'saved_at': 1270084485, 'game': '7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 0 0 0 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5\n7 8 0 0 0 0 0 5 6 0 0 9 0 8 0 1 0 0 0 4 6 0 0 0 0 7 0 6 5 1 8 3 4 7 9 2 0 0 0 9 0 1 0 0 0 3 9 7 6 0 0 0 1 8 0 6 0 0 0 0 2 8 0 0 0 5 0 4 0 6 0 0 2 1 0 0 0 0 0 4 5', 'gsd.impossible_hints': 0, 'timer.__absolute_start_time__': <float at remote 0x984b474>, 'gsd.hints': 0, 'timer.active_time': <float at remote 0x984b494>, 'timer.total_time': <float at remote 0x984b464>}], dialog=<gtk.Dialog at remote 0x98faaa4>, saved_game_model=<gtk.ListStore at remote 0x98fad24>, sudoku_maker=<SudokuMaker(terminated=False, played=[], batch_siz...(truncated)
++            swallower.run_dialog(self.dialog)
++#19 (unable to read python frame information)
++#23 (unable to read python frame information)
++#34 (unable to read python frame information)
++#37 Frame 0x9420b04, for file /usr/lib/python2.6/site-packages/gnome_sudoku/main.py, line 906, in start_game ()
++    u = UI()
++#40 Frame 0x948e82c, for file /usr/lib/python2.6/site-packages/gnome_sudoku/gnome_sudoku.py, line 22, in start_game (main=<module at remote 0xb771b7f4>)
++    main.start_game()
++
          ++
          ++

          The frame numbers correspond to those displayed by gdb’s standard backtrace command.

          ++
          ++
          py-print
          ++

          The py-print command looks up a Python name and tries to print it. It looks in locals within the current thread, then globals, then finally builtins:

          ++
          (gdb) py-print self
++local 'self' = <SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>,
++main_page=0) at remote 0x98fa6e4>
++(gdb) py-print __name__
++global '__name__' = 'gnome_sudoku.dialog_swallower'
++(gdb) py-print len
++builtin 'len' = <built-in function len>
++(gdb) py-print scarlet_pimpernel
++'scarlet_pimpernel' not found
++
          ++
          ++
          ++
          py-locals
          ++

          The py-locals command looks up all Python locals within the current Python frame in the selected thread, and prints their representations:

          ++
          (gdb) py-locals
++self = <SwappableArea(running=<gtk.Dialog at remote 0x98faaa4>,
++main_page=0) at remote 0x98fa6e4>
++d = <gtk.Dialog at remote 0x98faaa4>
++
          ++
          ++
          ++
          ++

          You can of course use other gdb commands. For example, the frame command takes you directly to a particular frame within the selected thread. We can use it to go a specific frame shown by py-bt like this:

          ++
          (gdb) py-bt
++(output snipped)
++#68 Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in <module> ()
++        main()
++(gdb) frame 68
++#68 0x00000000004cd1e6 in PyEval_EvalFrameEx (f=Frame 0xaa4560, for file Lib/test/regrtest.py, line 1548, in <module> (), throwflag=0) at Python/ceval.c:2665
++2665                            x = call_function(&sp, oparg);
++(gdb) py-list
++1543        # Run the tests in a context manager that temporary changes the CWD to a
++1544        # temporary and writable directory. If it's not possible to create or
++1545        # change the CWD, the original CWD will be used. The original CWD is
++1546        # available from test_support.SAVEDCWD.
++1547        with test_support.temp_cwd(TESTCWD, quiet=True):
++>1548            main()
++
          ++
          ++

          The info threads command will give you a list of the threads within the process, and you can use the thread command to select a different one:

          ++
          (gdb) info threads
++  105 Thread 0x7fffefa18710 (LWP 10260)  sem_wait () at ../nptl/sysdeps/unix/sysv/linux/x86_64/sem_wait.S:86
++  104 Thread 0x7fffdf5fe710 (LWP 10259)  sem_wait () at ../nptl/sysdeps/unix/sysv/linux/x86_64/sem_wait.S:86
++* 1 Thread 0x7ffff7fe2700 (LWP 10145)  0x00000038e46d73e3 in select () at ../sysdeps/unix/syscall-template.S:82
++
          ++
          ++

          You can use thread apply all COMMAND or (t a a COMMAND for short) to run a command on all threads. You can use this with py-bt to see what every thread is doing at the Python level:

          ++
          (gdb) t a a py-bt
++
++Thread 105 (Thread 0x7fffefa18710 (LWP 10260)):
++#5 Frame 0x7fffd00019d0, for file /home/david/coding/python-svn/Lib/threading.py, line 155, in _acquire_restore (self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=<thread.lock at remote 0x858770>, _RLock__count=1) at remote 0xd7ff40>, count_owner=(1, 140737213728528), count=1, owner=140737213728528)
++        self.__block.acquire()
++#8 Frame 0x7fffac001640, for file /home/david/coding/python-svn/Lib/threading.py, line 269, in wait (self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=<thread.lock at remote 0x858770>, _RLock__count=1) at remote 0xd7ff40>, acquire=<instancemethod at remote 0xd80260>, _is_owned=<instancemethod at remote 0xd80160>, _release_save=<instancemethod at remote 0xd803e0>, release=<instancemethod at remote 0xd802e0>, _acquire_restore=<instancemethod at remote 0xd7ee60>, _Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, timeout=None, waiter=<thread.lock at remote 0x858a90>, saved_state=(1, 140737213728528))
++            self._acquire_restore(saved_state)
++#12 Frame 0x7fffb8001a10, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 348, in f ()
++            cond.wait()
++#16 Frame 0x7fffb8001c40, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 37, in task (tid=140737213728528)
++                f()
++
++Thread 104 (Thread 0x7fffdf5fe710 (LWP 10259)):
++#5 Frame 0x7fffe4001580, for file /home/david/coding/python-svn/Lib/threading.py, line 155, in _acquire_restore (self=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=<thread.lock at remote 0x858770>, _RLock__count=1) at remote 0xd7ff40>, count_owner=(1, 140736940992272), count=1, owner=140736940992272)
++        self.__block.acquire()
++#8 Frame 0x7fffc8002090, for file /home/david/coding/python-svn/Lib/threading.py, line 269, in wait (self=<_Condition(_Condition__lock=<_RLock(_Verbose__verbose=False, _RLock__owner=140737354016512, _RLock__block=<thread.lock at remote 0x858770>, _RLock__count=1) at remote 0xd7ff40>, acquire=<instancemethod at remote 0xd80260>, _is_owned=<instancemethod at remote 0xd80160>, _release_save=<instancemethod at remote 0xd803e0>, release=<instancemethod at remote 0xd802e0>, _acquire_restore=<instancemethod at remote 0xd7ee60>, _Verbose__verbose=False, _Condition__waiters=[]) at remote 0xd7fd10>, timeout=None, waiter=<thread.lock at remote 0x858860>, saved_state=(1, 140736940992272))
++            self._acquire_restore(saved_state)
++#12 Frame 0x7fffac001c90, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 348, in f ()
++            cond.wait()
++#16 Frame 0x7fffac0011c0, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 37, in task (tid=140736940992272)
++                f()
++
++Thread 1 (Thread 0x7ffff7fe2700 (LWP 10145)):
++#5 Frame 0xcb5380, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 16, in _wait ()
++    time.sleep(0.01)
++#8 Frame 0x7fffd00024a0, for file /home/david/coding/python-svn/Lib/test/lock_tests.py, line 378, in _check_notify (self=<ConditionTests(_testMethodName='test_notify', _resultForDoCleanups=<TestResult(_original_stdout=<cStringIO.StringO at remote 0xc191e0>, skipped=[], _mirrorOutput=False, testsRun=39, buffer=False, _original_stderr=<file at remote 0x7ffff7fc6340>, _stdout_buffer=<cStringIO.StringO at remote 0xc9c7f8>, _stderr_buffer=<cStringIO.StringO at remote 0xc9c790>, _moduleSetUpFailed=False, expectedFailures=[], errors=[], _previousTestClass=<type at remote 0x928310>, unexpectedSuccesses=[], failures=[], shouldStop=False, failfast=False) at remote 0xc185a0>, _threads=(0,), _cleanups=[], _type_equality_funcs={<type at remote 0x7eba00>: <instancemethod at remote 0xd750e0>, <type at remote 0x7e7820>: <instancemethod at remote 0xd75160>, <type at remote 0x7e30e0>: <instancemethod at remote 0xd75060>, <type at remote 0x7e7d20>: <instancemethod at remote 0xd751e0>, <type at remote 0x7f19e0...(truncated)
++        _wait()
++
          ++
          ++
          ++

          Note

          ++

          This is only available for Python 2.7, 3.2 and higher.

          ++
          ++
          ++
          ++

          24.2. gdb 6 and earlier

          ++

          The file at Misc/gdbinit contains a gdb configuration file which provides ++extra commands when working with a CPython process. To register these commands ++permanently, either copy the commands to your personal gdb configuration file ++or symlink ~/.gdbinit to Misc/gdbinit. To use these commands from ++a single gdb session without registering them, type source Misc/gdbinit ++from your gdb session.

          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          23. Emacs support

          ++

          Next topic

          ++

          25. Changing CPython’s Grammar

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/genindex.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/genindex.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,142 @@ ++ ++ ++ ++ ++ ++ ++ ++ ++ Index — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++ ++

          Index

          ++ ++
          ++ P ++ ++
          ++

          P

          ++ ++ ++ ++
          ++ ++
          PEP process ++
          ++ ++
          ++ ++
          in FAQ ++
          ++ ++
          ++
          ++ ++
          ++ Python Enhancement Proposals ++
          ++ ++
          ++ ++
          PEP 1 ++
          ++ ++ ++
          PEP 291 ++
          ++ ++ ++
          PEP 360 ++
          ++ ++ ++
          PEP 387 ++
          ++ ++ ++
          PEP 7, [1] ++
          ++ ++ ++
          PEP 8, [1] ++
          ++ ++
          ++
          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++ ++ ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/grammar.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/grammar.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,166 @@ ++ ++ ++ ++ ++ ++ ++ ++ 25. Changing CPython’s Grammar — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          25. Changing CPython’s Grammar

          ++
          ++

          25.1. Abstract

          ++

          There’s more to changing Python’s grammar than editing ++Grammar/Grammar and Python/compile.c. This document aims to be a ++checklist of places that must also be fixed.

          ++

          It is probably incomplete. If you see omissions, submit a bug or patch.

          ++

          This document is not intended to be an instruction manual on Python ++grammar hacking, for several reasons.

          ++
          ++
          ++

          25.2. Rationale

          ++

          People are getting this wrong all the time; it took well over a ++year before someone noticed ++that adding the floor division ++operator (//) broke the parser module.

          ++
          ++
          ++

          25.3. Checklist

          ++
            ++
          • Grammar/Grammar: OK, you’d probably worked this one out :)
            • ++
          • Parser/Python.asdl may need changes to match the Grammar. Run make to ++regenerate Include/Python-ast.h and Python/Python-ast.c.
            • ++
          • Python/ast.c will need changes to create the AST objects involved with the ++Grammar change.
            • ++
          • Parser/pgen needs to be rerun to regenerate Include/graminit.h and ++Python/graminit.c. (make should handle this for you.)
            • ++
          • Python/symtable.c: This handles the symbol collection pass ++that happens immediately before the compilation pass.
            • ++
          • Python/compile.c: You will need to create or modify the ++compiler_* functions to generate opcodes for your productions.
            • ++
          • You may need to regenerate Lib/symbol.py and/or Lib/token.py ++and/or Lib/keyword.py.
            • ++
          • The parser module. Add some of your new syntax to test_parser, ++bang on Modules/parsermodule.c until it passes.
            • ++
          • Add some usage of your new syntax to test_grammar.py
            • ++
          • If you’ve gone so far as to change the token structure of ++Python, then the Lib/tokenizer.py library module will need to be changed.
            • ++
          • Certain changes may require tweaks to the library module pyclbr.
            • ++
          • Documentation must be written!
            • ++
          • After everything has been checked in, you’re likely to see a new ++change to Python/Python-ast.c. This is because this ++(generated) file contains the hg version of the source from ++which it was generated. There’s no way to avoid this; you just ++have to submit this file separately.
            • ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          24. gdb Support

          ++

          Next topic

          ++

          26. Design of CPython’s Compiler

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/help.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/help.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,166 @@ ++ ++ ++ ++ ++ ++ ++ ++ 3. Where to Get Help — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          3. Where to Get Help

          ++

          If you are working on Python it is very possible you will come across an issue ++where you need some assistance to solve it (this happens to core developers ++all the time).

          ++

          Should you require help, there are a variety of options available to seek assistance. If the question involves process or tool ++usage then please check the rest of this guide first (especially the ++Python Developer FAQ) as it should answer your question.

          ++
          ++

          3.1. Ask #python-dev

          ++

          If you are comfortable with IRC you can try asking on #python-dev (on ++the freenode network). Typically there are a number of experienced ++developers, ranging from triagers to core developers, who can answer ++questions about developing for Python. Just remember that #python-dev ++is for questions involving the development of Python whereas #python ++is for questions concerning development with Python.

          ++
          ++
          ++

          3.2. Core Mentorship

          ++

          If you are interested in improving Python and contributing to its development, ++but don’t yet feel entirely comfortable with the public channels mentioned ++above, Python Mentors are here to help you. Python is fortunate to have a ++community of volunteer core developers willing to mentor anyone wishing to ++contribute code, work on bug fixes or improve documentation. Everyone is ++welcomed and encouraged to contribute.

          ++
          ++
          ++

          3.3. Mailing Lists

          ++

          Further options for seeking assistance include the python-ideas and ++python-dev mailing lists. Python-ideas contains discussion of speculative ++Python language ideas for possible inclusion into the language. If an idea ++gains traction it can then be discussed and honed to the point of becoming a ++solid proposal and presented on python-dev. Python-dev contains discussion ++of current Python design issues, release mechanics, and maintenance of ++existing releases. As with #python-dev, these mailing lists are for ++questions involving the development of Python, not for development ++with Python.

          ++
          ++
          ++

          3.4. File a Bug

          ++

          If you strongly suspect you have stumbled on a bug (be it in the build ++process, in the test suite, or in other areas), then open an issue on the ++issue tracker. As with every bug report it is strongly advised that ++you detail which conditions triggered it (including the OS name and version, ++and what you were trying to do), as well as the exact error message you ++encountered.

          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          2. Setting Up Windows - Advanced

          ++

          Next topic

          ++

          4. Lifecycle of a Patch

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/index.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/index.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,703 @@ ++ ++ ++ ++ ++ ++ ++ ++ Python Developer’s Guide — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          Python Developer’s Guide

          ++

          This guide is a comprehensive resource for contributing ++to Python – for both new and experienced contributors. It is ++maintained by the same community ++that maintains Python. We welcome your contributions to Python!

          ++
          ++

          Quick Start

          ++

          Here are the basic steps needed to get set up and contribute a ++patch:

          ++
            ++

          1. Get the source code:

            ++
            hg clone http://hg.python.org/cpython
++
            ++
            ++
            2. ++

          2. Build Python. On UNIX:

            ++
            ./configure --with-pydebug && make -j2
++
            ++
            ++

            On Windows, open the solution file ++PCbuild\pcbuild.sln in Visual Studio, select Debug, ++and Build ‣ Build Solution. Run ++Tools\buildbot\external.bat or ++Tools\buildbot\external-amd64.bat to download and compile 3rd ++party libraries. Note: Visual Studio may throw errors, but Python will ++be built.

            ++
            3. ++

          3. Run the tests:

            ++
            ./python -m test -j3
++
            ++
            ++

            On most Mac OS X systems, replace ./python ++with ./python.exe. On Windows, use PCbuild\python_d.exe or ++check the Windows instructions. With Python 2.7, ++replace test with test.regrtest.

            ++
            4. ++

          4. Make the patch.

            ++
            5. ++

          5. Submit it to the issue tracker.

            ++
            6. ++
          ++
          ++ ++
          ++

          Contributing

          ++

          We encourage everyone to contribute to Python and that’s why we have put up this ++developer’s guide. If you still have questions after reviewing the material in ++this guide, then the Python Mentors group is available to help guide new ++contributors through the process. The Developer FAQ is another ++useful source of information.

          ++

          Guide for contributing to Python:

          ++ ++

          It is recommended that the above documents be read in the order listed. You ++can stop where you feel comfortable and begin contributing immediately without ++reading and understanding these documents all at once. If you do choose to skip ++around within the documentation, be aware that it is written assuming preceding ++documentation has been read so you may find it necessary to backtrack to fill in ++missing concepts and terminology.

          ++
          ++
          ++

          Proposing changes to Python itself

          ++

          Improving Python’s code, documentation and tests are ongoing tasks that are ++never going to be “finished”, as Python operates as part of an ever-evolving ++system of technology. An even more challenging ongoing task than these ++necessary maintenance activities is finding ways to make Python, in the form of ++the standard library and the language definition, an even better tool in a ++developer’s toolkit.

          ++

          While these kinds of change are much rarer than those described above, they do ++happen and that process is also described as part of this guide:

          ++ ++

          Also refer to Where should I suggest new features and language changes? in the FAQ.

          ++
          ++
          ++

          Other Interpreter Implementations

          ++

          This guide is specifically for contributing to the Python reference interpreter, ++also known as CPython (while most of the standard library is written in Python, ++the interpreter core is written in C and integrates most easily with the C and ++C++ ecosystems).

          ++

          There are other Python implementations, each with a different focus. Like ++CPython, they always have more things they would like to do than they have ++developers to work on them. Some major example that may be of interest are:

          ++
            ++
          • PyPy: A Python interpreter focused on high speed (JIT-compiled) operation ++on major platforms
            • ++
          • Jython: A Python interpreter focused on good integration with the Java ++Virtual Machine (JVM) environment
            • ++
          • IronPython: A Python interpreter focused on good integration with the ++Common Language Runtime (CLR) provided by .NET and Mono
            • ++
          • Stackless: A Python interpreter focused on providing lightweight ++microthreads while remaining largely compatible with CPython specific ++extension modules
            • ++
          ++
          ++
          ++

          Key Resources

          ++ ++
          ++
          ++

          Additional Resources

          ++ ++
          ++
          ++

          Full Table of Contents

          ++
          ++ ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Next topic

          ++

          1. Getting Started

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/langchanges.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/langchanges.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,167 @@ ++ ++ ++ ++ ++ ++ ++ ++ 21. Changing the Python Language — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          21. Changing the Python Language

          ++

          On occasion people come up with an idea on how to change or improve Python as a ++programming language. This document is meant to explain exactly what changes ++have a reasonable chance of being considered and what the process is to propose ++changes to the language.

          ++
          ++

          21.1. What Qualifies

          ++

          First and foremost, it must be understood that changes to the Python ++programming language are difficult to make. When the language changes, ++every Python programmer already in existence and all Python programmers to ++come will end up eventually learning about the change you want to propose. ++Books will need updating, code will be changed, and a new way to do things will ++need to be learned. Changes to the Python programming language are never taken ++lightly.

          ++

          Because of the seriousness that language changes carry, any change must be ++beneficial to a large proportion of Python users. If the change only benefits a ++small percentage of Python developers then the change will not be made. A good ++way to see if your idea would work for a large portion of the Python community ++is to ask on python-list or python-ideas. You can also ++go through Python’s stdlib and find examples of code which would benefit from ++your proposed change (which helps communicate the usefulness of your change to ++others). For further guidance, see Where should I suggest new features and language changes? in the FAQ.

          ++

          Your proposed change also needs to be Pythonic. While Guido is the only ++person who can truly classify something as Pythonic, you can read the Zen of ++Python for guidance.

          ++
          ++
          ++

          21.2. PEP Process

          ++

          Once you are certain you have a language change proposal which will appeal to ++the general Python community, you can begin the process of officially proposing ++the change. This process is the Python Enhancement Proposal (PEP) process. ++PEP 1 describes it in detail.

          ++

          You will first need a PEP that you will present to python-ideas. You may be a ++little hazy on the technical details as various core developers can help with ++that, but do realize that if you do not present your idea to python-ideas or ++python-list ahead of time you may find out it is technically not possible ++(e.g., Python’s parser will not support the grammar change as it is an LL(1) ++parser). Expect extensive comments on the PEP, some of which will be negative.

          ++

          Once your PEP has been modified to be of proper quality and to take into ++account comments made on python-ideas, it may proceed to python-dev. There it ++will be assigned a PEP dictator and another general discussion will occur. Once ++again, you will need to modify your PEP to incorporate the large amount of ++comments you will receive.

          ++

          The PEP dictator decides if your PEP is accepted (typically based on whether ++most core developers support the PEP). If that occurs then your proposed ++language change will be introduced in the next release of Python. Otherwise ++your PEP will be recorded as rejected along with an explanation as to why so ++that others do not propose the same language change in the future.

          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          20. Adding to the Stdlib

          ++

          Next topic

          ++

          22. Experts Index

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/objects.inv +Binary file build/objects.inv has changed +diff -r 85f290e474e2 build/patch.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/patch.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,275 @@ ++ ++ ++ ++ ++ ++ ++ ++ 4. Lifecycle of a Patch — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          4. Lifecycle of a Patch

          ++
          ++

          4.1. Creating

          ++
          ++

          4.1.1. Tool Usage

          ++

          Mercurial allows for various workflows according to each person’s or ++project’s preference. It is out of this guide’s scope to present them all, ++so we will stick to a basic workflow where you work on a patch in your ++working copy without ever making any local commits.

          ++

          If you use this workflow, and your work adds or removes files to the ++source tree, you will have to temporarily hg add or hg remove them, ++respectively, before generating a patch.

          ++

          To generate a patch, just invoke hg diff which will print out a ++patch of the working copy’s changes against the current revision:

          ++
          hg diff > mywork.patch
++
          ++
          ++

          If you want to undo your changes, you can revert them from the working copy:

          ++
          hg revert -a
++
          ++
          ++

          You can later re-apply the changes if you want to continue working on the ++patch:

          ++
          hg import --no-commit mywork.patch
++
          ++
          ++
          ++

          See also

          ++

          Refer to the FAQ for ++more information on using Mercurial.

          ++
          ++
          ++
          ++

          4.1.2. Preparation

          ++

          When creating a patch for submission, there are several things that you should ++do to help ensure that your patch is accepted.

          ++

          First, make sure to follow Python’s style guidelines. For Python code you ++should follow PEP 8, and for C code you should follow PEP 7. If you have ++one or two discrepancies those can be fixed by the core developer who commits ++your patch. But if you have systematic deviations from the style guides your ++patch will be put on hold until you fix the formatting issues.

          ++

          Second, be aware of backwards-compatibility considerations. While the core ++developer who eventually handles your patch will make the final call on whether ++something is acceptable, thinking about backwards-compatibility early ++will help prevent having your patch rejected on these grounds. Put yourself in ++the shoes of someone whose code will be broken by the change(s) introduced by ++the patch. It is quite likely that any change made will break ++someone’s code, so you need to have a good reason to make a change as you will ++be forcing someone to update their code. (This obviously does not apply to new ++classes or functions; new arguments should be optional and have default values ++which maintain the existing behavior.) If in doubt, have a look at ++PEP 387 or discuss the issue with experienced ++developers.

          ++

          Third, make sure you have proper tests to verify your patch works as expected. ++Patches will not be accepted without the proper tests!

          ++

          Fourth, make sure the entire test suite runs without ++failure because of your changes. It is not sufficient to only run whichever ++test seems impacted by your changes, because there might be interferences ++unknown to you between your changes and some other part of the interpreter.

          ++

          Fifth, proper documentation ++additions/changes should be included.

          ++
          ++
          ++

          4.1.3. Generation

          ++

          To perform a quick sanity check on your patch, you can run:

          ++
          make patchcheck
++
          ++
          ++

          This will check and/or fix various common things people forget to do for ++patches, such as adding any new files needed for the patch to work (note ++that not all checks apply to non-core developers). On Windows, use this ++command:

          ++
          ./python.exe Tools/scripts/patchcheck.py
++
          ++
          ++

          Assuming you are using the basic approach suggested earlier, ++just type the following:

          ++
          hg diff > mywork.patch
++
          ++
          ++

          If you are using another approach, you probably need to find out the right ++invocation of hg diff for your purposes; see hg help diff and hg ++help revisions. Just please make sure that you generate a ++single, condensed patch rather than a series of several changesets.

          ++
          ++
          ++
          ++

          4.2. Licensing

          ++

          For non-trivial changes, we must have your formal approval for distributing ++your work under the PSF license. Therefore, you need to fill out a ++contributor form which allows the Python Software Foundation to ++license your code for use with Python (you retain the copyright).

          ++
          ++

          Note

          ++

          You only have to sign this document once, it will then apply to all ++your further contributions to Python.

          ++
          ++
          ++
          ++

          4.3. Submitting

          ++

          If this is a patch in response to a pre-existing issue on the issue tracker, ++attach the patch to the issue; use the Choose File button on the tracker ++web page for the issue to upload your patch file. Please provide any details ++about your patch that ++would be relevant to the discussion of the issue or your patch.

          ++

          If this is a patch for an unreported issue (assuming you already performed a ++search on the issue tracker for a pre-existing issue), create a new issue and ++attach your patch. Please fill in as much relevant detail as possible to ++prevent patch reviewers from having to delay reviewing your patch because of ++lack of information.

          ++
          ++
          ++

          4.4. Reviewing

          ++

          To begin with, please be patient! There are many more people submitting patches ++than there are people capable of reviewing your patch. Getting your patch ++reviewed requires a reviewer to have the spare time and motivation to ++look at your patch (we cannot force anyone to review patches). If your patch has ++not received any notice from reviewers (i.e., no comment made) after one ++month, first “ping” the issue on the issue tracker to remind the nosy list ++that the patch needs a review. If you don’t get a response within a few days ++after pinging the issue, then you can try emailing python-dev@python.org asking ++for someone to review your patch.

          ++

          When someone does manage to find the time to look at your patch they will most ++likely make comments about how it can be improved (don’t worry, even core ++developers of Python have their patches sent back to them for changes). It ++is then expected that you post a new patch addressing these comments, and the ++review process will thus iterate until a satisfactory solution has emerged.

          ++
          ++
          ++

          4.5. Committing/Rejecting

          ++

          Once your patch has reached an acceptable state (and thus considered ++“accepted”), it will either be committed or rejected. If it is rejected, please ++do not take it personally! Your work is still appreciated regardless of whether ++your patch is committed. Balancing what does and does not go into Python ++is tricky and we simply cannot accept everyone’s contributions.

          ++

          But if your patch is committed it will then go into Python’s ++VCS to be released ++with the next major release of Python. It may also be backported to older ++versions of Python as a bugfix if the core developer doing the commit believes ++it is warranted.

          ++
          ++
          ++

          4.6. Crediting

          ++

          Non-trivial contributions are credited in the Misc/ACKS file (and, most ++often, in a contribution’s Misc/NEWS entry as well). This is something ++the core developer will do when committing your patch, you don’t have to ++propose the addition by yourself.

          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          3. Where to Get Help

          ++

          Next topic

          ++

          5. Running & Writing Tests

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/runtests.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/runtests.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,223 @@ ++ ++ ++ ++ ++ ++ ++ ++ 5. Running & Writing Tests — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          5. Running & Writing Tests

          ++
          ++

          Note

          ++

          This document assumes you are working from an ++in-development checkout of Python. If you ++are not then some things presented here may not work as they may depend ++on new features not available in earlier versions of Python.

          ++
          ++
          ++

          5.1. Running

          ++

          The shortest, simplest way of running the test suite is the following command ++from the root directory of your checkout (after you have built Python):

          ++
          ./python -m test
++
          ++
          ++

          You may need to change this command as follows throughout this section. ++On most Mac OS X systems, replace ./python ++with ./python.exe. On Windows, use PCbuild\python_d.exe or ++check the detailed Windows instructions. If using ++Python 2.7, replace test with test.regrtest.

          ++

          If you don’t have easy access to a command line, you can run the test suite from ++a Python or IDLE shell:

          ++
          >>> from test import autotest
++
          ++
          ++

          This will run the majority of tests, but exclude a small portion of them; these ++excluded tests use special kinds of resources: for example, accessing the ++Internet, or trying to play a sound or to display a graphical interface on ++your desktop. They are disabled by default so that running the test suite ++is not too intrusive. To enable some of these additional tests (and for ++other flags which can help debug various issues such as reference leaks), read ++the help text:

          ++
          ./python -m test -h
++
          ++
          ++

          If you want to run a single test, simply specify the test name as an argument. ++You also probably want to enable verbose mode (using -v), so that individual ++failures are detailed:

          ++
          ./python -m test -v test_abc
++
          ++
          ++

          If you have a multi-core or multi-CPU machine, you can enable parallel testing ++using several Python processes so as to speed up things:

          ++
          ./python -m test -j0
++
          ++
          ++

          If you are running a version of Python prior to 3.3 you must specify the number ++of processes to run simultaneously (e.g. -j2).

          ++

          Finally, if you want to run tests under a more strenuous set of settings, you ++can run test as:

          ++
          ./python -bb -E -Wd -m test -r -w -uall
++
          ++
          ++

          The various extra flags passed to Python cause it to be much stricter about ++various things (the -Wd flag should be -W error at some point, but the ++test suite has not reached a point where all warnings have been dealt with and ++so we cannot guarantee that a bug-free Python will properly complete a test run ++with -W error). The -r flag to the test runner causes it to run tests in ++a more random order which helps to check that the various tests do not interfere ++with each other. The -w flag causes failing tests to be run again to see ++if the failures are transient or consistent. ++The -uall flag allows the use of all available ++resources so as to not skip tests requiring, e.g., Internet access.

          ++

          To check for reference leaks (only needed if you modified C code), use the ++-R flag. For example, -R 3:2 will first run the test 3 times to settle ++down the reference count, and then run it 2 more times to verify if there are ++any leaks.

          ++

          You can also execute the Tools/scripts/run_tests.py script as found in a ++CPython checkout. The script tries to balance speed with thoroughness. But if ++you want the most thorough tests you should use the strenuous approach shown ++above.

          ++
          ++

          5.1.1. Unexpected Skips

          ++

          Sometimes when running the test suite, you will see “unexpected skips” ++reported. These represent cases where an entire test module has been ++skipped, but the test suite normally expects the tests in that module to ++be executed on that platform.

          ++

          Often, the cause is that an optional module hasn’t been built due to missing ++build dependencies. In these cases, the missing module reported when the test ++is skipped should match one of the modules reported as failing to build when ++Compiling (for debugging).

          ++

          In other cases, the skip message should provide enough detail to help figure ++out and resolve the cause of the problem (for example, the default security ++settings on some platforms will disallow some tests)

          ++
          ++
          ++
          ++

          5.2. Writing

          ++

          Writing tests for Python is much like writing tests for your own code. Tests ++need to be thorough, fast, isolated, consistently repeatable, and as simple as ++possible. We try to have tests both for normal behaviour and for error ++conditions. Tests live in the Lib/test directory, where every file that ++includes tests has a test_ prefix.

          ++

          One difference with ordinary testing is that you are encouraged to rely on the ++test.support module. It contains various helpers that are tailored to ++Python’s test suite and help smooth out common problems such as platform ++differences, resource consumption and cleanup, or warnings management. ++That module is not suitable for use outside of the standard library.

          ++

          When you are adding tests to an existing test file, it is also recommended ++that you study the other tests in that file; it will teach you which precautions ++you have to take to make your tests robust and portable.

          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          4. Lifecycle of a Patch

          ++

          Next topic

          ++

          6. Increase Test Coverage

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/search.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/search.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,99 @@ ++ ++ ++ ++ ++ ++ ++ ++ Search — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++

          Search

          ++
          ++ ++

          ++ Please activate JavaScript to enable the search ++ functionality. ++

          ++
          ++

          ++ From here you can search these documents. Enter your search ++ words into the box below and click "search". Note that the search ++ function will automatically search for all of the words. Pages ++ containing fewer words won't appear in the result list. ++

          ++
          ++ ++ ++ ++
          ++ ++
          ++ ++
          ++ ++
          ++
          ++
          ++
          ++
          ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/searchindex.js +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/searchindex.js Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,1 @@ ++Search.setIndex({objects:{},objnames:{},filenames:["gdb","silencewarnings","emacs","triaging","langchanges","buildbots","coverage","index","setupwindows","patch","stdlibchanges","faq","docquality","fixingissues","coredev","devcycle","setup","runtests","experts","clang","communication","grammar","documenting","developers","tracker","compiler","committing","help","coverity"],titles:["24. gdb Support","9. Silence Warnings From the Test Suite","23. Emacs support","12. Triaging an Issue","21. Changing the Python Language","19. Continuous Integration","6. Increase Test Coverage","Python Developer’s Guide","2. Setting Up Windows - Advanced","4. Lifecycle of a Patch","20. Adding to the Stdlib","29. Python Developer FAQ","7. Helping with Documentation","10. Fixing “easy” Issues (and Beyond)","14. How to Become a Core Developer","18. Development Cycle","1. Getting Started","5. Running & Writing Tests","22. Experts Index","28. Dynamic Analysis with Clang","13. Following Python’s Development","25. Changing CPython’s Grammar","8. Documenting Python","15. Developer Log","11. Issue Tracking","26. Design of CPython’s Compiler","16. Committing and Pushing Changes","3. Where to Get Help","27. Coverity Scan"],terms:{blogger:20,addop_jab:25,mailbox:[23,18],suspect:[27,19],enjoi:[14,20],wont:3,copyreg:18,analyz:[22,19,28],harder:[22,12],cannot:[15,17,3,0,19,5,22,9,6,28],cid:28,"_rlock":0,krah:23,mpatch:11,longest:5,languish:3,iceland:23,inclin:22,semant:[6,22,15,26],middl:[22,11],filecmp:18,shelv:18,benchmark:[25,18,3],abid:11,when:[],clean:[11,5,8],divis:21,conserv:[6,10],"0x0c327fff8810":19,stop:7,ticket:28,calcul:[25,6],timer:0,workflow:[],did:[24,14],venv:18,tackl:[12,1,13],span:[22,5],thread:[0,19,23,5,18],gaynor:23,alphabet:23,"3a0":5,five:22,audioop_getsample_impl:19,constant:22,reedi:[23,18],breviti:5,call_funct:[25,0],irix:22,xlinker:19,alexandr:[23,18],persist:5,alfr:25,stall:[22,14],doug:23,py_begin_allow_thread:22,previou:[6,22,11,10,15],git:[],over:[10,3,19,21,5,22,6],acronym:25,thisi:22,touch:[25,16,26,28],pycodeobject:25,putti:11,respond:[10,14,18],redzon:19,radio:11,lookup:25,everyon:[],"0x63f636":19,gone:[6,21,10],configpars:18,tex:23,mac:[16,17,18,3,19,7,22,23],legaci:[16,3],delimit:22,dev:[],brows:7,anoth:[10,26,3,4,7,8,9,6,11],testcwd:0,"0xd80160":0,segfault:22,move:[0,10,11,3],foremost:[4,14],"0x7fffe4001580":0,charl:23,need:[],head:[],"3regress":3,shift:[15,19],comment:[],settl:17,"0x000000000044060a":0,now:[15,26,3,23,24,25,6,11,14,28],parenthes:22,aurel32:19,absenc:19,stdio:[22,5],compiler_:21,suspici:[22,19,28],x86_64:[0,19,5],happen:[15,26,27,21,5,7,22,24,6,11,12],dozen:23,desir:[16,26,19,22,24,6,11],notabl:26,test_multiprocess:5,dec:23,interest:[26,18,3,27,19,5,20,7,22,24,6,12],chosen:[16,10,26,3,22,25],perl:8,return_kind:25,quickli:[22,1,24],ethan:[23,18],forum:11,four:22,variabl:[16,19,22,25,11,28],melodramat:14,project:[],"return":[0,19,22,25,11,28],stringo:0,him:[23,3],func:22,displai:[],proce:[4,1,8],facil:22,regrtest:[],johann:23,notifi:26,sens:6,anyon:[9,7,11,27,14],temporari:0,printf:22,depth:[25,22,26],brace:22,requir:16,consumpt:[22,17],focus:[7,11,22,20],rerun:21,repo:[11,3],wish:[6,27,11,5,14],yasskin:23,"0x000000000041a6b1":0,examin:[11,19],asyncio:18,match:[16,17,21,0,22,11,14],doesn:[16,26,3,0,22,6,11,28],commonli:22,modifi:[],rchild:25,chest:19,someon:[10,26,3,21,9,11,12,14],emerg:9,wolev:23,follow:[],spare:9,tab:22,nitem:22,inclus:[27,10,26],productionlist:22,pend:[11,3],spammi:26,macintosh:3,test_contain:5,numer:[25,22],curiou:22,initi:[],turtl:[23,18],toolkit:7,"long":[],pat:23,unforeseen:26,job:6,posixmodul:28,argpars:18,associ:[11,26],same:[],irmen:23,malform:22,try_stmt:22,classif:[13,28],appear:[6,22,11,26,3],diagnos:[0,5],foster:11,xicluna:23,meaning:22,namespac:[25,22],shutil:18,amet:22,portion:[4,19,10,22,17],asdl_seq_len:25,py3:18,revert:[],team:[22,23,24],pwd:[6,18],overhead:15,have:[],dylib:19,readm:[16,8],uncov:[19,12],rodrigo:23,come:[],libclang_rt:19,multi:[16,17,3],where:[],instanc:[16,0,19,22,24,25,6],warn:16,next:[15,3,4,19,5,22,24,25,9,11],substitut:[],none:[22,0],run_test:17,sandro:23,jackilyn:23,java:[7,28,18],side:[25,22,26],reput:14,randal:23,sax:18,imperfect:5,disput:11,lang:20,toolset:[22,23],librarydepend:19,monson:23,dictat:[4,10],typic:[15,16,1,10,3,26,4,27,22,8,25,6,11,13,14],dpy_build_cor:19,bleed:6,attempt:[22,0,11,13,8],strive:6,throwflag:0,"0x0c327fff8800":19,exploit:15,georg:[15,23,18],bac:23,distclean:11,ambassador:14,from:[],declar:25,"_condition__lock":0,principl:[25,26],snippet:22,anew:16,meador:[23,18],dakshesh:28,treat:[11,10],error:[16,26,17,3,27,0,19,7,22,24,8,6],signifi:22,inc:19,contrib:23,pseudo:22,uncheck:[16,28],primari:[25,22,20],openhatch:16,search:[10,3,19,5,7,22,24,25,9,11],livinglog:6,freed:[25,19,28],higher:[0,11],egg:22,shell:[22,11,2,17],"0x99262ac":0,render:[22,18],forgeotdarc:18,establish:[22,10],intrus:17,underli:0,enough:[15,16,26,17,3,19,5,22,24,12,13],pyconfig:[11,26],lib2to3:[18,3],studio:16,minimum:[19,16],origin:[25,0,26,23],urllib:18,back:[],luck:5,layout:24,jython:[7,23],peer:15,encount:[22,19,16,27],pyobject_fre:19,clariti:[22,19],jess:23,expans:22,directli:[10,26,3,18,0,22,23,25,11,12],summari:[],guilabel:22,horribl:6,truncat:0,rodolà:23,pyimport_importfrozenmoduleobject:19,binascii:18,asdl_seq_get:25,supersed:[],peephol:25,newsgroup:[22,20],space:22,invalid:[22,3],oparg:0,comma:22,oct:[22,23],pyunicodeucs2_decodeutf8st:0,outlin:[25,11,16,10],ever:[9,7],killer:2,prescod:23,implic:[22,3],"function":[16,10,3,0,19,21,20,22,8,25,9,6,11,28],solid:27,"0x7fff80fff010":19,maxdepth:22,"export":[19,26],thoma:23,todai:22,sentenc:[],reilli:11,me_valu:0,alwai:[15,16,26,3,0,7,22,24,6,11,12,13,28],her:3,fsf:2,hit:2,matur:[11,10,28],pool:25,timestamp:16,invoc:[9,22],gregori:[23,18],"3to2":23,machdep:19,perform:[15,16,3,19,9,11],deprec:22,deriv:22,"_wait":0,modern:6,python_d:[7,16,8,17],blai:23,accomplish:22,lookdict_str:0,forc:[25,9,10,5,8],vinai:18,contextlib:18,pulldom:18,deviat:9,creat:[],win:11,bsd:18,"_pyobject_debugmallocapi":0,crash:[22,0,15,3],liststor:0,isn:[],whenev:[22,16,14],me_kei:0,packag:[16,10,3,18,0,22,23,25,6,11],jong:23,lift:22,curli:22,issue12345:26,stat:[6,18],through:[16,10,26,4,19,20,7,22,25,6,11,28],intermedi:[25,26],jul:23,convert:[25,22,11],pick:[16,10,24],met:[11,10],"0x7fff80fff008":19,big:25,submodul:22,usenet:22,arbitrari:[25,22],piec:[25,22,16],symlink:0,ssh2:11,great:[6,16,10,24],minut:6,err:22,time:[1,3,4,27,9,11,26,19,21,20,24,6,17,5,13,14,15,18,0,22,23,25],waldman:23,cryptographi:18,fast:[26,17],repeat:[22,11,26,17],carlson:23,bump:25,selivanov:23,stdout:[22,11],py_debug:16,explan:[4,22,12,26],plu:[25,16,20],"0x0c327fff8820":19,includ:[16,10,2,3,26,17,27,19,21,20,22,23,24,25,9,6,11,12,28],python2:[22,0],unlik:[11,26,23],exc:22,yselivanov:18,perman:[0,11],distutils2:3,those:[15,16,26,0,7,22,24,8,25,9,6,13,14],abbrevi:[25,22,20],mdc2:8,extra:[15,16,1,17,0,24,25],trace:[6,19,18],platform:[],pyobject:[25,22,0,28],broke:21,talin:23,gijsber:23,ullman:25,load:[],firm:24,miss:[16,26,17,19,7,22,8,6],didn:26,saved_st:0,record:[6,4,11,26,5],pystentryobject:25,roi:23,write:[],assist:[22,11,16,27,3],manpag:22,inact:[],frequent:[7,11],thank:[25,26],read:[],"0xb771b7f4":0,"0x3dbdf85820":0,program:[16,10,2,4,19,22,25,11,12,28],concentr:15,scoder:18,qpop:11,boutsiouki:23,call:[10,2,5,22,25,9,11,28],win32:8,test_subprocess:5,supervis:14,situat:[6,3],ma_smallt:0,compiler_visit_xx:25,misalign:19,home:[25,0,19,5,14],microsoft:[22,16,8],qualif:22,lost:22,"0x0c327fff87f0":19,poor:6,issue10991:6,pdb:[2,18],pyframeobject:0,com:[25,11,5,28],accept:[],hightow:23,condens:9,coveragepi:6,append:6,websit:[6,28],jlt63:18,mous:22,diederich:23,hashlib:[22,18],jerri:23,stutzbach:[23,18],etre:18,jvr:18,sln:[7,16,8],person:[10,26,3,18,4,0,24,9,14],unexpect:[],pickletool:18,also:[3,4,8,9,11,10,26,19,21,20,24,6,17,5,7,12,13,14,15,16,18,22,25],gerhard:23,helper:[25,6,17],trigger:[6,27,5,3],bad:[22,11],ascii:23,"short":[22,0,26,24],connect:[25,22,28],complic:22,hasn:17,rememb:[27,11,26,3],rww:5,exactli:[4,5],identifi:[16,3,19,22,25,11],servic:[15,28],grouper:22,might:[16,26,3,19,5,22,24,25,9,6,11,12,14,28],string:[25,22,0,14,18],subsect:22,exit:25,pretti:0,removenam:22,web:[16,26,3,5,20,22,9,6,11],name:[15,16,26,17,3,18,27,0,5,20,22,23,24,8,25,6,11],prose:22,wang97:25,"catch":[16,26,20],bar:22,reprlib:18,xdrlib:18,copi:[],structur:[],"_testmethodnam":0,remind:[9,11,15,3],paramet:[25,22,11,19,5],contain:[16,10,17,3,27,0,19,21,5,22,8,25,6,11,12,14,28],privat:[11,26,20],server:[11,12,26,5],deco:22,occasion:[26,3],parenthesi:18,select:[16,18,3,0,7,22,24,8],simpl:[15,26,17,22,25,11],mytestsequ:5,bit:[16,26,19,22,8,6,14],likewis:22,py32:11,total_tim:0,mayb:26,doerwalt:18,mandatori:26,martin:23,der:23,reader:[22,20],qualiti:[4,19,10,12,14],opcod:[25,22,21],lock:0,pmoodi:18,mai:[16,10,26,3,17,18,4,21,5,7,22,23,24,8,25,9,6,11,12,14,28],abil:[23,26,24,14],len:0,admin:[],"0xaa4560":0,aimacintyr:18,cours:[18,0,26,5,14],sequenc:[25,22,5],successfulli:26,tosi:23,visit_slic:25,gdb:[],markup:[],snapshot:7,"0x0c327fff87c0":19,consum:0,consult:[22,3],ziadé:23,backlink:22,newer:[0,11,23],forward:[15,26,3],properli:[16,10,26,3,17,0,22,24,25,6],untest:6,maxim:5,bother:14,trunk:23,widen:18,holth:23,inplac:6,ippolito:[23,18],literalinclud:22,misread:22,address:[9,22,0,26,19],plistlib:18,disabl:17,split:[],pain:10,plan:15,alloc:25,rang:[10,27,0,22,11,28],"0x000000000041b717":0,except:[15,16,26,3,18,0,22,8,25,6,12],exercis:[6,26,5],mime:22,langa:[23,18],unreport:9,bug12345:26,optpars:18,cc_kext:19,emsli:23,gfb:23,"0x00000038e46d73e3":0,criteria:26,interconnect:22,wherev:16,pydebug:[7,16],jone:23,uncommon:24,login:11,hash:0,self:[22,0,19],pythonpath:6,gsd:0,creator:[22,10],recompil:[25,16,26],"0x7ffff7f14360":0,nice:[6,26,14],unix:[],later:[],tediou:5,databas:[24,18],justifi:11,cgi:18,laid:25,fedora:16,gvanrossum:18,sinc:[15,5,22,23,25,6,11,28],therefor:[15,26,5,22,9,11,28],test_threadsign:5,theller:18,test_python_29628:5,flexibl:23,inher:22,pyarena:25,screen:14,vya:28,mere:11,fwrapv:19,hast:[15,23],fellow:14,year:[15,10,21],independ:25,heurist:[22,11],highli:11,you:16,solari:18,ahead:4,whose:[25,9],omiss:21,allevi:10,sever:[],oussoren:23,commun:[],subject:23,arriv:10,success:[22,13,5],reach:[26,17,5,25,9,11,13],ftplib:18,link:[],sporad:[26,5],thu:[15,16,10,3,0,22,25,9,6,11,14],"final":[],pyclbr:[21,18],qpush:11,must:[15,16,10,26,3,17,18,4,21,5,22,8,25,9,11,12,13,14,28],understood:[4,28],led:25,datatyp:22,price:23,effect:[6,22,26,24],tabnanni:18,children:[25,22,11],stricter:17,pull:[11,26,28],decemb:23,end:[16,10,26,3,4,0,19,22,24,25,6,11,14],mailcap:18,py33:11,curtin:23,malloc:28,look:[3,0,19,5,22,24,25,9,6,11,12,13,14],convers:[25,11,3],confirm:5,termio:18,googl:5,misstep:22,sizeof:28,itertool:[22,10,18],belong:[22,16],gener:[],angl:22,someth:[15,10,26,3,4,20,22,24,25,9,6,11,12],"0x7fffd00019d0":0,tracker:[],mono:7,fifth:9,setnewnam:22,sourc:[],equival:[],cwd:0,mateusz:23,pylong_fromlong:28,dom:18,"0xc9c790":0,roger:[23,18],sometim:[15,16,10,26,17,19,5,20,25,11,28],fulli:22,ipsum:22,dereferenc:28,mimic:26,satisfi:11,issue10541:6,internet:[22,17],mailhead:22,misc:[16,26,0,7,23,24,9],run_dialog:0,ken:23,everyth:[15,26,21,19,8,6,11],bundl:11,affect:[16,3,20,22,24,25],urgenc:3,rfc:22,sirolf:23,michael:[25,23,18],testsrun:0,bquinlan:18,pylongobject:[0,19],auto:[],whole:[22,26,5],debugg:[0,23],contribut:[],cmath:18,sunau:18,net:[25,7,2,20],i18n:18,paper:[25,26],"0x00000000004466aa":0,prior:[17,16,26,14,3],storchaka:23,alpha:[],traction:27,incorrect:11,unimport:6,triager:[27,26,24,14,3],first_nam:14,topic:[22,18],test_poplib:5,"0xd75160":0,"0x984b474":0,stale:25,"0x3dad39f5e0":0,discourag:22,"_64_x2_dual_core_processor_4400":5,loewi:[23,18],overcom:[0,16],exhaust:25,sampl:22,ssh:[],winsound:18,firefox:7,distutil:[18,23,3],bottom:[22,0],activ:[],constitu:10,want:[],she:23,exact:[25,22,27,5],fijalkowski:23,wang:25,camel:22,descend:[11,15],demo:3,beginn:7,older:[9,0,16,10,26],victor:[11,23],front:[0,19],chapter:22,"class":[25,9,22,10,3],asan_symbol:19,lifecycl:[],javascript:[24,3],"_cleanup":0,spwd:18,succe:[26,5,8],ack:[9,26,24],publicli:[10,20],latin:23,asdl_seq_set:25,parent:[22,11],child:[25,22],hook:[],inde:11,diff:[9,11,16,26,3],gsoc:[23,3],determin:[22,16,24],electron:26,vptr:19,tid:0,soc:23,verif:11,dif:26,autotest:17,inter:5,tweak:[11,16,21],transliter:23,"0x98faaa4":0,speaker:22,nasty_eq_vs_dict:0,filesystem:[16,5],translat:[23,3],between:[],here:[16,26,17,27,0,19,5,20,7,22,23,25,12],cc_kext_ios5:19,sai:[15,1,3,22,6,12,14],saved_at:0,broken:[9,22,15,24],corner:22,asan_osx:19,anthonybaxt:18,prune:6,addon:8,refus:26,litter:22,relicens:26,denial:15,versionchang:22,asyncor:[23,18],holden:23,softwar:[9,16,24,14],c89:[16,28],parser:[16,18,3,4,19,21,22,25],lowercas:3,transpar:11,planet:20,size:[0,19,28],favorit:[6,22],flush:22,crasher:0,pyobject_head:22,functiondef:25,hint:0,tgp:23,bodi:[25,6,22,16],"0x681d77":19,struct:[25,22,18],credit:[],committ:[20,23,26,14,18],linkcheck:22,pycon:23,some_python_integ:0,lightweight:7,kuchl:23,addop_nam:25,hardwar:[24,5],man:11,amount:[25,4,10,26,3],edg:[25,6],bedivier:23,deepli:22,unrel:[11,26],recurs:[11,5],kei:[],item:[25,22,18],handi:[22,26],maintain:[15,16,10,2,26,18,7,22,23,9,6,11,12,28],obvious:[9,6,14],pyobject_malloc:0,elimin:1,least:[16,10,26,5,22,24],branch:[],act:[24,3],describ:[16,3,4,19,7,22,24,8,25,11],wall:19,uppercas:22,behind:18,insid:[],alreadi:[],dummy_thread:18,lsan:19,bch:25,soon:5,"_my":22,promptli:14,ravi:25,creation:25,daniel:[25,23],no_sit:5,out:[],press:[16,26,3],occurr:22,apart:26,live:[23,16,12,5,17],instruct:[16,26,17,3,21,7,22,24,25,6,11],thought:[25,1],librari:[16,26,17,3,19,21,5,7,22,23,8,25,6],restor:11,audioop_getsample_imp:19,slice:25,dot:[22,28],disk:26,stack:[0,26,19],swappablearea:0,userprofil:26,modif:26,seri:[25,9],"static":28,mismatch:16,decor:[25,22],weekend:13,valgrind:19,bitbucket:[6,26],"0x7fffac0011c0":0,netbsd1:18,sleep:0,"0xd802e0":0,who:[],spam:[22,26],aho86:25,ignore_environ:5,cole:23,specifi:[10,26,17,3,19,22,25,6,11],ten:24,"__libc_start_main":19,necessari:[15,16,26,3,7,22,8,11],good:[10,26,3,4,19,5,7,22,24,8,9,6,11,12,14],serra:25,csu:19,fleme:23,csv:18,scope:[25,9,19,16],divers:11,august:23,report:[],shall:5,given:[15,16,18,0,5,22,23,24,25,28],singl:[],py27:11,allison:23,lukasz:18,auto_fil:0,instead:[],aris:[6,0,16],option:[15,16,10,26,17,27,0,19,5,22,25,9,6,11],"0x00000000004cd1e6":0,carefulli:22,"0x6d72c0":0,synopsi:22,nntp:20,section:[],wait:[0,5],"0x0c327fff8840":19,approv:[9,11,23,28],hopefulli:[5,14],proper:[10,26,4,5,24,25,9,6,11],backward:[9,10,26,3],"0x7fffd00024a0":0,setup:[],buggi:19,meant:[16,10,26,18,4,22],circumst:16,mean:[16,10,26,5,22,25,11,12,14],uniform:10,ubsan:19,"0xad4730":0,dbm:18,gregorlingl:18,dure:[6,22,15,16,19],virtu:10,module2:11,tend:10,forth:22,copyright:[9,22,26,14],omit:[6,22,11,26],getpass:18,mode:[15,16,2,17,22,24],"0x7ffff7fe2700":0,subsubsect:22,unifi:26,"0x0000000000440d1b":0,foord:[23,18],closur:25,besid:22,defenc:0,last:[],under:[15,16,1,10,26,17,19,22,9,6,11,14,28],respect:[26,3,22,25,9,11],than:[],verifi:[9,6,11,14,17],devguid:[18,11,12,3],ma_tabl:0,schuppeni:23,ncoghlan:18,"enum":[25,18],sourceforg:[25,23],versa:[16,26],plain:22,zero:25,unprocess:26,neworsavedgameselector:0,appl:16,tarfil:[23,18],"0x984b464":0,groupbi:22,preserv:16,reason:[26,3,4,21,5,22,9,11],hmac:18,slightli:[22,11,16],myriad:20,test_urllibnet:5,cut:[22,15,26,5],josiahcarlson:[23,18],header:[25,22,16],nntplib:18,winreg:18,path_convert:28,va_copi:28,repositori:[],lead:[25,6,22,10],version_requir:11,suddenli:25,xemac:[22,2],can:[],environ:[7,11,16,22],distinct:5,runpi:18,socketserv:18,raymond:23,"0x0000000000446647":0,differ:[],lorem:22,renam:11,tie:25,idlelib:[18,3],februari:23,pyspecif:22,rej:[11,26],addop_i:25,proceed:25,put:[15,26,7,22,8,9,14],frank:[23,18],fortun:27,alexand:23,upper:8,gcc:[6,19,5],pass:[],transform:25,few:9,stackoverflow:11,joel:11,deili:[23,18],leav:[22,11,12,13],excel:11,signific:[22,11,10,26],schlawack:23,c99:[16,28],essenti:25,bug:[],carri:4,word:[22,26,24,18],whitespac:[],sanction:10,sent:[9,11,12,23,20],"_modulesetupfail":0,linux:[16,18,0,19,5,28],noindex:22,ronaldoussoren:18,nosi:[],how:[],whatev:22,turn:[16,10,3,5,25,6,13,14],plai:[25,0,17],advanc:16,unconvert:22,"__block":0,done:[15,16,10,3,22,23,24,25,6,13,14],tailor:17,benediktsson:23,specul:27,collaps:26,pub:11,retain:[9,14],meth:22,store:[25,22,11,16],foundat:[9,14],occur:[15,4,19,20,22,8,25],dino:23,queri:25,yuri:23,"22ae2b002865":5,belopolski:[23,18],sign:[],msvcrt:18,support:[],overal:[6,11,10,14],freenod:[27,11,20],gpolo:18,cleanup:[25,17],ob_refcnt:0,bytes_warn:5,"0x0c327fff87e0":19,kdiff3:11,advis:27,cond:0,pytypeobject:22,basi:[19,26],pycodegen:25,across:[27,10,24],seek:27,sqlite3:18,maupin:23,assumpt:22,attach:[10,3,23,24,9,14],decim:[23,18],encourag:[7,11,27,17],"throw":[7,11],compat:[15,10,26,2,3,7,23,9],qualifi:[],acquaint:[6,5],bang:21,paul:23,surpris:[22,14],demonstr:[25,22],dialog:[22,0,11,26],qdelet:11,launchpad:2,friendli:2,subscrib:[12,14,20],somework:11,timeit:18,paragraph:[],"0xd80260":0,dare:6,jeroen:23,van:[22,23],meet:[10,14],dep:16,beta:[],intern:[],"__version__":25,boolop:25,failfast:0,highlight:22,nomenclatur:15,customarili:[22,26],selector:18,close:[15,26,3,0,22,24,11,13],fine:8,makefil:[22,19,5,18],gave:[24,8],clear:[26,3],aspect:[22,11,28],field:[],futur:[15,18,4,22,23,14],bandwidth:26,serious:4,writabl:0,indent:22,typedef:25,process:[],stderr:16,easili:[7,22,16,26],your:[16,10,2,26,17,4,0,21,27,5,7,22,24,8,25,9,6,11,12,14,28],"_is_own":0,combin:[25,11,19,5,28],hotshot:23,buildbot:[15,16,3,18,5,7,8],slowdown:25,delic:5,logo:[11,24],express:[],andrew:[25,23],earlier:[],keygen:11,framework:3,ironpython:[7,23],bell:22,peterson:[15,23,18],zephyr:25,symtable_exit_block:25,product:[],batchfil:22,conflict:[],faster:[22,11,26,5],eglibc:19,count_own:0,clutter:[22,11],"try":[16,1,26,17,27,0,5,22,24,9,6,11,12,13],tool:[],pydictobject:0,appreci:[9,12],enjoy:14,checkin:[28,23,26,14,20],forgot:11,"0x7fffb8001c40":0,releas:[],announc:[24,14,20],help:[],reserv:3,signal:[5,18],extend:[26,18,0,22,23,14],legal:14,built:[16,17,3,0,7,22,8,11,12],unladen:23,fit:3,poison:19,grammar:[],sep:23,dialog_swallow:0,adapt:23,rebas:26,foo:22,ma_mask:0,getopt:18,cstringio:0,chm:22,judgment:22,rpartit:22,institut:23,wierzbicki:[23,18],kelsei:23,florent:23,too:[26,17,3,22,23,24,14,28],descript:[25,22,24,3],arena:25,jan:23,"2to3":[23,3],jafo:18,drawback:6,sajip:18,lurk:12,adventur:13,challeng:[7,13],overflow:[19,28],obtain:[11,16],furthermor:5,batch_siz:0,secur:[],ob_typ:0,deal:[22,5],user:[15,10,26,4,19,22,23,24,11],cprofil:18,realm:[15,5],msvc:16,edit:[],breakpoint:2,seealso:22,glob:18,"true":[25,22,0],mimetyp:[22,18],detect:28,jvm:[7,18],agre:[11,10,14],pdbtrack:2,recip:10,org:[16,10,2,3,26,19,5,20,7,22,23,25,9,6,11,12,14,28],adjunct:22,alias_for_import_nam:25,diverg:10,channel:[],burden:[10,24],randse:5,"_gc_head":19,yet:[16,26,27,24,28,14],temp_cwd:[0,26],compiler_new_block:25,like:[15,16,26,17,0,19,21,7,22,24,25,9,6,11,14,28],sub:22,rais:[22,11,26],base:[15,16,10,26,4,22,23,24,25,6,11,28],said:22,test_unicod:5,memcpi:28,befor:[15,16,10,26,3,21,5,20,22,23,24,8,25,9,6,11,14],realiz:[25,6,4,16,24],forgeot:23,dictionari:[22,0],declin:11,"0x0c327fff8850":19,ground:[9,28],absolut:[25,6,5],ronald:23,readabl:[22,26],cleanli:24,throughout:[25,22,17],were:[16,26,3,27,23,24,25,6,11],reid:23,dark:6,text:[26,17,5,22,6,11],uuid:18,confer:25,skip:[],"__future__":18,shadow:19,first:[15,10,26,17,3,4,27,5,22,23,24,25,9,6,11,14,28],dndebug:19,rossum:[22,23],nest:22,lwp:0,caption:22,felt:16,oldest:[15,26],some:[],well:[16,26,3,27,0,21,22,24,9,11,12,14],similar:[25,22,0,11],rel:[25,22,26,5],neg:[25,4,19,28],object:[],been:[15,16,1,10,3,26,17,4,21,5,7,22,23,24,8,25,6,11,13,14],trent:23,idea:[10,4,19,27,20,8,11],"0xd7ff40":0,backtrack:7,jack:23,quiet:[0,16,5],benefit:[4,13],dai:[26,16,3,9,12,13,28],bin:[19,16],infrastructur:[10,26,28],submenu:22,whitebox:6,collect:[11,21,18],chri:[25,23,26],"_rlock__count":0,thei:[15,10,26,17,3,18,0,19,5,20,7,22,23,24,25,9,6,11,12],respons:[],clarifi:[22,15],test:[],mutabl:22,tutor:11,latex:22,ask:[],habit:11,implement:[],tew:23,startup:[6,11,16],einat:23,giampaolo:[23,18],steven:23,changelog:26,indic:[15,16,26,18,3,22,11],data:[10,18,22,25,6,11,28],excess:22,consid:[15,10,26,2,3,4,22,25,9,11,12,13,14,28],ellipsi:22,c17d7772c638:11,restructuredtext:[],seriou:3,feel:[18,27,7,22,11,13],align:[22,19],"0x7fffac001640":0,sysconfig:[19,18],sticki:11,config:11,furman:[23,18],mind:22,"\u00e9ric":23,feedback:10,collabor:26,share:[11,16,10,26],overview:[22,16],strictli:11,gentoo:5,wget:19,tortoisehg:[11,16,26],becaus:[10,26,3,4,19,21,22,24,8,25,9,6,11,13,28],jit:[7,23],api:[22,10,3],differenti:[22,11],enabl:[26,16,17,3,0,19,5,22,24,11,28],py_ssize_t:22,predict:22,each:[15,16,26,17,18,5,7,22,24,8,25,9,6,11,12],rlcomplet:18,role:[],reflect:[22,11],"0x5c2b8d":0,selen:11,runtim:[7,19],etc:[15,16,10,26,3,19,5,20,22,24,8,25,6,11,12],pyarg_parsetupleandkeyword:28,noth:3,target:[25,22,16,3],appel:25,snip:0,note:[16,26,3,0,19,7,22,23,8,9,6,11],intend:[16,10,18,21,22,11],experienc:[9,7,11,27],exec:25,init:[11,19],place:[15,16,10,26,18,21,20,22,25,6,11],test_trac:6,vassalotti:[23,18],off:[25,22,14],machineri:18,ma_fil:0,onlin:[7,11,10,22,8],pypi:[7,22,23],legend:19,realli:[26,28],"null":[],abl:[26,3,0,24,6,14,28],hyphen:22,fpectl:18,dalk:23,buildarea:5,cov:28,jónsson:23,handler:[25,18],knowledg:[22,16,24],ceval:[25,0],have_argu:25,claim:28,quit:[9,22,0,11,13],defin:[25,22,11,26],themselv:[25,26],"0x858860":0,test_bool:5,some_machine_integ:0,python32:8,index:[],"0x4e6894":19,anywher:11,spolski:11,color:11,symtable_enter_block:25,amazon:25,macpath:18,"import":[],start_gam:0,viehland:23,approxim:[22,26],devel:11,yield:25,impact:[9,3],explicitli:[22,11,28],emphas:22,monti:[22,26],"break":[15,26,25,9,12,14],tip:[22,11,28],profile_m:0,despit:22,second:[10,26,22,25,9,11,14,28],letter:22,notat:22,expertis:18,msan:19,insensit:[16,3],maximum:[22,28],again:[15,10,17,4,5,22,8,11,14],compress:[11,16],reject:[],svetlov:23,uall:[11,5,17],cell:25,iinclud:19,referenc:[25,22],shortest:17,"0x7fffdf5fe710":0,content:[],lineno:25,writer:22,shortli:22,quickest:5,ham:22,repr:0,variant:28,dfn:22,puttygen:11,explain:[16,10,26,4,5,22,24,25,28],down:[17,0,20,5,22,25,14],symbol:[25,22,21,18],customari:26,synthet:11,filter:22,presum:22,rebuild:8,produc:[26,19,5,22,8,11],wipe:8,"const":[25,22],until:[26,3,19,21,5,22,24,9,11],understand:[26,7,22,25,14,28],thousand:19,unfortun:[6,22,11,19,1],against:[9,11,24],"float":0,even:[15,16,10,26,3,19,5,7,22,24,25,9,11,14,28],could:[26,19,22,23,6,13],larg:[25,4,7,10],provid:[16,10,26,3,17,0,19,5,7,22,23,24,25,9,6,11,13],popular:[6,22,16],dealloc:25,tsan:19,nois:19,after:[],ini:26,session:[22,0,11],bat:[],extern:[],reliabl:5,smith:[23,18],offend:[11,16,5],uniniti:28,textwrap:18,liter:[25,22],achiev:[22,11],formatt:18,parti:[10,18,7,8,6,11],suit:[],"0x858770":0,concept:[7,22],complain:22,"0x619000004020":19,netrc:18,doubt:[9,6,3],py3k:[7,11,23],debian:16,complex:[25,22,10],potenti:[22,11,5],impossible_hint:0,lot:[10,26,0,22,11,12],profession:8,yourself:[3,9,6,11,28,14],proport:4,cookbook:10,whichev:9,ubsan_osx:19,vast:16,keyboard:0,parsermodul:21,speed:[7,23,24,17],checkout:[],coverity_model:28,tkinter:[18,3],poplib:18,pygc_head:19,involv:[26,10,18,27,21,5,22,24,25,12,14],keyword:[],simplest:[11,17],silenc:[],rather:[16,26,18,0,20,22,25,9,11],advers:5,tempt:16,errno:18,posit:[],modulefind:18,standalon:22,ochtman:5,mkdef:8,asap:14,dedic:[28,22,26,5,14],local:[],src:19,hexadecim:0,calderon:23,"0x000000000041b7c0":0,libc:19,conveni:[0,11,26],howev:[16,26,0,19,22,8,25,11],portabl:17,aka:[25,19],trim:5,hat:16,longobject:19,intro:22,divid:11,ncn:23,osu:28,terminolog:[7,15,22],ziga:23,bob:[23,18],dolor:22,haypo:18,cost:16,repres:[26,17,0,19,22,25,14],printer:0,asan:19,prefer:[16,26,22,9,6,11],resolv:[16,26,17,3,8,25,11],clees:22,sudoku_mak:0,rukowicz:23,subproject:8,bogu:26,graphlog:11,exampl:[],left:[15,3,19,22,24,6,13],kristján:23,contemporan:23,heiko:23,expectedfailur:0,apr:23,ping:9,ubuntu:16,found:[16,1,10,17,0,19,5,20,7,22,24,8,25,14],virtual:[7,28],label:[22,26],"0xc185a0":0,bracket:22,expr_ti:25,narrow:[11,5,28],unclear:12,shinner:23,intellig:22,octob:23,reindent:26,yum:16,yield_kind:25,fashion:24,more:[15,16,1,2,10,26,17,18,19,21,5,7,22,24,25,9,11,12,14,28],scarlet_pimpernel:0,past:[22,15,26,5],assert:[25,5],"__cached__":0,mail:[],recommend:[26,17,2,5,7,23,11],almost:26,"_stmt":25,histori:[],attack:15,ppk:11,python3:16,compiler_visit_stmt:25,philip:23,versionad:22,owner:[0,28],daili:[7,11],site:[16,18,0,22,6,11],bruynoogh:23,astrand:18,"_acquire_restor":0,littl:[10,3,4,5,6,12,14],core:[],insult:14,gettext:18,graminit:[25,21],pydotorg:11,block:[25,22,8,3],comp:20,"_type_equality_func":0,sparingli:22,brian:23,effort:[23,12,3],due:[22,11,19,17],makeopcodetarget:16,verbatim:22,network:[27,5,18],whether:[15,10,26,3,4,19,22,24,9,11],token:[25,22,21,18],"public":[],moduleauthor:22,pkgutil:18,x64:8,"0x3dbdc7ea70":0,snow:[23,18],folk:26,hale:23,bsddb:23,josiah:23,expert:[],real:[19,16,3],opinion:[11,20,18],pybench:18,newest:26,"int":[25,0,28],ast_for_xx:25,b1ddcb220a7f:11,roughli:[15,12],addop:25,f12ef116dd10:11,afterward:[26,3],analog:0,within:[],along:[16,4,22,25,6,11,12,14,28],bisect:[11,5,18],smtpd:18,unsur:26,mock:18,guard:[25,11],newcom:22,interact:[22,11,5],gaug:10,thorough:17,csid:11,toolchain:[22,12],kipp:23,special:16,john:[22,23],mani:[26,3,19,20,22,24,8,9,6,11,28],node:[25,22,16],weigh:22,grasp:[22,24],whom:22,pythonrun:19,clow:19,freebsd:18,bring:13,active_tim:0,agent:11,no_user_sit:5,hazi:4,especi:[16,26,3,27,22,24,11],still:[],bound:[22,19],graphic:[11,16,26,17],abc:[6,18],math:18,assign:[],code:[],own:[16,17,20,22,23,24,25,6,11,28],jean:23,credenti:11,workshop:[25,22],smooth:17,"_original_stderr":0,compileal:18,eventu:[9,4],statu:[],bugfix:[9,15,10,26,5],"_ios_fmtflag":19,test_augassign:5,hard:3,addop_jrel:25,load_attr:25,satisfactori:9,libpython3:19,unless:[25,16,26,28,18],try2_stmt:22,teach:17,tmp:16,iter:[9,22],magic:25,subsequ:[22,11,26],remain:[7,26],seed:5,awai:[25,22,11],enclos:22,visibl:[6,11],aronach:18,resourcewarn:1,rdh:23,test_functool:5,element:[22,26],xxx:19,"__lltrace__":0,inject:22,opt:8,current:[],sit:22,"0x7fffb8001a10":0,loop:[25,22,0,16],normal:[16,26,17,3,19,22,12],percentag:4,nullabl:28,intermediari:28,rarer:7,send:[22,10,26,14,20],specialbuild:16,endian:5,"_start":19,pylib:6,wiki:[22,11,24],just:[16,26,27,19,21,5,22,25,9,6,11],lose:[11,12],alexi:[23,18],macro:[25,22],montanaro:[25,23,18],definit:[16,3,7,22,25,6,11],valid:[6,22,12,26,24],shown:[25,22,0,24,17],mulich:23,profile_io:19,timeout:[0,5],python:[],heavi:22,obido:25,region:19,client:[20,11,16,5,8],fdrake:18,sysv:0,choos:[16,7,22,25,9,6,11],runner:[17,5,3],amauri:[23,18],blog:[],pyast_compil:25,"3rd":[6,7],parrot:[22,23],imposs:5,"_mirroroutput":0,floor:21,doe:[],jesu:23,gregor:23,categori:[6,22],nadeem:[23,18],openssl:8,verbos:[5,17],length:[25,22,0,28],instrument:[6,19],"char":[0,28],arg:[25,28],accident:16,distinguish:0,month:[9,15,23],newsread:20,sibl:15,batista:23,usr:[22,0,16,19],save:[22,11,26,24],unnecessari:16,hellmann:23,linker:19,svn:[22,0,23,3],fnmatch:18,though:[16,19,22,24,25,6,11,13],ma_lookup:0,pyarena_fre:25,expos:22,believ:[9,10],perhap:[26,8],around:[7,19,26,22,24],nelson:23,freeli:[11,14],script:[16,26,17,3,5,22,9,11,28],aggreg:26,upfront:10,figur:[11,12,14,17],refactor:3,develop:[],specif:[],"0x63d0f8":0,problem:[],tide:13,descriptor:[22,28],compil:[],subset:5,capabl:[9,22,26],misinterpret:22,land:26,johnson:23,hhp:22,arch:19,assembl:[25,6],unabl:0,domain:[25,22],xcode:16,"_pyunicode_new":0,contact:[],open:[15,16,1,10,3,26,27,5,20,7,22,24,8,6,11,13,14,28],regist:[25,0,16,11,24],everi:[15,16,26,17,4,0,19,27,20,22,24,25,6,11,28],"_condition__wait":0,lower:[22,0],pstat:[23,18],"0x0c327fff87d0":19,lagerwal:23,unicodedata:18,commit:[],ossaudiodev:18,cover:[],semicolon:22,annot:11,machin:[],feed:20,ob_siz:0,impli:22,fulfil:26,fals:[],spend:20,"0x7f19e0":0,saved_game_model:0,attribut:[25,22,26],balanc:[9,17],view:[15,19,5,22,6,11,12],visual:[6,22,16,5],heap:19,zipfil:[22,18],vindic:22,test_:17,templat:[22,0],line:[],about:[],unexpectedsuccess:0,"void":22,cgitb:18,"0x7e7820":0,altern:[22,23,26],hardi:23,button:[9,22,11,26,3],glossari:22,smtplib:18,last_nam:14,life:14,donald:23,confus:[22,0,8],goodger:23,rodriguez:23,unicodeobject:[0,3],sig:[10,12],buildbottest:5,ptr_to_python_str:0,trick:[11,26],"_rlock__own":0,synchron:[26,5],quopri:18,"2b3":22,ecosystem:7,imghdr:18,github:11,strongli:[27,15,26],visit:25,construct:[],farm:25,aho:25,march:23,redirect:[22,10,20],clr:7,introduc:[],parallel:[1,5,17],concret:22,claus:5,audioop:[19,18],va_list:28,ldl:19,action:[24,28],know:[],emac:[],authorit:22,heim:[23,28,18],opaqu:0,written:[16,10,0,21,7,22,24,28],dict:0,perceiv:3,all:[4,27,8,9,11,10,26,19,21,20,24,6,28,17,5,7,12,14,15,16,0,22,23,25],calendar:18,optim:[25,0,19,23,5],succinct:22,nor:25,assum:[26,17,3,5,7,8,9,6,11],shortcut:[22,11],suitabl:[22,26,17],"switch":[],window:[],"0x984b494":0,conf:22,xml:[18,3],promot:3,frozen:[10,20],arrai:[28,18],abus:22,symtable_visit_xx:25,doubl:0,appeal:[4,10],micro:15,tempfil:18,predecessor:23,pyclass_typ:22,wstrict:19,purpos:[26,22,23,25,9,11],rsa:[11,14],instancemethod:0,took:21,"0x620c00":19,solem:23,domin:22,dump:3,entiti:22,buffer:[2,0,19,22,23,28],push:[],phase:19,upon:[6,10],pdflatex:22,gui:[16,18],test_thread:5,prepar:[],latest:[],confid:22,previous:[11,16],disallow:17,jerdonek:[23,26],cla:26,appli:[],practic:[6,22,16,26,14],mkdir:19,univers:[11,19],minidom:18,"0x7eba00":0,metadata:26,rundown:5,pair:[25,22,5],handl:[],brett:[23,28,18],"0xc9c7f8":0,fcntl:18,chang:[],risk:[22,15],fsanit:19,spark:25,dda1a32748e0:11,possibl:[],sponsor:14,"0x0c327fff8830":19,technic:[25,28,4,20,3],culprit:11,ident:11,autocomplet:3,qunus:16,ensur:[16,26,19,22,9,11],dd12639b82bf:11,revis:[],made:[],mangl:25,"_pyobject_debugmalloc":0,eli:[23,18],"0x7ffff2128500":0,coverage_data:6,"0xd803e0":0,sudo:[19,16],unreleas:26,substanti:22,subtl:[26,24],grp:18,better:[16,3,5,7,22,11],track:[],deserv:[22,15,26,3],compiler_xx:25,scare:22,avoid:[],my_blacklist:19,asdl_c:[25,16],serv:[22,15],build_ext:6,asan_osx_dynam:19,facundo:23,submiss:[9,24],surround:22,far:[21,26],maciej:23,wouldn:26,nptl:0,vulner:22,adjust:[25,16,26],decoratormethod:22,scratch:[11,16,19,8],migrat:3,robust:[5,17],scan:[],cxx:19,impl:22,learn:[],much:[15,17,3,5,7,22,9,11,28],workaround:19,keystrok:22,two:[],keep:[],digest:22,outgo:11,former:[25,11],openid:24,cmd:18,winter:23,url:[16,26,3,22,11,14,28],backtrac:0,lack:[26,3,24,25,9,11,12],occas:[4,19,1],quo:11,pre:[],otherwis:[4,15,16,26,8],suggest:[],eric:[22,23,18],world:[22,0,11],symtabl:[25,21,18],caus:[16,1,26,3,17,19,5,22,8,11],aifc:18,entri:[],facundobatista:18,begin:[4,19,5,7,22,23,25,9],titl:[],locat:[25,22,11,16,5],underlin:22,fail:[],elson:23,amd_athlon:5,"\u0142ukasz":23,pageant:11,signatur:22,lutil:19,subdirectori:[22,8],modul:[],wast:22,column:[22,11],stab:6,ob_digit:0,downsid:5,notic:[16,0,21,24,25,9,11],beyond:[],"0x2b76be018078":19,clearli:[22,24],spuriou:[11,5],right:[15,10,26,19,24,8,25,9,6,11,14],level:[],navig:22,json:18,alter:[25,19],remot:[],postpon:3,integ:[22,0,28],serhii:23,held:25,worth:[10,26,3],ptr_to_char_star:0,transit:18,routin:0,regener:[],app:16,email:[26,10,3,18,20,22,23,9,12,14],minor:[22,15,26],orsenthil:18,addop_o:25,techniqu:25,date:[16,26,18,3,22,24,6,11],immedi:[16,1,26,21,7,22],wasn:22,flatten:25,pertain:22,compon:16,microthread:7,simpler:26,aid:[22,26],hex:3,member:[22,19,14,28],pty:18,overlook:3,antoin:23,"_check_notifi":0,mailman:2,add:[],"_freeze_importlib":19,pickl:18,pimentel:23,"__doc__":0,pete:23,fileinput:18,attr:22,present:[17,4,0,27,5,22,25,9,11,28],hgrc:[11,26],necess:25,engin:[7,22],neal:23,cxxflag:19,regress:[],game:0,refresh:11,preprocessor:22,strateg:25,mywork:[9,26],zlib:[16,18],strongest:15,path:[],accel:19,alex:23,autom:[25,26,28],stalem:11,lingl:23,menuselect:22,wide:[16,10,28],posix:[22,11,19,18],hoxworth:23,multiprocess:[23,10,18],welcom:[7,22,27,24],subentri:22,r45329:23,comput:[6,11,26,3],path_t:28,savedcwd:0,explor:11,test_grammar:21,"0x7e30e0":0,cannon:[23,28,18],entir:[10,26,17,27,19,22,24,25,9,6,12],gustaebel:[23,18],"_stderr_buff":0,asdl_seq:25,profil:[0,19,23,18],coordin:15,py_buildvalu:28,submitt:[26,24,18],thing:[15,16,26,17,4,19,5,7,22,23,24,25,9,14],bnf:22,incomplet:21,form:[16,26,20,7,22,23,24,9,11,14],natur:[22,10],inlin:[],non:[15,26,18,22,25,9],compliment:19,stufft:23,waterfal:5,itself:[],sandbox:[23,5],uniqu:[25,22],hudson:25,lab:[22,28],secondari:[6,22],center:[22,28],cpu:[22,16,17],serwi:[23,18],variou:[16,10,26,3,17,18,4,19,5,20,7,22,23,24,25,9,6,11,12],"0xd7ee60":0,bernardo:23,prevent:[9,11,10,5],make:[],openindiana:18,discret:[15,28],gnome_sudoku:0,truli:[6,4,13],codeop:18,araujo:[23,18],"_stdout_buff":0,apt:16,busi:14,"var":[22,19],anyth:[22,16,24,14],"0xcb5380":0,veiw:19,choic:[10,26],union:[25,19],input:22,receiv:[10,26,4,19,20,24,25,9,11,14],chunk:[25,6,22,18],mirror:[11,20],offset:25,obmalloc:[0,19],concern:[],"default":[15,16,26,17,3,0,5,22,9,11,14],latter:[25,11,20],applic:[22,19,16,26,14],simpli:[26,17,3,5,20,22,9,6,11,12,14],suffici:[9,16],discrep:[9,5],html:[18,3,22,23,25,6,12],ideal:6,access:[],free:[17,18,5,22,8,25,11,13,14,28],summer:23,imp:18,"0x98fad24":0,importlib:18,incompat:[15,26],strip:22,nbyte:0,subitem:22,waiter:0,solut:[16,10,3,7,24,8,9,11],kumaran:23,mainli:[22,11],eval:[25,16],dead:[22,28],http:[16,26,2,3,18,19,5,20,7,22,23,25,6,11,12,14],stai:6,builtin:[22,0,18],model:[],correspond:[15,26,3,0,5,22,25],run:[],global:[0,19,22,25,6,11],pyarena_addpyobject:25,zen:4,"0x948e82c":0,extens:[16,10,26,3,4,0,7,22,24,6,11,14],ghaer:18,charact:[22,28],jump:25,difficult:[4,22,10,1],warrant:[9,3],wild:19,onc:[15,16,10,26,3,4,7,24,25,9,6,11,12,14],longer:[15,10,3,22,23,24,13,14],breed:10,cflag:[19,16],"8ff33af017ef":11,"0x98fa6e4":0,modulenam:22,restrict:[22,15,28],"0x98fab44":0,guido:[4,22,23],remaind:22,issu:[],run_swallowed_dialog:0,happi:26,permiss:[],tty:18,impress:22,testresult:0,ftp:11,edelsohn:18,fraction:18,undon:11,systemat:9,buildpython:19,usual:[15,26,3,23,24,25,11],unittest:[18,3],fork:26,addresssanit:19,ubsan_cxx:19,seilnacht:23,statement:[25,6,22,11],pile:26,"0xd750e0":0,david:[0,23,18],basic:[16,10,26,7,22,25,9],argument:[16,17,3,0,22,25,9,6,11,28],sync:[],consensu:[11,13],interpret:[],terri:[23,18],tar:[22,19],familiar:[7,24],autostart:11,breakag:[26,3],patchcheck:[9,26],decis:[18,3],tabl:[],fundament:22,spent:14,scheme:26,unit:[],assur:22,seutter:23,workload:[10,24],qimport:11,pje:18,common:[],"0x9420b04":0,attest:11,test_notifi:0,"0x858a90":0,envvar:22,recent:[],flovi:23,repli:[20,3],wherea:[27,0],offer:14,chdir:26,gdbinit:[0,11],consist:[10,26,17,22,24,25,14],clock:24,weakref:18,"__name__":[22,0],talk:22,complet:[16,26,17,3,19,20,22,25,6,11,12,14],hidden:25,vari:[0,16,12],critic:[25,16,28,3],pyc:25,"0x7fffefa18710":0,stringprep:18,lee:23,sidebar:24,okai:26,tell:[],expat:18,usag:[],hereaft:0,incom:11,featur:[],changeset:[],unresolv:11,syslog:18,"0x0000000000584abd":0,convent:[22,16,26],regular:[22,0,19,5,3],sectionauthor:22,docutil:22,ebnf:16,week:[28,18],hgaccount:[11,23,14],pgen:[25,21],test_sometest:11,anymor:3,often:[15,26,17,3,5,22,25,9,11],pydict_getitemstr:0,pprint:18,pathlib:18,would:[10,3,4,19,5,20,7,22,25,9,6,11,14],constructor:[25,22],account:[16,4,5,22,24,14,28],dens:26,mistak:22,rietveld:24,onli:[15,16,10,26,3,17,18,4,0,5,20,22,24,25,9,6,11,14,28],wno:[19,16],interfac:[20,22,11,5,17],ronach:23,unconvinc:11,preced:[25,7,22],highlightlang:22,libari:6,ital:22,duplain:23,rough:25,shlex:18,format:[10,26,18,3,19,22,9,11,28],dir:3,aim:[22,15,21],ned:[6,23,18],test_pars:21,ansi:28,"0x4e664c":19,yoshida:23,epub:22,queue:[22,11,26,18],"_sre":3,fresh:8,discuss:[15,10,26,2,4,19,27,20,22,23,24,25,9,11,12,13,14],relev:[9,22,0,16,24],builddep:16,darwin:19,effbot:18,"__builtins__":0,comprehens:[25,7,22],danger:22,particularli:26,"_condit":0,difficulti:13,sphinx:[22,12,26],libcrypto:19,stackless:7,eol:26,regularli:10,brought:3,most:[16,10,26,3,17,4,20,7,22,8,25,9,6,11,12],see:[],retriev:[25,11],new_block:25,wither:23,stand:[22,11],sure:[],functool:18,emit:[25,22,0],resourc:[],nnn:3,wrong:[6,22,21,26,3],further:[15,4,27,22,9,11],lai:22,pybuilddir:19,constraint:26,master:[25,11],"0xd751e0":0,backport:[9,15,23],python331:8,mentor:[27,7,23,24,11,14],guilherm:23,guidelin:[9,11,3],dont_write_bytecod:5,smart:22,colorsi:18,host:[11,15,19,5],syscal:0,shouldn:[11,16],walker:23,lehtinen:[11,23,18],janssen:[23,18],util:[11,16,19,8,3],taken:[4,22,10,24,5],finish:[25,7,12],pyarena_new:25,individu:[28,22,8,17],toc:22,notion:6,box:[22,11,24,3],behavior:[9,22,19,24,3],separ:[],backpatch:25,escal:15,formal:[9,22,26],"0x3dad3a95a0":0,publish:[11,12,15,8,26],amongst:11,awar:[9,7,11,22,3],fact:[25,22,3],ongo:7,motiv:[9,22],updat:[],without:[],map:11,cast:0,give:[16,26,0,22,23,25,6,14],datetim:18,amk:23,tortoiseplink:11,mutual:11,came:[6,26],plug:7,cmdoption:22,senthil:23,rush:23,socket:[11,23,18],rodola:18,test_support:0,primarili:[6,23],grati:16,contrast:22,trivial:[9,26,5,28],slave:5,"0xc191e0":0,rewrit:14,unobtrus:22,pyeval_evalframeex:[25,0],hgtest:14,reanim:22,disappoint:11,manag:[],larger:[11,26],redistribut:26,probabl:[26,17,21,5,7,9,14],pipe:[22,19,18],nch:25,wave:18,grant:[23,26],"0x7e7d20":0,attende:23,libssl:19,offici:[15,16,26,3,4,25,11,14],jinja:22,high:[25,7,0,12,3],unexecut:6,"0x928310":0,colon:[25,22],standard:[],elsewher:16,book:[25,4,11],"__file__":0,backout:11,acquir:0,xmlrpc:18,oliph:23,hello:[22,0],varieti:27,mark:[],peopl:[16,10,26,3,18,4,21,20,22,24,9,12,14],worri:[16,26,22,25,9,6,12],"0xd7fd10":0,type:16,nick:23,novemb:23,propos:[],benefici:4,delet:[],greatli:11,lessen:24,volunt:[27,14],msg:3,kept:[25,22,19,16],execut:[1,17,0,19,22,8,25,6,11],review:[],incorpor:4,bill:23,docstr:[0,26],somehow:3,sp1:16,relat:[],pitrou:[23,18],precaut:17,import_init:19,expr:25,prompt:[22,14],dfsan:19,rst:[25,22,11,26],zipimport:18,bdb:18,pylong_from:28,fill:[9,7,22,28,3],openssh:11,"_resultfordocleanup":0,expand:23,configur:[],amend:22,armin:23,backslash:22,steve:23,ezio:[23,18],"_dummy_thread":18,py_compil:18,condit:[1,17,27,5,8,25],similarli:22,cpythondir:6,abort:[],murrai:[23,18],jnoller:18,vice:[16,26],veri:[15,16,10,26,3,27,5,22,24,25,6,11,14],vawda:[23,18],tupleobject:19,grow:10,archiv:[22,23,20],imaplib:18,nativ:[22,11],call_attr:25,either:[10,26,3,0,5,22,24,8,25,9,11,14,28],eprintf:19,universalsdk:19,suppress:5,"_rlock__block":0,heapq:18,mvl:23,smoothli:26,unknown:[9,19],context:[25,22,0,18],necessarili:[22,11,16,10],typo:12,"_verbose__verbos":0,"_io":3,stmt:25,accur:6,brandl:[15,23,18],"52ec6a3eeda5":11,code_dealloc:19,perfect:5,revers:[22,26],pointer:[25,0,19,28],backtick:26,classifi:[],count:[25,22,0,17,28],pyunicodeucs2_fromstr:0,asdl:[25,21],power:6,certain:[16,18,3,4,19,21,22,6,14],seen:22,visit_seq:25,full:[],dickinson:[23,18],djg:23,maverick:16,file:[],"0x7ffff7fd5ee8":0,larri:[15,23],fix:[],simplifi:[25,24],seemingli:5,random:[18,24,1,5,17],swallow:[0,23],easiest:[22,11,16,26],gather:[6,22,20],tim:[23,18],reachabl:22,evalu:22,best:[],"0x7a2141":19,broader:18,task:[15,16,3,0,7,22,25,11],output:[0,19,5,22,25,6,11],asid:[26,24],period:[22,18],baker:23,jcea:18,prioriti:[],blackbox:6,petri:[11,23,18],which:[],polo:23,me_hash:0,resolut:[],exclud:[6,16,17],comfort:[7,27,13,24],care:[16,26,22,24,25,11,12],arc:23,saniti:[9,16],guarante:[26,17],jim:23,browser:[6,22,24,20],promis:[6,10],regardless:[9,16,13],lock_test:0,moment:[11,3],kwarg:28,accordingli:[25,26],control:[],travi:23,stinner:23,lightli:[4,10,5],libzma:16,nasm:8,shoe:9,norwitz:23,try1_stmt:22,don:[16,26,17,3,27,19,20,22,24,25,9,6,11,12,28],sole:6,rss:20,"0x7fffc8002090":0,weinen:23,correct:[25,12,26,8],barri:18,schedul:[11,12,5],emphasi:22,pleas:[16,10,3,27,22,23,9,6,11,14,28],log:[],osx:19,undefin:19,regexp:22,fno:19,stick:[9,6],peter:[23,18],mercuri:[],stabl:[5,8],cea:23,commerci:28,xvf:19,fetch:11,cygwin:18,subprocess:[5,18],gladli:22,mmap:18,appropri:[15,16,10,26,0,22,24,25,6,11],benjamin:[15,23,18],area:[16,18,3,27,0,24,25,14],alt:11,suppli:[22,0,5],had:[11,24,5,8],"_release_sav":0,rolenam:22,san:19,spell:22,mod:22,top:[16,10,26,0,22,23,24],simultan:[12,17],greater:[25,23],detail:[16,26,17,4,0,19,27,22,23,24,25,9,11,12],jeff:[25,23],vertic:5,gvr:23,new_game_model:0,"0x4ed4b1":19,needn:3,stmt_ty:25,cpython:[],ani:[15,16,10,26,3,17,18,4,0,5,20,22,23,24,8,25,9,6,11,14,28],marker:22,strenuou:[1,5,17],dragon:25,goe:[25,22],hack:[6,21],hunk:11,txt:[22,19,16,5,14],checker:19,improv:[15,26,3,4,19,27,7,22,23,9,6],pyimport_importfrozenmodul:19,idl:[22,23,16,17,3],amd64:[7,16,5,8],"544b654d000c":11,traceback:18,duplic:3,part:[16,10,3,0,19,7,22,9,6,11,12],border:22,lib:[16,17,3,0,19,21,5,22,25,6],do_nasm:8,author:[22,26],xmlreader:18,jenvei:23,recreat:25,compiler_visit_expr:25,"new":[],befit:11,marshal:[25,19,18],coveragedir:6,dash:22,pipermail:23,deadlock:0,pccuild:8,succeed:[11,5],tinker:0,unicod:[18,22,3],distribut:[9,11,16,8,14],question:[],"0xd75060":0,withdrawn:11,ref:22,henceforth:16,fall:[6,10],keychain:11,"0x7fffff7fefe8":0,"0x4ed4b2":19,particular:[],jeffrei:[25,23],tp_base:22,coupl:[6,10],hierarchi:22,advantag:[26,24],them:[16,26,17,3,18,0,19,5,7,22,24,8,25,9,11,14],bz2:18,delin:25,vocal:22,interfer:[9,5,17],makevar:22,never:[26,18,3,4,19,7,22,6,11,28],aix:18,whatsnew:[23,26],trail:22,decid:[10,1,18,4,24,6,12],sprint:23,feb:23,bytecodehack:25,richard:23,doc:[16,26,3,22,23,25,11,12],tag:[],enhanc:[3,4,0,7,22,23],instal:[],faq:[],prettifi:11,launch:16,emx:18,insert:[22,26],"_thread":[0,18],justif:26,concurr:[10,18],tutori:[22,11],goal:[6,10],ordinari:[22,17],kbd:22,known:[],backquot:22,hetting:23,quiver:23,pyunicodeucs2_decodeutf8:0,game_selector:0,among:22,number:[16,26,17,3,18,27,0,19,5,22,23,24,25,6,11,28],"0x2abf9a525eac":19,answer:[27,26,14],profile_osx:19,hold:[9,15,16,3],unsuccess:23,frame:0,debug:[],filenam:11,upstream:26,root:[16,17,0,22,8,11],bbreport:5,rule:[15,16,18,19,5,22,24,25,6],hone:27,fromfil:5,curs:[22,18],collin:23,draft:[11,26],aug:23,dsa:11,histor:[25,8],py_main:19,"0xaace60":0,debat:15,english:22,rebuilt:12,partial:19,sndhdr:18,oudkerk:23,our:[22,26,28],"_testemb":19,mention:[22,27,16,26],"__main__":[22,0,18],red:[22,16],june:23,"0x0c327fff87b0":19,although:[11,12,13,15,28],accord:[9,16],expect:[],somewher:[6,12,26,2],next_block:25,pdf:22,stupid:22,uncommit:11,gud:2,"_build":12,click:[26,3,5,24,8,11],won:[11,16,19,24,3],gmane:20,variat:22,mathemat:[23,18],stefan:23,ctype:[18,0,16,3],per:[],enter:[],www:[25,23,16],termin:[22,0,11,5],strength:[6,19],exist:[],think:[3,5,24,9,12,13,14,28],desktop:17,menu:[22,16,28],abov:[16,26,2,3,17,27,5,7,22,25,6,11,14],media:[22,11],htmlhelp:22,materi:[7,22],overlin:22,pep:[],get_small_int:28,hand:[22,19,26,8],fragment:25,weak:19,tri:[22,0,17],sbt:18,toler:11,replac:[7,11,16,22,17],asdl_seq_new:25,remov:[10,26,18,19,22,23,25,9,6,11,14],easier:[0,22,6,11,14,28],saxutil:18,mid:19,pcbuild:[7,16,8,17],editor:[],test_runpi:6,subtler:5,somewhat:[0,10],cach:[11,28],should:[],advic:15,golden:[23,18],get:[],both:[15,16,26,2,17,19,7,22,23,25,6,11,28],superflu:16,tech:23,werven:23,dealt:[1,17,3],prematur:28,gtk:0,bolz:23,"0x7ffff7fc6340":0,"0x0000000000440d94":0,sethi:25,codec:[18,22,3],str:[25,18,22,0,3],languag:[],obviou:11,point:[15,26,17,27,19,22,25,14],carl:23,avail:[],seamlessli:26,togeth:[22,11],pydoc:[22,18],inspect:[23,5,18],race:11,quirk:6,autoconf:[11,18],manner:22,petursson:23,allow:[],fullcoverag:6,third:[10,26,8,9,6,11,14],korn:25,test_abc:[6,17],prototyp:19,particip:[11,24,18],keyboardinterrupt:0,listen:10,plaintext:22,"0x63fd07":19,ipaddress:[23,18],compiler_mod:25,hare:23,classic:25,septemb:23,functiondef_kind:25,hover:22,tricki:[9,10],"_original_stdout":0,januari:23,ruigrok:23,crypto:8,bookkeep:25,yamamoto:23,robert:23,small:[15,17,4,22,6,12,28],isol:[17,11,5,8],"_previoustestclass":0,yacc:25,cvar:22,crypt:18,"__absolute_start_time__":0,studi:17,tal:23,temporarili:[9,5],"0x0":0,msilib:18,base64:18,runar:23,yourkei:11,algorithm:18,three:[25,22,19,8,18],implicit:[6,19],req:25,main_pag:0,manual:[6,22,11,26,21],suppos:19,outsid:[22,10,5,17],sem_wait:0,difflib:18,stem:5,els:[25,22,11,12,26],yuck:0,boldfac:22,mainten:[],tarek:[23,18],ron:23,xx_ty:25,authorship:23,sort:28,"byte":[25,19,3],fourth:9,leak:[17,28],list:[],alanmcintyr:18,"0x7fffac001c90":0,sudokumak:0,ssl:[22,19,23,8,18],conditiontest:0,moodi:23,step:16,delai:9,unus:[22,19,16],triag:[],lemburg:18,pristin:[26,5],nondist:23,other:[],matt:23,programm:[4,22,2],reproduc:[24,5,3],seem:[9,11,26],cosmet:26,print:[9,6,0,16],stdlib:[],linecach:18,ext:[28,3],compiler_nameop:25,document:[],"0x9aead74":0,below:[15,16,19,20,22,25,6,11],quinlan:23,françoi:23,reli:[6,22,11,5,17],traffic:20,py_va_copi:28,lva:28,vtabl:19,work:[],gzip:18,ob_bas:0,métaireau:23,"0xaacd80":0,wai:[],usernam:[26,14,3],impedi:22,addit:[],"0x7ffff7fb1868":0,let:[8,6,22,5,3],"__package__":0,zadka:23,guidanc:[4,11,24],rest:[16,10,26,27,22,25,6,11],thi:[3,4,27,8,9,11,10,26,19,21,20,24,6,28,17,5,7,12,14,15,16,18,0,22,23,25],offlin:22,command:[16,17,0,5,22,9,6,11],submit:[],cppflag:6,def:22,group:[7,11,22,14],info:0,mostli:[25,20],listinfo:2,stumbl:27,pure:[6,22,16],system:[],readlin:18,summerfield:23,pysymtable_build:25,directori:[],farawai:11,regard:[22,15,20,28],"while":[],binari:[11,26],htmlcov:6,usabl:22,post:[10,26,3,19,20,22,25,9,11],why:[],lar:[23,18],mechan:[22,27,26],casual:11,pyassem:25,finn:23,set:[],melotti:[23,18],interrupt:0,wit:5,tripl:22,correctli:[11,26],bullet:22,test_importlib:6,ldflag:19,utf:[22,23],attent:3,coghlan:23,pyunicodeobject:0,ross:23,compliant:16,psf:[26,23,9,11,14,28],processor:[22,8],shouldstop:0,aren:[11,26],sched:18,pyast_fromnod:25,sphinxext:22,patient:9,test_compileal:5,prohibit:26,show:[],main:[],constantli:[],graft:26,valu:[16,3,0,19,22,24,25,9,28],dictobject:0,kind:[15,16,10,17,5,7,22,25,6,11],escap:22,low:[0,3],whatsnew25:23,request:[],represent:[25,0],explicit:[],friedrich:23,statist:18,quick:[],arguments_ti:25,deem:15,os2:18,progress:26,vet:10,encod:[],take:[],fun:[19,14],puzzl:0,nth:25,kbk:18,page:[26,2,3,22,24,8,9,6,11],atexit:18,matter:15,walk:25,obj:25,malcolm:23,subvers:[22,11,8,3],ma_us:0,watch:[25,14],heavili:26,easi:[],intuit:22,memori:[],pygment:22,blocker:3,recogn:[22,28],focu:[6,7],temp:6,telnetlib:18,unaryneg:22,hynek:[23,18],protocol:[22,23],asynchat:[23,18],mar:[23,5],doctest:[18,3],wsgiref:18,unpredict:5,toctre:22,myfix:5,gnu:[22,19,2],rubric:22,oper:[26,18,3,19,21,5,7,22,24,11],sound:[22,14,17],juli:23,natali:23,"_py_initializeex_priv":19,prepend:[22,26],mosh:23,pytype_genericalloc:22,forget:[9,12,14],manheim:23,defer:[15,3],direct:[],brief:22,start:[],pyunicodeucs2_fromstringands:0,strong:22,"0x620d5c":19,old:[25,15,16,26,24],accompani:6,sysdep:0,"case":[],actual:[15,26,19,22,25,11],addremov:11,troubleshoot:[],technolog:7,samp:22,ps2:22,binhex:18,asterisk:[22,26],versatil:22,kleckner:23,akheron:11,benderski:[23,18],hirokazu:23,emiss:25,april:[22,23],autoreconf:11,octal:22,christian:[23,28,18],while_stmt:25,"64bit":28,via:[22,11,20],digit:3,unhelp:11,invok:[9,19,16],alon:[22,11],noller:23,webbrows:18,punctuat:22,caveat:22,bethard:[23,18],shorthand:[],ing:[23,18],anonym:24,sake:5,lzma:18,vital:5,evolv:7,inform:[],tismer:23,saved_gam:0,empti:[22,11,16],blank:22,prefix:[16,17,19,22,8,11],bock:23,central:[22,11],war:19,less:[22,15,24,5],disclos:28,judgement:[6,18],tree:[],enterpris:16,rhetting:18,state:[16,10,26,3,0,22,23,24,25,9,6,13,14],chanc:[4,11,26,24,14],codeobject:[25,19],x86:11,flip:14,rev:3,method:[22,11,10,19],inaccur:13,repeatedli:11,refer:[],rare:[25,22,15,5,8]},envversion:43,titleterms:{statu:3,troubleshoot:16,continu:5,appli:11,help:[27,12,24],kei:[7,11],miscellan:18,sure:11,proofread:12,cross:22,handl:26,blacklist:19,credit:9,within:26,grammar:[22,21],chang:[4,7,11,26,21],mail:[27,14,20],platform:18,candid:15,histori:23,possibl:11,alia:11,custom:5,load:11,minim:26,licens:[9,26],debug:16,addit:[7,22],interpret:7,intention:28,revis:11,core:[27,11,14],write:[14,17],gcov:6,meta:[22,24],inact:11,stabil:5,branch:[6,11,15,26],when:11,track:24,silenc:1,made:11,fals:28,from:[11,1],earli:6,secur:[22,15],result:[6,5],insid:11,workflow:28,"public":11,edit:11,resourc:7,rational:21,what:[4,11,19,14],out:11,accept:10,cpython:[25,11,21],expect:11,file:[16,27,25,6,11,12],disagre:11,scan:28,faq:11,learn:11,contributor:[26,14],auto:[11,16],channel:11,two:26,keep:11,"import":[25,6],unexpect:17,git:11,per:11,enter:11,know:11,messag:[11,26],remot:11,compar:11,style:[22,26],audienc:22,pass:26,quot:22,pre:[15,10],exist:[10,24],run:[11,17],fail:11,password:11,separ:11,"abstract":[25,21],pep:4,everyon:11,special:3,allow:11,titl:3,who:11,updat:11,without:22,recent:11,editor:16,modul:[6,22,10],skip:17,stage:[15,3],get:[27,16],need:11,head:11,code:[25,6,22,16,26],safe:11,copi:11,report:[11,24,28],structur:16,level:22,singl:26,object:25,entri:26,instead:11,approach:26,languag:[4,11],known:[25,28],alpha:15,design:25,manag:25,upload:[26,28],regener:11,after:23,request:23,section:22,changeset:[11,26],between:[11,26],footnot:22,test:[6,26,1,17],capit:22,compon:3,standard:11,increas:6,admin:23,ask:[27,11],control:[25,11,16],project:23,implement:7,sanit:19,displai:22,alreadi:[11,24],gdb:0,regrtest:6,posit:28,add:11,shorthand:11,type:[10,3],restructuredtext:22,dev:27,propos:[7,10],suggest:11,delet:11,current:11,instal:19,review:[9,26,24],last:11,lcov:6,configur:[11,26],pars:25,relat:25,regress:11,split:11,python:[26,4,19,27,20,7,22,11],submit:9,"new":[25,11,10,26],come:11,role:24,path:11,mainten:15,back:11,than:11,assign:3,hyperlink:22,refer:25,major:26,markup:22,abort:11,limit:28,step:8,initi:23,triag:[24,3],"long":26,repositori:[11,3],avoid:[11,16],requir:10,isn:11,blog:20,same:26,releas:[11,15],stdlib:[10,18],doe:26,unix:[11,16],syntax:25,later:0,llvm:19,failur:5,fix:13,patch:[9,11,26,24],should:11,revert:11,work:[11,26],"null":11,inlin:22,flow:25,clang:[19,16],have:11,beyond:13,loss:23,respons:14,itself:7,tell:11,link:[7,11,22,3],graph:[25,11],classifi:24,sever:11,where:[27,11],primer:22,commun:11,warn:1,index:[22,18],substitut:22,read:14,make:[22,11],system:11,"final":15,develop:[15,26,20,7,23,24,11,12,14],specif:[22,11],full:7,directori:[11,16],problem:11,dynam:19,compil:[25,16],"while":11,comment:[22,3],ast:25,why:11,some:11,follow:20,best:11,document:[22,12],whitespac:22,set:[16,8],contact:[23,28],nosi:3,how:[11,14],prioriti:3,access:28,checklist:[21,26],gotcha:[6,22],drop:23,intent:28,advanc:8,tone:22,resolut:[11,3],machin:11,tracker:[11,12,24,14],readi:26,analysi:[19,28],builder:5,sourc:[22,16],equival:22,bug:[27,11,24],affirm:22,model:28,see:11,express:22,main:15,constantli:11,visual:8,list:[3,27,20,22,11,14],sign:14,differ:26,support:[0,2],agreement:[26,14],setup:[19,16,26],becom:14,explicit:22,mark:11,line:11,about:11,studio:8,quick:7,experi:25,tag:11,bat:22,extern:22,content:[7,22],contribut:[7,11],behaviour:11,encod:22,issu:[3,24,6,11,12,13,14,28],cycl:15,privileg:14,measur:6,log:[11,23],suit:[26,1],summari:15,mercuri:[11,26,3],version:[11,16,26,3],introduct:22,coverag:6,xyz:11,easi:13,memori:25,supersed:3,guid:[7,22,12],merg:[11,26],gener:[9,22,11,16,3],port:26,clone:26,sync:11,build:[22,19,16,5,28],term:26,construct:22,cfg:25,checkout:14,activ:26,want:11,wai:11,keyword:3,paragraph:22,sentenc:22,can:[11,24],expert:18,find:[11,19,24],tabl:[7,22],introduc:[25,11],mentorship:27,direct:22,unit:22,depend:[16,5,3],start:[7,16],common:6,check:[11,24,5],beta:15,intern:22,emac:2,multipl:26,bytecod:25,"case":22,lifecycl:9,local:11,you:24,avail:11,modifi:11,hook:26,order:[26,5],"switch":11,window:[11,16,8],ignor:19,reject:9,field:3,other:[7,11,26,22],ssh:[11,14],show:22,automat:5,integr:5,qualifi:4,"transient":5,creat:[9,11,16],process:[4,10],permiss:23,question:11,concern:22,inform:22,still:26,exampl:22,earlier:0,consider:22,irc:20,particular:11,take:14,which:11,flag:5,undo:11,download:19,tree:25,solv:11,test_gdb:11,gain:[24,14],got:11,commit:[9,11,26,14],product:22,push:[11,26],economi:22,conflict:11,cover:28,prepar:9,latest:11,usag:9,tool:[9,16,18],featur:[11,26]},objtypes:{}}) +\ No newline at end of file +diff -r 85f290e474e2 build/setup.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/setup.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,424 @@ ++ ++ ++ ++ ++ ++ ++ ++ 1. Getting Started — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          1. Getting Started

          ++

          These instructions cover how to get a working copy of the source code and a ++compiled version of the CPython interpreter (CPython is the version of Python ++available from http://www.python.org/). It also gives an overview of the ++directory structure of the CPython source code.

          ++

          OpenHatch also has a great setup guide for Python for people who are ++completely new to contributing to open source.

          ++
          ++

          1.1. Getting Set Up

          ++
          ++

          1.1.1. Version Control Setup

          ++

          CPython is developed using Mercurial. The Mercurial ++command line program is named hg; this is also used to refer to Mercurial ++itself. Mercurial is easily available for common Unix systems by way of the ++standard package manager; under Windows, you might want to use the ++TortoiseHg graphical client.

          ++
          ++
          ++

          1.1.2. Getting the Source Code

          ++

          One should always work from a working copy of the CPython source code. ++While it may ++be tempting to work from the copy of Python you already have installed on your ++machine, it is very likely that you will be working from out-of-date code as ++the Python core developers are constantly updating and fixing things in their ++VCS. It also means you will have better tool ++support through the VCS as it will provide a diff tool, etc.

          ++

          To get a working copy of the in-development branch of ++CPython (core developers use a different URL as outlined in How to Become a Core Developer), ++run:

          ++
          hg clone http://hg.python.org/cpython
++
          ++
          ++

          If you want a working copy of an already-released version of Python, ++i.e., a version in maintenance mode, you can update your ++working copy. For instance, to update your working copy to Python 3.3, do:

          ++
          hg update 3.3
++
          ++
          ++

          You will need to re-compile CPython when you do such an update.

          ++

          Do note that CPython will notice that it is being run from a working copy. ++This means that if you edit CPython’s source code in your working copy, ++changes to Python code will be picked up by the interpreter for immediate ++use and testing. (If you change C code, you will need to recompile the ++affected files as described below.)

          ++

          Patches for the documentation can be made from the same repository; see ++Documenting Python.

          ++
          ++
          ++

          1.1.3. Compiling (for debugging)

          ++

          CPython provides several compilation flags which help with debugging various ++things. While all of the known flags can be found in the ++Misc/SpecialBuilds.txt ++file, the most critical one is the Py_DEBUG flag which creates what is ++known as a “pydebug” build. This flag turns on ++various extra sanity checks which help catch common issues. The use of the flag ++is so common that turning on the flag is a basic compile option.

          ++

          You should always ++develop under a pydebug build of CPython (the only instance of when you ++shouldn’t is if you are taking performance measurements). Even when working ++only on pure Python code the pydebug build provides several useful checks that ++one should not skip.

          ++
          ++

          1.1.3.1. Build dependencies

          ++

          The core CPython interpreter only needs a C compiler to be built; if ++you get compile errors with a C89 or C99-compliant compiler, please open a ++bug report. ++However, some of the extension modules will need development headers ++for additional libraries (such as the zlib library for compression). ++Depending on what you intend to work on, you might need to install these ++additional requirements so that the compiled interpreter supports the ++desired features.

          ++

          For UNIX based systems, we try to use system libraries whenever available. ++This means optional components will only build if the relevant system headers ++are available. The best way to obtain the appropriate headers will vary by ++distribution, but the appropriate commands for some popular distributions ++are below.

          ++

          Fedora, Red Hat Enterprise Linux and other yum based systems:

          ++
          $ sudo yum install yum-utils
++$ sudo yum-builddep python3
++
          ++
          ++

          Debian, Ubuntu and other apt based systems:

          ++
          $ sudo apt-get build-dep python3
++
          ++
          ++

          For Mac OS X systems, it is generally easiest to use the C compiler and other ++development utilities provided by Apple’s Xcode Developer Tools. There are ++specific versions supported by Apple for each major release of OS X. For ++current releases, Xcode is available as a no-cost download from Apple’s App ++Store. Xcode versions for older releases are available through ++the Apple Developer web site. ++Note that while the Xcode IDE application itself is not needed to build Python, ++the development components packaged inside it may be. You should also install ++the Xcode Command Line Tools component to ensure build tools and system header ++files are installed in their conventional locations (/usr/bin and ++/usr/include). How the command line tools are installed varies by OS X ++and Xcode release. In earlier releases, there may be a separate installer ++download. For OS X 10.7 and 10.8, there is an option in the Xcode app ++Preferences menu. For OS X 10.9 (Mavericks), run the following:

          ++
          $ xcode-select --install
++
          ++
          ++

          Also note that OS X does not include several libraries used by the Python ++standard library, including libzma, so expect to see some extension module ++build failures unless you install local copies of them.

          ++

          There will sometimes be optional modules added for a new release which ++won’t yet be identified in the OS level build dependencies. In those cases, ++just ask for assistance on the core-mentorship list. If working on bug ++fixes for Python 2.7, use python in place of python3 in the above ++commands.

          ++

          Explaining how to build optional dependencies on a UNIX based system without ++root access is beyond the scope of this guide.

          ++
          ++

          Note

          ++

          While you need a C compiler to build CPython, you don’t need any ++knowledge of the C language to contribute! Vast areas of CPython are ++written completely in Python: as of this writing, CPython contains slightly ++more Python code than C.

          ++
          ++
          ++
          ++

          1.1.3.2. UNIX

          ++

          The basic steps for building Python for development is to configure it and ++then compile it.

          ++

          Configuration is typically:

          ++
          ./configure --with-pydebug
++
          ++
          ++

          More flags are available to configure, but this is the minimum you should ++do to get a pydebug build of CPython.

          ++

          Once configure is done, you can then compile CPython with:

          ++
          make -s -j2
++
          ++
          ++

          This will build CPython with only warnings and errors being printed to ++stderr and utilize up to 2 CPU cores. If you are using a multi-core machine ++with more than 2 cores (or a single-core machine), you can adjust the number ++passed into the -j flag to match the number of cores you have.

          ++

          Do take note of what modules were not built as stated at the end of your ++build. More than likely you are missing a dependency for the module(s) that ++were not built, and so you can install the dependencies and re-run both ++configure and make (if available for your OS). ++Otherwise the build failed and thus should be fixed (at least with a bug being ++filed on the issue tracker).

          ++

          Once CPython is done building you will then have a working build ++that can be run in-place; ./python on most machines (and what is used in ++all examples), ./python.exe wherever a case-insensitive filesystem is used ++(e.g. on OS X by default), in order to avoid conflicts with the Python ++directory. There is normally no need to install your built copy ++of Python! The interpreter will realize where it is being run from ++and thus use the files found in the working copy. If you are worried ++you might accidentally install your working copy build, you can add ++--prefix=/tmp/python to the configuration step. When running from your ++working directory, it is best to avoid using the --enable-shared flag ++to configure; unless you are very careful, you may accidentally run ++with code from an older, installed shared Python library rather than from ++the interpreter you just built.

          ++
          ++
          1.1.3.2.1. Clang
          ++

          If you are using clang to build CPython, some flags you might want to set to ++quiet some standard warnings which are specifically superfluous to CPython are ++-Wno-unused-value -Wno-empty-body -Qunused-arguments. You can set your ++CFLAGS environment variable to these flags when running configure.

          ++

          If you are using LLVM 2.8, also use the -no-integrated-as flag in order to ++build the ctypes module (without the flag the rest of CPython will ++still build properly).

          ++
          ++
          ++
          ++

          1.1.3.3. Windows

          ++

          The readme included in the solution has more details, especially on the ++software needed to resolve the below mentioned build errors.

          ++

          Python 3.3 and later use Microsoft Visual Studio 2010. You can ++download Microsoft Visual C++ 2010 Express from Microsoft’s site. ++To use it for more than 28 days, one must register through a ++Windows Live account.

          ++

          Most Python versions prior to 3.3 use Microsoft Visual Studio 2008. You can ++download Microsoft Visual C++ 2008 Express Edition with SP1 ++from a new location yet to be determined.

          ++

          Regardless of Visual Studio version, the PCbuild directory of a source ++checkout contains the build files for the Python version you are building. ++The full version of Visual Studio is not necessary for common tasks with ++32-bit builds; the gratis C++ Express versions linked above are sufficient. ++Their limitations are given here (2008) ++and here (2010).

          ++

          To build from the Visual Studio GUI, open the pcbuild.sln solution file ++with Visual Studio. If you are using C++ Express, you may get an error message ++indicating solution files are not supported, you can ignore it. Choose the ++Build Solution option under the Build or ++Debug menu (depending on your version of Visual Studio). ++Be sure that “Debug” was chosen as the active solution configuration ++(e.g. under Build ‣ Configuration Manager...)

          ++

          When building you may see a number of build errors related to missing ++files or directories. These do not necessarily mean that Python failed ++to build. If you prefer, you can exclude the offending projects from ++the build process by unchecking them inside the ++Build ‣ Configuration Manager... settings. You can ++also use the script Tools\buildbot\external.bat or ++Tools\buildbot\external-amd64.bat (as applicable) to download and ++compile missing dependencies.

          ++

          Once built you might want to set Python as a startup project. Pressing F5 in ++Visual Studio, or choosing Start Debugging from the Debug menu, will launch ++the interpreter.

          ++

          If you want to launch the compiled interpreter from the command-line, the ++path varies according to the build. For a 32-bit build in debug mode, you ++have to invoke PCBuild\python_d.exe, for a 64-bit build in debug mode, ++PCBuild\amd64\python_d.exe. If you are compiling in release mode (which ++you shouldn’t, in general), replace python_d.exe with python.exe.

          ++

          For additional help for Windows see Setting Up Windows - Advanced

          ++
          ++
          ++
          ++

          1.1.4. Troubleshooting the build

          ++

          This section lists some of the common problems that may arise during the ++compilation of Python, with proposed solutions.

          ++
          ++

          1.1.4.1. Avoiding re-creating auto-generated files

          ++

          Under some circumstances you may encounter Python errors in scripts like ++Parser/asdl_c.py or Python/makeopcodetargets.py while running make. ++Python auto-generates some of its own code, and a full build from scratch needs ++to run the auto-generation scripts. However, this makes the Python build require ++an already installed Python interpreter; this can also cause version mismatches ++when trying to build an old (2.x) Python with a new (3.x) Python installed, or ++vice versa.

          ++

          To overcome this problem, auto-generated files are also checked into the ++Mercurial repository. So if you don’t touch the auto-generation scripts, there’s ++no real need to auto-generate anything. However, as Mercurial doesn’t preserve ++timestamps well, a special build target touch was added. Run:

          ++
          make touch
++
          ++
          ++

          Before running the compilation make. This will tweak the timestamps of the ++auto-generated files in a way that makes it unnecessary to create them anew and ++henceforth the compilation should not require an installed Python interpreter.

          ++
          ++
          ++
          ++
          ++

          1.2. Editors and Tools

          ++

          Python is used widely enough that practically all code editors have some form ++of support for writing Python code. Various coding tools also include Python ++support.

          ++

          For editors and tools which the core developers have felt some special comment ++is needed for coding in Python, see Additional Resources.

          ++
          ++
          ++

          1.3. Directory Structure

          ++

          There are several top-level directories in the CPython source tree. Knowing what ++each one is meant to hold will help you find where a certain piece of ++functionality is implemented. Do realize, though, there are always exceptions to ++every rule.

          ++
          ++
          Doc
          ++
          The official documentation. This is what http://docs.python.org/ uses. ++See also Building the documentation.
          ++
          Grammar
          ++
          Contains the EBNF grammar file for ++Python.
          ++
          Include
          ++
          Contains all interpreter-wide header files.
          ++
          Lib
          ++
          The part of the standard library implemented in pure Python.
          ++
          Mac
          ++
          Mac-specific code (e.g., using IDLE as an OS X application).
          ++
          Misc
          ++
          Things that do not belong elsewhere. Typically this is varying kinds of ++developer-specific documentation.
          ++
          Modules
          ++
          The part of the standard library (plus some other code) that is implemented ++in C.
          ++
          Objects
          ++
          Code for all built-in types.
          ++
          PC
          ++
          Windows-specific code along with legacy build files for previously used ++versions of MSVC.
          ++
          PCbuild
          ++
          Build files for the version of MSVC currently used for the Windows ++installers provided on python.org.
          ++
          Parser
          ++
          Code related to the parser. The definition of the AST nodes is also kept ++here.
          ++
          Python
          ++
          The code that makes up the CPython interpreter. This includes the compiler, ++eval loop and various built-in modules.
          ++
          Tools
          ++
          Various tools that are (or have been) used to maintain Python.
          ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          Python Developer’s Guide

          ++

          Next topic

          ++

          2. Where to Get Help

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/setupWindows.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/setupWindows.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,224 @@ ++ ++ ++ ++ ++ ++ ++ ++ 2. Setting Up Windows - Advanced — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          2. Setting Up Windows - Advanced

          ++

          The online directions for downloading the development version source are fine ++and can be found at Windows. There is also ++information in the readme file found in the source directory that is helpful.

          ++

          Mercurial must be installed on your machine. ++Stable released version source is available on the download page.

          ++

          Subversion is necessary because some of the third party components for the ++windows built are still in a subversion repository.

          ++

          Python building/rebuilding assumes the existence of subversion, perl, and a ++version of Visual Studio on your system. If you have all three, skip to step ++three. Otherwise download and install any of those that are missing.

          ++

          If it is necessary to have on hand multiple versions of python built from scratch, you ++should isolate them from each other by putting them in a container directory ++perhaps of the same name:

          ++
          python331/python331, python32/python32
++
          ++
          ++

          where the subdirectory is the source root directory. Use the upper directory ++to isolate the external subprojects created by the buildbots described later. ++The buildbots of one version can wipe out required subprojects of another ++version of python which can cause confusion.

          ++
          ++

          2.1. Step 0

          ++

          Download and install a subversion client and add the executable to your path.

          ++
          ++
          ++

          2.2. Step 1

          ++

          Download and install perl and add the executable to your path.

          ++
          ++
          ++

          2.3. Step 2

          ++

          Download and install Visual Studio 2010. Either Express C++ will work or ++Visual Studio Professional. Express is free, however, when the solution file ++is loaded, an error message is displayed.

          ++

          Visual Studio should be in your path.

          ++
          ++
          ++

          2.4. Step 3

          ++

          Download and install NASM

          ++
          ++
          ++

          2.5. Step 4

          ++

          Download and build the external subprojects with the buildbots using either:

          ++
          Tools\buildbot\external.bat         # for 32 bit processors
++Tools\buildbot\external-amd64.bat   # for 64 bit processors
++
          ++
          ++

          from the root directory or your python distribution. ++This step will download the correct versions of the external projects for ++this version of python. There are several projects

          ++
          ++
          ++

          2.6. Step 5

          ++

          openssl is used for python on windows ++ssl rarely succeeds if you proceed to build using pcbuild.sln:

          ++

          The following steps will resolve many problems if you executing them ++before building with the .sln file:

          ++
          cd into the openssl directory created by the buildbots
++perl util\mkdef.pl crypto ssl update
++perl Configure VC-WIN32 --prefix=C:\opt\openssl-1.0.1d
++ms\do_nasm
++
          ++
          ++

          Compilation errors may occur when you attempt to build the .sln file with ++Visual Studio. The errors are typically a forced error contained within a ++block of conditional code. Good results have been found by commenting out ++the forced error. Most recently commenting out code blocks in ++mdc2.h and idea.h produced good results.

          ++

          Historically, the openssl build has not had a “clean” function. Cleaning the ++project by deleting and letting the buildbot download again gave good results.

          ++
          ++
          ++

          2.7. Step 6

          ++

          Finally Build python and its internal subprojects

          ++
          ++

          Open the solution “pcbuild.sln” in Visual Studio ++If you have an express version, then ignore the warning ++Select the configuration (Release or Debug)

          ++
          "Release" builds python.exe
++"Debug" builds python_d.exe
++Select the platform   Win32 or x64
++Build the solution.
++Right click "Solution 'pccuild'"  and select
++   build - for fresh build
++   clean - to delete all files created for build , i.e. objects,
++   libraries, executable, etc.
++   rebuild - clean and build everything
++
          ++
          ++
          ++

          Note that you can clean and build individual subprojects by right clicking ++on the subproject and selecting build, clean, or rebuild for that project

          ++
          ++

          2.7.1. Using Visual Studio

          ++

          There is Python Tools for Visual Studio an addon published ++by Microsoft for many versions of Visual Studio except the Express editions.

          ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          1. Getting Started

          ++

          Next topic

          ++

          3. Where to Get Help

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/silencewarnings.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/silencewarnings.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,120 @@ ++ ++ ++ ++ ++ ++ ++ ++ 9. Silence Warnings From the Test Suite — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          9. Silence Warnings From the Test Suite

          ++

          When running Python’s test suite, no warnings should result when you run it ++under strenuous testing conditions (you can ignore ++the extra flags passed to test that cause randomness and parallel execution ++if you want). Unfortunately new warnings are added to Python on occasion which ++take some time to eliminate (e.g., ResourceWarning). Typically the easy ++warnings are dealt with quickly, but the more difficult ones that require some ++thought and work do not get fixed immediately.

          ++

          If you decide to tackle a warning you have found, open an issue on the issue ++tracker (if one has not already been opened) and say you are going to try and ++tackle the issue, and then proceed to fix the issue.

          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Previous topic

          ++

          8. Documenting Python

          ++

          Next topic

          ++

          10. Fixing “easy” Issues (and Beyond)

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/stdlibchanges.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/stdlibchanges.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,244 @@ ++ ++ ++ ++ ++ ++ ++ ++ 20. Adding to the Stdlib — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          20. Adding to the Stdlib

          ++

          While the stdlib contains a great amount of useful code, sometimes you want ++more than is provided. This document is meant to explain how you can get either ++a new addition to a pre-existing module in the stdlib or add an entirely new ++module.

          ++

          Changes to pre-existing code is not covered as that is considered a bugfix and ++thus is treated as a bug that should be filed on the issue tracker.

          ++
          ++

          20.1. Adding to a pre-existing module

          ++

          If you have found that a function, method, or class is useful and you believe ++it would be useful to the general Python community, there are some steps to go ++through in order to see it added to the stdlib.

          ++

          First is you should gauge the usefulness of the code. Typically this is done ++by sharing the code publicly. You have a couple of options for this. One is to ++post it online at the Python Cookbook. Based on feedback or reviews of the ++recipe you can see if others find the functionality as useful as you do. ++A search of the issue tracker for previous suggestions related to the proposed ++addition may turn up a rejected issue that explains why the suggestion will not ++be accepted. ++Another is to do a blog post about the code and see what kind of responses you ++receive. Posting to python-list (see Following Python’s Development for where to find the ++list and other mailing lists) to discuss your code also works. Finally, asking ++on a specific SIG from mail.python.org or ++python-ideas is also acceptable. This is not a required step but it is ++suggested.

          ++

          If you have found general acceptance and usefulness for your code from people, ++you can open an issue on the issue tracker with the code attached as a ++patch. If possible, also submit a ++contributor agreement.

          ++

          If a core developer decides that your code would be useful to the general ++Python community, they will then commit your code. If your code is not picked ++up by a core developer and committed then please do not take this personally. ++Through your public sharing of your code in order to gauge community support ++for it you at least can know that others will come across it who may find it ++useful.

          ++
          ++
          ++

          20.2. Adding a new module

          ++

          It must be stated upfront that getting a new module into the stdlib is very ++difficult. Adding any significant amount of code to the stdlib increases the ++burden placed upon core developers. It also means that the module somewhat ++becomes “sanctioned” by the core developers as a good way to do something, ++typically leading to the rest of the Python community to using the new module ++over other available solutions. All of this means that additions to the stdlib ++are not taken lightly.

          ++
          ++

          20.2.1. Acceptable Types of Modules

          ++

          Typically two types of modules get added to the stdlib. One type is a module ++which implements something that is difficult to get right. A good example of ++this is the multiprocessing package. Working out the various OS ++issues, working through concurrency issues, etc. are all very difficult to get ++right.

          ++

          The second type of module is one that implements something that people ++re-implement constantly. The itertools module is a good example of ++this type as its constituent parts are not necessarily complex, but are used ++regularly in a wide range of programs and can be a little tricky to get right. ++Modules that parse widely used data formats also fall under this type of module ++that the stdlib consists of.

          ++

          While a new stdlib module does not need to appeal to all users of Python, it ++should be something that a large portion of the community will find useful. ++This makes sure that the developer burden placed upon core developers is worth ++it.

          ++
          ++
          ++

          20.2.2. Requirements

          ++

          In order for a module to even be considered for inclusion into the stdlib, a ++couple of requirements must be met.

          ++

          The most basic is that the code must meet ++standard patch requirements. For code that has ++been developed outside the stdlib typically this means making sure the coding ++style guides are followed and that the proper tests have been written.

          ++

          The module needs to have been out in the community for at least a year. Because ++of Python’s conservative nature when it comes to backwards-compatibility, when ++a module is added to the stdlib its API becomes frozen. This means that a module ++should only enter the stdlib when it is mature and gone through its ++“growing pains”.

          ++

          The module needs to be considered best-of-breed. When something is included in ++the stdlib it tends to be chosen first for products over other third-party ++solutions. By virtue of having been available to the public for at least a ++year, a module needs to have established itself as (one of) the top choices by ++the community for solving the problem the module is intended for.

          ++

          The development of the module must move into Python’s ++infrastructure (i.e., the module is no longer directly maintained outside of ++Python). This prevents a divergence between the code that is included in the ++stdlib and that which is released outside the stdlib (typically done to provide ++the module to older versions of Python). It also removes the burden of forcing ++core developers to have to redirect bug reports or patches to an external issue ++tracker and VCS.

          ++

          Someone involved with the development of the ++module must promise to help maintain the module in the stdlib for two years. ++This not only helps out other core developers by alleviating workload from bug ++reports that arrive from the first Python release containing the module, but ++also helps to make sure that the overall design of the module continues to be ++uniform.

          ++
          ++
          ++

          20.2.3. Proposal Process

          ++

          If the module you want to propose adding to the stdlib meets the proper ++requirements, you may propose its inclusion. To start, you should email ++python-list or python-ideas to make sure the community in general would support ++the inclusion of the module (see Following Python’s Development).

          ++

          If the feedback from the community is positive overall, you will need to write ++a PEP for the module’s inclusion. It ++should outline what the module’s overall goal is, why it should be included in ++the stdlib, and specify the API of the module. See the PEP index for PEPs ++that have been accepted before that proposed a module for inclusion.

          ++

          Once your PEP is written, send it to python-ideas for basic vetting. Be ++prepared for extensive feedback and lots of discussion (not all of it ++positive). This will help make the PEP be of good quality and properly ++formatted.

          ++

          When you have listened to, responded, and integrated as appropriate the ++feedback from python-ideas into your PEP, you may send it to python-dev. You ++will once again receive a large amount of feedback and discussion. A PEP ++dictator will be assigned who makes the final call on whether the PEP will be ++accepted or not. If the PEP dictator agrees to accept your PEP (which typically ++means that the core developers end up agreeing in general to accepting ++your PEP) then the module ++will be added to the stdlib once the creators of the module sign ++contributor agreements.

          ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          19. Continuous Integration

          ++

          Next topic

          ++

          21. Changing the Python Language

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/tracker.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/tracker.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,286 @@ ++ ++ ++ ++ ++ ++ ++ ++ 11. Issue Tracking — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          11. Issue Tracking

          ++
          ++

          11.1. Using the Issue Tracker

          ++

          If you think you found a bug in Python, you can report it to the ++issue tracker. Documentation bugs can also be reported there. ++Issues about the tracker should be reported to the meta tracker.

          ++
          ++

          11.1.1. Checking if a bug already exists

          ++

          The first step in filing a report is to determine whether the problem has ++already been reported. The advantage in doing so, aside from saving the ++developers time, is that you learn what has been done to fix it; it may be that ++the problem has already been fixed for the next release, or additional ++information is needed (in which case you are welcome to provide it if you can!).

          ++

          To do this, search the bug database using the search box on the top of the page. ++An advanced search is also available by clicking on “Search” in ++the sidebar.

          ++
          ++
          ++

          11.1.2. Reporting an issue

          ++

          If the problem you’re reporting is not already in the issue tracker, you ++need to log in by entering your user and password in the form on the left. ++If you don’t already have a tracker account, select the “Register” link or, ++if you use OpenID, one of the OpenID provider logos in the sidebar.

          ++

          It is not possible to submit a bug report anonymously.

          ++

          Being now logged in, you can submit a bug by clicking on the “Create New” link ++in the sidebar.

          ++

          The submission form has a number of fields, and they are described in detail ++in the Triaging an Issue page. This is a short summary:

          ++
            ++
          • in the Title field, enter a very short description of the problem; ++less than ten words is good;
            • ++
          • in the Type field, select the type of your problem (usually behavior);
            • ++
          • if you know which Components and Versions are affected by the issue, ++you can select these too;
            • ++
          • if you have JavaScript enabled, you can use the Nosy List field to search ++developers that can help with the issue by entering the name of the affected ++module, operating system, or interest area.
            • ++
          • last but not least, you have to describe the problem in detail, including ++what you expected to happen and what did happen, in the Comment field. ++Be sure to include whether any extension modules were involved, and what ++hardware and software platform you were using (including version information ++as appropriate).
            • ++
          ++

          The triaging team will take care of setting other fields, and possibly assign ++the issue to a specific developer. You will automatically receive an update ++each time an action is taken on the bug.

          ++
          ++
          ++
          ++

          11.2. Helping Triage Issues

          ++

          Once you know your way around how Python’s source files are ++structured and you are comfortable working with patches, a great way to ++participate is to help triage issues. Do realize, though, that experience ++working on Python is needed in order to effectively help triage.

          ++

          Around the clock, new issues are being opened on the issue tracker and ++existing issues are being updated. Every ++issue needs to be triaged to make sure various things are in proper order. Even ++without special privileges you can help with this process.

          ++
          ++

          11.2.1. Classifying Reports

          ++

          For bugs, an issue needs to:

          ++
            ++
          • clearly explain the bug so it can be reproduced
            • ++
          • include all relevant platform details
            • ++
          • state what version(s) of Python are affected by the bug.
            • ++
          ++

          These are things you can help with once you have experience developing for ++Python. For instance, if a bug is not clearly explained enough for you to ++reproduce it then there is a good chance a core developer won’t be able to ++either. And it is always helpful to know if a bug not only affects the ++in-development version of Python, but whether it also affects other versions in ++maintenance mode. And if the bug lacks a unit test that should end up in ++Python’s test suite, having that written can be very helpful.

          ++

          This is all helpful as it allows triagers (i.e., ++people with the Developer role on the issue tracker) to ++properly classify an issue so it can be handled by the right core developers in ++a timely fashion.

          ++
          ++
          ++

          11.2.2. Reviewing Patches

          ++

          If an issue has a patch attached that has not been reviewed, you can help by ++making sure the patch:

          ++
            ++
          • follows the style guides
            • ++
          • applies cleanly to an up-to-date clone
            • ++
          • is a good solution to the problem it is trying to solve
            • ++
          • includes proper tests
            • ++
          • includes proper documentation changes
            • ++
          • submitter is listed in Misc/ACKS, either already or the patch adds them
            • ++
          ++

          Doing all of this allows core developers and triagers to more ++quickly look for subtle issues that only people with extensive experience ++working on Python’s code base will notice.

          ++
          ++
          ++

          11.2.3. Finding an Issue You Can Help With

          ++

          If you want to help triaging issues, you might also want to search for issues ++that you are knowledgeable about. An easy way to do it, is to search for ++the name of a module you are familiar with. You can also use the ++advanced search and search for specific components (e.g. “Windows” if you ++are a Windows developer, “Extension Modules” if you are familiar with C, etc.). ++Finally you can use the “Random issue” link in the sidebar to pick random ++issues until you find an issue that you like. Is not so uncommon to find old ++issues that can be closed, either because they are no longer valid, or ++because they have a patch that is ready to be committed, but no one had ++time to do it yet.

          ++

          In the sidebar you can also find links to summaries for easy issues and ++issues with a patch.

          ++
          ++
          ++
          ++

          11.3. Gaining the “Developer” Role on the Issue Tracker

          ++

          When you have consistently shown the ability to properly ++help triage issues without guidance, you may request that you ++be given the “Developer” role on the issue tracker. You can make the request ++of any person who already has the Developer role. If they decide you are ready ++to gain the extra privileges on the tracker they will then act as a mentor to ++you until you are ready to do things entirely on your own. There is no set rule ++as to how many issues you need to have helped with before or how long you have ++been participating. The key requirements are that you show the desire to ++help, you are able to work well with others (especially those already with the ++Developer role), and that have a firm grasp of how to do things on the issue ++tracker properly on your own.

          ++

          Gaining the Developer role will allow you to set any value on any issue in the ++tracker, releasing you from the burden of having to ask others to set values on ++an issue for you in order to properly triage something. This will not only help ++speed up and simplify your work in helping out, but also help lessen the ++workload for everyone by gaining your help.

          ++
          ++
          ++

          11.4. The Meta Tracker

          ++

          If you find an issue with the issue tracker, you can report it to the ++meta tracker. The meta tracker is where you file issues against anything ++you come across when working with the issue tracker itself (e.g you can’t ++attach a file, the layout is broken on your browser, Rietveld gave you an ++error, etc.).

          ++

          If you want to contribute to the tracker you can get a checkout of the source ++and install a local instance where to experiment. You can find detailed ++instructions on the Tracker Development page.

          ++
          ++

          See also

          ++
          ++
          The Python issue tracker
          ++
          Where to report issues about Python.
          ++
          The New-bugs-announce mailing list
          ++
          Where all the new issues created on the tracker are reported.
          ++
          The Python-bugs-list mailing list
          ++
          Where all the changes to issues are reported.
          ++
          The meta tracker
          ++
          Where to report issues about the tracker itself.
          ++
          The Tracker development wiki page
          ++
          Instructions about setting up a local instance of the bug tracker.
          ++
          The Tracker-discuss mailing list
          ++
          Discussions about the bug tracker.
          ++
          ++
          ++
          ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          10. Fixing “easy” Issues (and Beyond)

          ++

          Next topic

          ++

          12. Triaging an Issue

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 build/triaging.html +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/build/triaging.html Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,427 @@ ++ ++ ++ ++ ++ ++ ++ ++ 12. Triaging an Issue — Python Developer's Guide ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++ ++
          ++

          Navigation

          ++ ++
          ++ ++
          ++
          ++
          ++
          ++ ++
          ++

          12. Triaging an Issue

          ++

          When you have the Developer role on the issue tracker you are able to triage ++issues directly without any assistance.

          ++
          ++

          12.1. Fields

          ++
          ++

          12.1.1. Title

          ++

          Should be properly descriptive of what the issue is about. Occasionally ++people file an issue that either has too generic of a title or end up thinking ++they filed about X but in fact it turns out to be about Y and thus the ++title is now wrong.

          ++
          ++
          ++

          12.1.2. Type

          ++

          Describes the type of issue. If something does not fit within any ++specific type then simply do not set it.

          ++
          ++
          behavior
          ++
          Wrong or unexpected behavior, result, or exception. This includes most of ++the bugs.
          ++
          crash
          ++
          Hard crashes of the Python interpreter – possibly with a core ++dump or a Windows error box.
          ++
          compile error
          ++
          Errors reported by the compiler while compiling Python.
          ++
          resource usage
          ++
          Situations where too many resources (e.g. memory) are used.
          ++
          security
          ++
          Issues that might have security implications. If you think the issue ++should not be made public, please report it to security@python.org instead.
          ++
          performance
          ++
          Situations where too much time is necessary to complete the task.
          ++
          enhancement
          ++
          Issues that propose the addition of new functionality, such as new ++functions, classes, modules, or even new arguments for existing functions. ++Also used for improvements in the documentation and test suite and for ++other refactorings.
          ++
          ++
          ++
          ++

          12.1.3. Stage

          ++

          What is needed next to advance the issue. The stage needn’t be set until ++it is clear that the issue warrants fixing.

          ++
          ++
          test needed
          ++
          The bug reporter should post a script or instructions to let a triager or ++developer reproduce the issue.
          ++
          needs patch
          ++
          The issue lacks a patch to solve the problem (i.e. fixing the bug, or ++adding the requested improvement).
          ++
          patch review
          ++
          There is a patch, but it needs reviewing or is in the process of being ++reviewed. This can be done by any triager as well as a core developer.
          ++
          commit review
          ++
          A triager performed a patch review and it looks good to them, but a core ++developer needs to commit the patch (and do a quick once-over to make sure ++nothing was overlooked).
          ++
          committed/rejected
          ++
          The issue is considered closed and dealt with.
          ++
          ++
          ++
          ++

          12.1.4. Components

          ++

          What part of Python is affected by the issue. This is a multi-select field. ++Be aware that what component is chosen may cause the issue to be auto-assigned, ++i.e. the issue tracker may automatically fill in the Assigned To field ++after you press Submit changes.

          ++

          The following component(s) should be selected if the issue applies to:

          ++
          ++
          2to3 (2.x to 3.0 conversion tool)
          ++
          The 2to3 conversion tool in Lib/lib2to3.
          ++
          Benchmarks
          ++
          The benchmarks in the benchmarks repo.
          ++
          Build
          ++
          The build process.
          ++
          ctypes
          ++
          The ctypes package in Lib/ctypes.
          ++
          Demos and Tools
          ++
          The files in Tools and Tools/demo.
          ++
          Devguide
          ++
          The Developer’s guide.
          ++
          Distutils
          ++
          The distutils package in Lib/distutils.
          ++
          Distutils2
          ++
          The packaging module in Lib/packaging.
          ++
          Documentation
          ++
          The documentation in Doc (used to build the HTML doc at http://docs.python.org/).
          ++
          email
          ++
          The email package and related modules.
          ++
          Extension Modules
          ++
          C modules in Modules.
          ++
          IDLE
          ++
          The Lib/idlelib package.
          ++
          Installation
          ++
          The installation process.
          ++
          Interpreter Core
          ++
          The interpreter core, the built-in objects in Objects, the Python, ++Grammar and Parser dirs.
          ++
          IO
          ++
          The I/O system, Lib/io.py and Modules/_io.
          ++
          Library (Lib)
          ++
          Python modules in Lib.
          ++
          Macintosh
          ++
          The Mac OS X operating system.
          ++
          Regular Expressions
          ++
          The Lib/re.py and Modules/_sre.c modules.
          ++
          Tests
          ++

          The unittest and doctest frameworks in Lib/unittest and ++Lib/doctest.py.

          ++

          The CPython tests in Lib/test, the test runner in Lib/test/regrtest.py ++and the Lib/test/support.py module.

          ++
          ++
          Tkinter
          ++
          The Lib/tkinter package.
          ++
          Unicode
          ++
          Unicode, codecs, str vs bytes, Objects/unicodeobject.c.
          ++
          Windows
          ++
          The Windows operating system.
          ++
          XML
          ++
          The Lib/xml package.
          ++
          ++
          ++
          ++

          12.1.5. Versions

          ++

          The known versions of Python that the issue affects and should be fixed for. ++Thus if an issue for a new feature is assigned for e.g., Python 3.3 but is not ++applied before Python 3.3.0 is released, this field should be updated to say ++Python 3.4 as the version and drop Python 3.3.

          ++
          ++
          ++

          12.1.6. Priority

          ++

          How important is this issue?

          ++
          ++
          low
          ++
          This is for low-impact bugs, or feature requests of little utility.
          ++
          normal
          ++
          The default value for most issues, which deserve fixing but without ++any urgency to do so.
          ++
          high
          ++
          Make some effort to fix the issue before the next final release.
          ++
          critical
          ++
          This issue should definitely be fixed before the next final release.
          ++
          deferred blocker
          ++
          The issue will not hold up the next release, but will be promoted to a ++release blocker for the following release, e.g., won’t block the next ++release of a1 but will block a2.
          ++
          release blocker
          ++
          The issue must be fixed before any release is made, e.g., will block the ++next release even if it is an alpha release.
          ++
          ++

          As a guideline, critical and above are usually reserved for crashes, ++serious regressions or breakage of very important APIs. Whether a bug ++is a release blocker is a decision better left to the release manager so, ++in any doubt, add him or her to the nosy list.

          ++
          ++
          ++

          12.1.7. Keywords

          ++

          Various flags about the issue. Multiple values are possible.

          ++
          ++
          buildbot
          ++
          A buildbot triggered the issue being reported.
          ++
          easy
          ++
          Fixing the issue should not take longer than a day for someone new to ++contributing to Python to solve.
          ++
          gsoc
          ++
          The issue would fit as, or is related to, a GSoC project.
          ++
          needs review
          ++
          The patch attached to the issue is in need of a review.
          ++
          patch
          ++
          There is a patch attached to the issue.
          ++
          3.3regression
          ++
          The issue is a regression in 3.3.
          ++
          ++
          ++
          ++

          12.1.8. Nosy List

          ++

          A list of people who may be interested in an issue. It is acceptable to add ++someone to the nosy list if you think the issue should be brought to their ++attention. Use the Experts Index to know who wants to be added to the nosy ++list for issues targeting specific areas.

          ++

          If you are logged in and have JavaScript enabled, you can use the [+] ++button to add yourself to the nosy list (remember to click on ++“Submit Changes” afterwards). Note that you are added to the nosy ++automatically when you submit a message. ++The nosy list also has an autocomplete that lets you search from the lists of ++developers and Experts Index. The search is case-insensitive and ++works for real names, modules, interest areas, etc., and only adds the ++username(s) to the nosy once an entry is selected.

          ++
          ++
          ++

          12.1.9. Assigned To

          ++

          Who is expected to take the next step in resolving the issue. It is acceptable ++to assign an issue to someone if the issue cannot move forward without their ++help, e.g., they need to make a technical decision to allow the issue to move ++forward. Also consult the Experts Index as certain stdlib modules should ++always be assigned to a specific person.

          ++
          ++
          ++

          12.1.10. Dependencies

          ++

          The issue requires the listed issue(s) to be resolved first before it can move ++forward.

          ++
          ++
          ++

          12.1.11. Superseder

          ++

          The issue is a duplicate of the listed issue(s).

          ++
          ++
          ++

          12.1.12. Status

          ++
          ++
          open
          ++
          Issue is not resolved.
          ++
          languishing
          ++
          The issue has no clear solution , e.g., no agreement on a technical ++solution or if it is even a problem worth fixing.
          ++
          pending
          ++
          The issue is blocked until someone (often the ++OP) provides some critical information; ++the issue will be closed after a set amount of time if no reply comes in. ++Useful when someone opens an issue that lacks enough information to ++reproduce the bug reported. Requesting additional information and setting ++status to pending indicates that the issue should be closed if the ++necessary information is never provided.
          ++
          closed
          ++
          The issue has been resolved (somehow).
          ++
          ++
          ++
          ++

          12.1.13. Resolution

          ++

          Why the issue is in its current state (not usually used for “open”).

          ++
          ++
          duplicate
          ++
          Duplicate of another issue; should have the Superseder field filled out.
          ++
          fixed
          ++
          A fix for the issue was committed.
          ++
          invalid
          ++
          For some reason the issue is invalid (e.g. the perceived problem is not ++a bug in Python).
          ++
          later
          ++
          Issue is to be worked on at a later date.
          ++
          out of date
          ++
          The issue has already been fixed, or the problem doesn’t exist anymore ++for other reasons.
          ++
          postponed
          ++
          Issue will not be worked on at the moment.
          ++
          rejected
          ++
          Issue was rejected (especially for feature requests).
          ++
          remind
          ++
          The issue is acting as a reminder for someone.
          ++
          wont fix
          ++
          Issue will not be fixed, typically because it would cause a ++backwards-compatibility problem.
          ++
          works for me
          ++
          Bug cannot be reproduced.
          ++
          ++
          ++
          ++

          12.1.14. Mercurial Repository

          ++

          HTTP link to a Mercurial repository that contains a patch for the issue. ++A Create Patch button will appear that computes a diff for the ++head revision of the remote branch and attaches it to the issue. The button ++supports only CPython patches.

          ++

          If you don’t indicate a remote branch, default is used. You can ++indicate a remote branch by adding #BRANCH to the end of the URL.

          ++
          ++
          ++ ++
          ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Table Of Contents

          ++ ++ ++

          Previous topic

          ++

          11. Issue Tracking

          ++

          Next topic

          ++

          13. Following Python’s Development

          ++

          This Page

          ++ ++ ++ ++
          ++
          ++
          ++
          ++
          ++

          Navigation

          ++ ++
          ++
          ++ © Copyright 2011-2012, Python Software Foundation. ++ Created using Sphinx 1.2.2. ++
          ++ ++ +\ No newline at end of file +diff -r 85f290e474e2 index.rst +--- a/index.rst Mon Mar 17 21:35:56 2014 -0500 ++++ b/index.rst Wed Mar 19 13:46:42 2014 -0500 +@@ -187,6 +187,7 @@ + :numbered: + + setup ++ setupwindows + help + patch + runtests +diff -r 85f290e474e2 setup.rst +--- a/setup.rst Mon Mar 17 21:35:56 2014 -0500 ++++ b/setup.rst Wed Mar 19 13:46:42 2014 -0500 +@@ -49,9 +49,9 @@ + + If you want a working copy of an already-released version of Python, + i.e., a version in :ref:`maintenance mode `, you can update your +-working copy. For instance, to update your working copy to Python 3.4, do:: ++working copy. For instance, to update your working copy to Python 3.3, do:: + +- hg update 3.4 ++ hg update 3.3 + + You will need to re-compile CPython when you do such an update. + +@@ -216,7 +216,6 @@ + + Windows + ''''''' +- + The readme included in the solution has more details, especially on the + software needed to resolve the below mentioned build errors. + +@@ -240,11 +239,12 @@ + `_. + + To build from the Visual Studio GUI, open the ``pcbuild.sln`` solution file +-with Visual Studio. Choose the :menuselection:`Build Solution` option +-under the :menuselection:`Build` or :menuselection:`Debug` menu +-(depending on your version of Visual Studio). Be sure that "Debug" was +-chosen as the active solution configuration (e.g. under +-:menuselection:`Build --> Configuration Manager...`). ++with Visual Studio. If you are using C++ Express, you may get an error message ++indicating solution files are not supported, you can ignore it. Choose the ++:menuselection:`Build Solution` option under the :menuselection:`Build` or ++:menuselection:`Debug` menu (depending on your version of Visual Studio). ++Be sure that "Debug" was chosen as the active solution configuration ++(e.g. under :menuselection:`Build --> Configuration Manager...`) + + When building you may see a number of build errors related to missing + files or directories. These do not necessarily mean that Python failed +@@ -267,6 +267,8 @@ + ``PCBuild\amd64\python_d.exe``. If you are compiling in release mode (which + you shouldn't, in general), replace ``python_d.exe`` with ``python.exe``. + ++For additional help for Windows see :ref:`windows-advanced` ++ + .. _build_troubleshooting: + + Troubleshooting the build +diff -r 85f290e474e2 setupwindows.rst +--- /dev/null Thu Jan 01 00:00:00 1970 +0000 ++++ b/setupwindows.rst Wed Mar 19 13:46:42 2014 -0500 +@@ -0,0 +1,126 @@ ++.. _windows-advanced: ++ ++============================= ++Setting Up Windows - Advanced ++============================= ++ ++The online directions for downloading the development version source are fine ++and can be found at :ref:`Windows `. There is also ++information in the readme file found in the source directory that is helpful. ++ ++Mercurial must be installed on your machine. ++Stable released version source is available on the download page. ++ ++Subversion is necessary because some of the third party components for the ++windows built are still in a subversion repository. ++ ++Python building/rebuilding assumes the existence of subversion, perl, and a ++version of Visual Studio on your system. If you have all three, skip to step ++three. Otherwise download and install any of those that are missing. ++ ++If it is necessary to have on hand multiple versions of python built from scratch, you ++should isolate them from each other by putting them in a container directory ++perhaps of the same name:: ++ ++ python331/python331, python32/python32 ++ ++where the subdirectory is the source root directory. Use the upper directory ++to isolate the external subprojects created by the buildbots described later. ++The buildbots of one version can wipe out required subprojects of another ++version of python which can cause confusion. ++ ++------ ++Step 0 ++------ ++ ++Download and install a subversion client and add the executable to your path. ++ ++------ ++Step 1 ++------ ++ ++Download and install perl and add the executable to your path. ++ ++------ ++Step 2 ++------ ++ ++Download and install Visual Studio 2010. Either Express C++ will work or ++Visual Studio Professional. Express is free, however, when the solution file ++is loaded, an error message is displayed. ++ ++Visual Studio should be in your path. ++ ++------ ++Step 3 ++------ ++ ++Download and install `NASM `_ ++ ++------ ++Step 4 ++------ ++ ++Download and build the external subprojects with the buildbots using either:: ++ ++ Tools\buildbot\external.bat # for 32 bit processors ++ Tools\buildbot\external-amd64.bat # for 64 bit processors ++ ++from the root directory or your python distribution. ++This step will download the correct versions of the external projects for ++this version of python. There are several projects ++ ++------ ++Step 5 ++------ ++ ++ ++openssl is used for python on windows ++ssl rarely succeeds if you proceed to build using pcbuild.sln: ++ ++The following steps will resolve many problems if you executing them ++before building with the .sln file:: ++ ++ cd into the openssl directory created by the buildbots ++ perl util\mkdef.pl crypto ssl update ++ perl Configure VC-WIN32 --prefix=C:\opt\openssl-1.0.1d ++ ms\do_nasm ++ ++Compilation errors may occur when you attempt to build the .sln fil \ No newline at end of file