how 2 write some code do automatic garbage collection?

Effective harnesses for long-running agents

Effective harnesses for long-running agents

【信息科学与工程学】【安全领域】第八十三篇 云安全解决方案02

企业中“搞人”与“搞事情”常见问题的分析框架。我将选取4个典型场景，每个场景都从实际管理现象出发，逐步推导出数学模型、参数设定及关联知识。

操作系统(内存管理)

文将对 Linux™ 程序员可以使用的内存管理技术进行概述，虽然关注的重点是 C 语言，但同样也适用于其他语言。文中将为您提供如何管理内存的细节，然后将进一步展示如何手工管理内存，如何使用引用计数或者内存池来半手工地管理内存，以及如何使用垃圾收集自动管理内存。 为什么必须管理内存 内存管理是计算机编程最为基本的领域之一。在很多脚本语言中，您不必担心内存是如何管理的，这并不能使得内存管理的重要性有一点点降低。对实际编程来说，理解您的内存管理器的能力与局限性至关重要。在大部分系统语言中，比如 C 和 C++，您必须进行内存管理。本文将介绍手工的、半手工的以及自动的内存管理实践的基本概念。 追溯到在 Apple II 上进行汇编语言编程的时代，那时内存管理还不是个大问题。您实际上在运行整个系统。系统有多少内存，您就有多少内存。您甚至不必费心思去弄明白它有多少内存，因为每一台机器的内存数量都相同。所以，如果内存需要非常固定，那么您只需要选择一个内存范围并使用它即可。 不过，即使是在这样一个简单的计算机中，您也会有问题，尤其是当您不知道程序的每个部分将需要多少内存时。如果您的空间有限，而内存需求是变化的，那么您需要一些方法来满足这些需求： 确定您是否有足够的内存来处理数据。 从可用的内存中获取一部分内存。 向可用内存池（pool）中返回部分内存，以使其可以由程序的其他部分或者其他程序使用。 实现这些需求的程序库称为 分配程序（allocators），因为它们负责分配和回收内存。程序的动态性越强，内存管理就越重要，您的内存分配程序的选择也就更重要。让我们来了解可用于内存管理的不同方法，它们的好处与不足，以及它们最适用的情形。 回页首 C 风格的内存分配程序 C 编程语言提供了两个函数来满足我们的三个需求： malloc：该函数分配给定的字节数，并返回一个指向它们的指针。如果没有足够的可用内存，那么它返回一个空指针。 free：该函数获得指向由 malloc 分配的内存片段的指针，并将其释放，以便以后的程序或操作系统使用（实际上，一些 malloc 实现只能将内存归还给程序，而无法将内存归还给操作系统）。 物理内存和虚拟内存 要理解内存在程序中是如何分配的，首先需要理解如何将内存从操作系统分配给程序。计算机上的每一个进程都认为自己可以访问所有的物理内存。显然，由于同时在运行多个程序，所以每个进程不可能拥有全部内存。实际上，这些进程使用的是 虚拟内存。 只是作为一个例子，让我们假定您的程序正在访问地址为 629 的内存。不过，虚拟内存系统不需要将其存储在位置为 629 的 RAM 中。实际上，它甚至可以不在 RAM 中 —— 如果物理 RAM 已经满了，它甚至可能已经被转移到硬盘上！由于这类地址不必反映内存所在的物理位置，所以它们被称为虚拟内存。操作系统维持着一个虚拟地址到物理地址的转换的表，以便计算机硬件可以正确地响应地址请求。并且，如果地址在硬盘上而不是在 RAM 中，那么操作系统将暂时停止您的进程，将其他内存转存到硬盘中，从硬盘上加载被请求的内存，然后再重新启动您的进程。这样，每个进程都获得了自己可以使用的地址空间，可以访问比您物理上安装的内存更多的内存。 在 32-位 x86 系统上，每一个进程可以访问 4 GB 内存。现在，大部分人的系统上并没有 4 GB 内存，即使您将 swap 也算上， 每个进程所使用的内存也肯定少于 4 GB。因此，当加载一个进程时，它会得到一个取决于某个称为 系统中断点（system break）的特定地址的初始内存分配。该地址之后是未被映射的内存 —— 用于在 RAM 或者硬盘中没有分配相应物理位置的内存。因此，如果一个进程运行超出了它初始分配的内存，那么它必须请求操作系统“映射进来（map in）”更多的内存。（映射是一个表示一一对应关系的数学术语 —— 当内存的虚拟地址有一个对应的物理地址来存储内存内容时，该内存将被映射。） 基于 UNIX 的系统有两个可映射到附加内存中的基本系统调用： brk： brk() 是一个非常简单的系统调用。还记得系统中断点吗？该位置是进程映射的内存边界。 brk() 只是简单地将这个位置向前或者向后移动，就可以向进程添加内存或者从进程取走内存。 mmap： mmap()，或者说是“内存映像”，类似于 brk()，但是更为灵活。首先，它可以映射任何位置的内存，而不单单只局限于进程。其次，它不仅可以将虚拟地址映射到物理的 RAM 或者 swap，它还可以将它们映射到文件和文件位置，这样，读写内存将对文件中的数据进行读写。不过，在这里，我们只关心 mmap 向进程添加被映射的内存的能力。 munmap() 所做的事情与 mmap() 相反。 如您所见， brk() 或者 mmap() 都可以用来向我们的进程添加额外的虚拟内存。在我们的例子中将使用 brk()，因为它更简单，更通用。 实现一个简单的分配程序 如果您曾经编写过很多 C 程序，那么您可能曾多次使用过 malloc() 和 free()。不过，您可能没有用一些时间去思考它们在您的操作系统中是如何实现的。本节将向您展示 malloc 和 free 的一个最简化实现的代码，来帮助说明管理内存时都涉及到了哪些事情。 要试着运行这些示例，需要先 复制本代码清单，并将其粘贴到一个名为 malloc.c 的文件中。接下来，我将一次一个部分地对该清单进行解释。 在大部分操作系统中，内存分配由以下两个简单的函数来处理： void *malloc(long numbytes)：该函数负责分配 numbytes 大小的内存，并返回指向第一个字节的指针。 void free(void *firstbyte)：如果给定一个由先前的 malloc 返回的指针，那么该函数会将分配的空间归还给进程的“空闲空间”。 malloc_init 将是初始化内存分配程序的函数。它要完成以下三件事：将分配程序标识为已经初始化，找到系统中最后一个有效内存地址，然后建立起指向我们管理的内存的指针。这三个变量都是全局变量： 清单 1. 我们的简单分配程序的全局变量 int has_initialized = 0; void *managed_memory_start; void *last_valid_address; 如前所述，被映射的内存的边界（最后一个有效地址）常被称为系统中断点或者 当前中断点。在很多 UNIX® 系统中，为了指出当前系统中断点，必须使用 sbrk(0) 函数。 sbrk 根据参数中给出的字节数移动当前系统中断点，然后返回新的系统中断点。使用参数 0 只是返回当前中断点。这里是我们的 malloc 初始化代码，它将找到当前中断点并初始化我们的变量： 清单 2. 分配程序初始化函数 /* Include the sbrk function */ #include void malloc_init() { /* grab the last valid address from the OS */ last_valid_address = sbrk(0); /* we don't have any memory to manage yet, so *just set the beginning to be last_valid_address */ managed_memory_start = last_valid_address; /* Okay, we're initialized and ready to go */ has_initialized = 1; } 现在，为了完全地管理内存，我们需要能够追踪要分配和回收哪些内存。在对内存块进行了 free 调用之后，我们需要做的是诸如将它们标记为未被使用的等事情，并且，在调用 malloc 时，我们要能够定位未被使用的内存块。因此， malloc 返回的每块内存的起始处首先要有这个结构： 清单 3. 内存控制块结构定义 struct mem_control_block { int is_available; int size; }; 现在，您可能会认为当程序调用 malloc 时这会引发问题 —— 它们如何知道这个结构？答案是它们不必知道；在返回指针之前，我们会将其移动到这个结构之后，把它隐藏起来。这使得返回的指针指向没有用于任何其他用途的内存。那样，从调用程序的角度来看，它们所得到的全部是空闲的、开放的内存。然后，当通过 free() 将该指针传递回来时，我们只需要倒退几个内存字节就可以再次找到这个结构。 在讨论分配内存之前，我们将先讨论释放，因为它更简单。为了释放内存，我们必须要做的惟一一件事情就是，获得我们给出的指针，回退 sizeof(struct mem_control_block) 个字节，并将其标记为可用的。这里是对应的代码： 清单 4. 解除分配函数 void free(void *firstbyte) { struct mem_control_block *mcb; /* Backup from the given pointer to find the * mem_control_block */ mcb = firstbyte - sizeof(struct mem_control_block); /* Mark the block as being available */ mcb->is_available = 1; /* That's It! We're done. */ return; } 如您所见，在这个分配程序中，内存的释放使用了一个非常简单的机制，在固定时间内完成内存释放。分配内存稍微困难一些。以下是该算法的略述： 清单 5. 主分配程序的伪代码 1. If our allocator has not been initialized, initialize it. 2. Add sizeof(struct mem_control_block) to the size requested. 3. start at managed_memory_start. 4. Are we at last_valid address? 5. If we are: A. We didn't find any existing space that was large enough -- ask the operating system for more and return that. 6. Otherwise: A. Is the current space available (check is_available from the mem_control_block)? B. If it is: i) Is it large enough (check "size" from the mem_control_block)? ii) If so: a. Mark it as unavailable b. Move past mem_control_block and return the pointer iii) Otherwise: a. Move forward "size" bytes b. Go back go step 4 C. Otherwise: i) Move forward "size" bytes ii) Go back to step 4 我们主要使用连接的指针遍历内存来寻找开放的内存块。这里是代码： 清单 6. 主分配程序 void *malloc(long numbytes) { /* Holds where we are looking in memory */ void *current_location; /* This is the same as current_location, but cast to a * memory_control_block */ struct mem_control_block *current_location_mcb; /* This is the memory location we will return. It will * be set to 0 until we find something suitable */ void *memory_location; /* Initialize if we haven't already done so */ if(! has_initialized) { malloc_init(); } /* The memory we search for has to include the memory * control block, but the users of malloc don't need * to know this, so we'll just add it in for them. */ numbytes = numbytes + sizeof(struct mem_control_block); /* Set memory_location to 0 until we find a suitable * location */ memory_location = 0; /* Begin searching at the start of managed memory */ current_location = managed_memory_start; /* Keep going until we have searched all allocated space */ while(current_location != last_valid_address) { /* current_location and current_location_mcb point * to the same address. However, current_location_mcb * is of the correct type, so we can use it as a struct. * current_location is a void pointer so we can use it * to calculate addresses. */ current_location_mcb = (struct mem_control_block *)current_location; if(current_location_mcb->is_available) { if(current_location_mcb->size >= numbytes) { /* Woohoo! We've found an open, * appropriately-size location. */ /* It is no longer available */ current_location_mcb->is_available = 0; /* We own it */ memory_location = current_location; /* Leave the loop */ break; } } /* If we made it here, it's because the Current memory * block not suitable; move to the next one */ current_location = current_location + current_location_mcb->size; } /* If we still don't have a valid location, we'll * have to ask the operating system for more memory */ if(! memory_location) { /* Move the program break numbytes further */ sbrk(numbytes); /* The new memory will be where the last valid * address left off */ memory_location = last_valid_address; /* We'll move the last valid address forward * numbytes */ last_valid_address = last_valid_address + numbytes; /* We need to initialize the mem_control_block */ current_location_mcb = memory_location; current_location_mcb->is_available = 0; current_location_mcb->size = numbytes; } /* Now, no matter what (well, except for error conditions), * memory_location has the address of the memory, including * the mem_control_block */ /* Move the pointer past the mem_control_block */ memory_location = memory_location + sizeof(struct mem_control_block); /* Return the pointer */ return memory_location; } 这就是我们的内存管理器。现在，我们只需要构建它，并在程序中使用它即可。 运行下面的命令来构建 malloc 兼容的分配程序（实际上，我们忽略了 realloc() 等一些函数，不过， malloc() 和 free() 才是最主要的函数）： 清单 7. 编译分配程序 gcc -shared -fpic malloc.c -o malloc.so 该程序将生成一个名为 malloc.so 的文件，它是一个包含有我们的代码的共享库。 在 UNIX 系统中，现在您可以用您的分配程序来取代系统的 malloc()，做法如下： 清单 8. 替换您的标准的 malloc LD_PRELOAD=/path/to/malloc.so export LD_PRELOAD LD_PRELOAD 环境变量使动态链接器在加载任何可执行程序之前，先加载给定的共享库的符号。它还为特定库中的符号赋予优先权。因此，从现在起，该会话中的任何应用程序都将使用我们的 malloc()，而不是只有系统的应用程序能够使用。有一些应用程序不使用 malloc()，不过它们是例外。其他使用 realloc() 等其他内存管理函数的应用程序，或者错误地假定 malloc() 内部行为的那些应用程序，很可能会崩溃。ash shell 似乎可以使用我们的新 malloc() 很好地工作。 如果您想确保 malloc() 正在被使用，那么您应该通过向函数的入口点添加 write() 调用来进行测试。 我们的内存管理器在很多方面都还存在欠缺，但它可以有效地展示内存管理需要做什么事情。它的某些缺点包括： 由于它对系统中断点（一个全局变量）进行操作，所以它不能与其他分配程序或者 mmap 一起使用。 当分配内存时，在最坏的情形下，它将不得不遍历 全部进程内存；其中可能包括位于硬盘上的很多内存，这意味着操作系统将不得不花时间去向硬盘移入数据和从硬盘中移出数据。 没有很好的内存不足处理方案（ malloc 只假定内存分配是成功的）。 它没有实现很多其他的内存函数，比如 realloc()。 由于 sbrk() 可能会交回比我们请求的更多的内存，所以在堆（heap）的末端会遗漏一些内存。 虽然 is_available 标记只包含一位信息，但它要使用完整的 4-字节 的字。 分配程序不是线程安全的。 分配程序不能将空闲空间拼合为更大的内存块。 分配程序的过于简单的匹配算法会导致产生很多潜在的内存碎片。 我确信还有很多其他问题。这就是为什么它只是一个例子! 其他 malloc 实现 malloc() 的实现有很多，这些实现各有优点与缺点。在设计一个分配程序时，要面临许多需要折衷的选择，其中包括： 分配的速度。 回收的速度。 有线程的环境的行为。 内存将要被用光时的行为。 局部缓存。 簿记（Bookkeeping）内存开销。 虚拟内存环境中的行为。 小的或者大的对象。 实时保证。 每一个实现都有其自身的优缺点集合。在我们的简单的分配程序中，分配非常慢，而回收非常快。另外，由于它在使用虚拟内存系统方面较差，所以它最适于处理大的对象。 还有其他许多分配程序可以使用。其中包括： Doug Lea Malloc：Doug Lea Malloc 实际上是完整的一组分配程序，其中包括 Doug Lea 的原始分配程序，GNU libc 分配程序和 ptmalloc。 Doug Lea 的分配程序有着与我们的版本非常类似的基本结构，但是它加入了索引，这使得搜索速度更快，并且可以将多个没有被使用的块组合为一个大的块。它还支持缓存，以便更快地再次使用最近释放的内存。 ptmalloc 是 Doug Lea Malloc 的一个扩展版本，支持多线程。在本文后面的 参考资料部分中，有一篇描述 Doug Lea 的 Malloc 实现的文章。 BSD Malloc：BSD Malloc 是随 4.2 BSD 发行的实现，包含在 FreeBSD 之中，这个分配程序可以从预先确实大小的对象构成的池中分配对象。它有一些用于对象大小的 size 类，这些对象的大小为 2 的若干次幂减去某一常数。所以，如果您请求给定大小的一个对象，它就简单地分配一个与之匹配的 size 类。这样就提供了一个快速的实现，但是可能会浪费内存。在 参考资料部分中，有一篇描述该实现的文章。 Hoard：编写 Hoard 的目标是使内存分配在多线程环境中进行得非常快。因此，它的构造以锁的使用为中心，从而使所有进程不必等待分配内存。它可以显著地加快那些进行很多分配和回收的多线程进程的速度。在 参考资料部分中，有一篇描述该实现的文章。 众多可用的分配程序中最有名的就是上述这些分配程序。如果您的程序有特别的分配需求，那么您可能更愿意编写一个定制的能匹配您的程序内存分配方式的分配程序。不过，如果不熟悉分配程序的设计，那么定制分配程序通常会带来比它们解决的问题更多的问题。要获得关于该主题的适当的介绍，请参阅 Donald Knuth 撰写的 The Art of Computer Programming Volume 1: Fundamental Algorithms 中的第 2.5 节“Dynamic Storage Allocation”（请参阅 参考资料中的链接）。它有点过时，因为它没有考虑虚拟内存环境，不过大部分算法都是基于前面给出的函数。 在 C++ 中，通过重载 operator new()，您可以以每个类或者每个模板为单位实现自己的分配程序。在 Andrei Alexandrescu 撰写的 Modern C++ Design 的第 4 章（“Small Object Allocation”）中，描述了一个小对象分配程序（请参阅 参考资料中的链接）。 基于 malloc() 的内存管理的缺点 不只是我们的内存管理器有缺点，基于 malloc() 的内存管理器仍然也有很多缺点，不管您使用的是哪个分配程序。对于那些需要保持长期存储的程序使用 malloc() 来管理内存可能会非常令人失望。如果您有大量的不固定的内存引用，经常难以知道它们何时被释放。生存期局限于当前函数的内存非常容易管理，但是对于生存期超出该范围的内存来说，管理内存则困难得多。而且，关于内存管理是由进行调用的程序还是由被调用的函数来负责这一问题，很多 API 都不是很明确。 因为管理内存的问题，很多程序倾向于使用它们自己的内存管理规则。C++ 的异常处理使得这项任务更成问题。有时好像致力于管理内存分配和清理的代码比实际完成计算任务的代码还要多！因此，我们将研究内存管理的其他选择。 回页首 半自动内存管理策略 引用计数 引用计数是一种 半自动（semi-automated）的内存管理技术，这表示它需要一些编程支持，但是它不需要您确切知道某一对象何时不再被使用。引用计数机制为您完成内存管理任务。 在引用计数中，所有共享的数据结构都有一个域来包含当前活动“引用”结构的次数。当向一个程序传递一个指向某个数据结构指针时，该程序会将引用计数增加 1。实质上，您是在告诉数据结构，它正在被存储在多少个位置上。然后，当您的进程完成对它的使用后，该程序就会将引用计数减少 1。结束这个动作之后，它还会检查计数是否已经减到零。如果是，那么它将释放内存。 这样做的好处是，您不必追踪程序中某个给定的数据结构可能会遵循的每一条路径。每次对其局部的引用，都将导致计数的适当增加或减少。这样可以防止在使用数据结构时释放该结构。不过，当您使用某个采用引用计数的数据结构时，您必须记得运行引用计数函数。另外，内置函数和第三方的库不会知道或者可以使用您的引用计数机制。引用计数也难以处理发生循环引用的数据结构。 要实现引用计数，您只需要两个函数 —— 一个增加引用计数，一个减少引用计数并当计数减少到零时释放内存。 一个示例引用计数函数集可能看起来如下所示： 清单 9. 基本的引用计数函数 /* Structure Definitions*/ /* Base structure that holds a refcount */ struct refcountedstruct { int refcount; } /* All refcounted structures must mirror struct * refcountedstruct for their first variables */ /* Refcount maintenance functions */ /* Increase reference count */ void REF(void *data) { struct refcountedstruct *rstruct; rstruct = (struct refcountedstruct *) data; rstruct->refcount++; } /* Decrease reference count */ void UNREF(void *data) { struct refcountedstruct *rstruct; rstruct = (struct refcountedstruct *) data; rstruct->refcount--; /* Free the structure if there are no more users */ if(rstruct->refcount == 0) { free(rstruct); } } REF 和 UNREF 可能会更复杂，这取决于您想要做的事情。例如，您可能想要为多线程程序增加锁，那么您可能想扩展 refcountedstruct，使它同样包含一个指向某个在释放内存之前要调用的函数的指针（类似于面向对象语言中的析构函数 —— 如果您的结构中包含这些指针，那么这是 必需的）。 当使用 REF 和 UNREF 时，您需要遵守这些指针的分配规则： UNREF 分配前左端指针（left-hand-side pointer）指向的值。 REF 分配后左端指针（left-hand-side pointer）指向的值。 在传递使用引用计数的结构的函数中，函数需要遵循以下这些规则： 在函数的起始处 REF 每一个指针。 在函数的结束处 UNREF 第一个指针。 以下是一个使用引用计数的生动的代码示例： 清单 10. 使用引用计数的示例 /* EXAMPLES OF USAGE */ /* Data type to be refcounted */ struct mydata { int refcount; /* same as refcountedstruct */ int datafield1; /* Fields specific to this struct */ int datafield2; /* other declarations would go here as appropriate */ }; /* Use the functions in code */ void dosomething(struct mydata *data) { REF(data); /* Process data */ /* when we are through */ UNREF(data); } struct mydata *globalvar1; /* Note that in this one, we don't decrease the * refcount since we are maintaining the reference * past the end of the function call through the * global variable */ void storesomething(struct mydata *data) { REF(data); /* passed as a parameter */ globalvar1 = data; REF(data); /* ref because of Assignment */ UNREF(data); /* Function finished */ } 由于引用计数是如此简单，大部分程序员都自已去实现它，而不是使用库。不过，它们依赖于 malloc 和 free 等低层的分配程序来实际地分配和释放它们的内存。 在 Perl 等高级语言中，进行内存管理时使用引用计数非常广泛。在这些语言中，引用计数由语言自动地处理，所以您根本不必担心它，除非要编写扩展模块。由于所有内容都必须进行引用计数，所以这会对速度产生一些影响，但它极大地提高了编程的安全性和方便性。以下是引用计数的益处： 实现简单。 易于使用。 由于引用是数据结构的一部分，所以它有一个好的缓存位置。 不过，它也有其不足之处： 要求您永远不要忘记调用引用计数函数。 无法释放作为循环数据结构的一部分的结构。 减缓几乎每一个指针的分配。 尽管所使用的对象采用了引用计数，但是当使用异常处理（比如 try 或 setjmp()/ longjmp()）时，您必须采取其他方法。 需要额外的内存来处理引用。 引用计数占用了结构中的第一个位置，在大部分机器中最快可以访问到的就是这个位置。 在多线程环境中更慢也更难以使用。 C++ 可以通过使用 智能指针（smart pointers）来容忍程序员所犯的一些错误，智能指针可以为您处理引用计数等指针处理细节。不过，如果不得不使用任何先前的不能处理智能指针的代码（比如对 C 库的联接），实际上，使用它们的后果通实比不使用它们更为困难和复杂。因此，它通常只是有益于纯 C++ 项目。如果您想使用智能指针，那么您实在应该去阅读 Alexandrescu 撰写的 Modern C++ Design 一书中的“Smart Pointers”那一章。 内存池 内存池是另一种半自动内存管理方法。内存池帮助某些程序进行自动内存管理，这些程序会经历一些特定的阶段，而且每个阶段中都有分配给进程的特定阶段的内存。例如，很多网络服务器进程都会分配很多针对每个连接的内存 —— 内存的最大生存期限为当前连接的存在期。Apache 使用了池式内存（pooled memory），将其连接拆分为各个阶段，每个阶段都有自己的内存池。在结束每个阶段时，会一次释放所有内存。 在池式内存管理中，每次内存分配都会指定内存池，从中分配内存。每个内存池都有不同的生存期限。在 Apache 中，有一个持续时间为服务器存在期的内存池，还有一个持续时间为连接的存在期的内存池，以及一个持续时间为请求的存在期的池，另外还有其他一些内存池。因此，如果我的一系列函数不会生成比连接持续时间更长的数据，那么我就可以完全从连接池中分配内存，并知道在连接结束时，这些内存会被自动释放。另外，有一些实现允许注册 清除函数（cleanup functions），在清除内存池之前，恰好可以调用它，来完成在内存被清理前需要完成的其他所有任务（类似于面向对象中的析构函数）。 要在自己的程序中使用池，您既可以使用 GNU libc 的 obstack 实现，也可以使用 Apache 的 Apache Portable Runtime。GNU obstack 的好处在于，基于 GNU 的 Linux 发行版本中默认会包括它们。Apache Portable Runtime 的好处在于它有很多其他工具，可以处理编写多平台服务器软件所有方面的事情。要深入了解 GNU obstack 和 Apache 的池式内存实现，请参阅 参考资料部分中指向这些实现的文档的链接。 下面的假想代码列表展示了如何使用 obstack： 清单 11. obstack 的示例代码 #include #include /* Example code listing for using obstacks */ /* Used for obstack macros (xmalloc is a malloc function that exits if memory is exhausted */ #define obstack_chunk_alloc xmalloc #define obstack_chunk_free free /* Pools */ /* Only permanent allocations should go in this pool */ struct obstack *global_pool; /* This pool is for per-connection data */ struct obstack *connection_pool; /* This pool is for per-request data */ struct obstack *request_pool; void allocation_failed() { exit(1); } int main() { /* Initialize Pools */ global_pool = (struct obstack *) xmalloc (sizeof (struct obstack)); obstack_init(global_pool); connection_pool = (struct obstack *) xmalloc (sizeof (struct obstack)); obstack_init(connection_pool); request_pool = (struct obstack *) xmalloc (sizeof (struct obstack)); obstack_init(request_pool); /* Set the error handling function */ obstack_alloc_failed_handler = &allocation_failed; /* Server main loop */ while(1) { wait_for_connection(); /* We are in a connection */ while(more_requests_available()) { /* Handle request */ handle_request(); /* Free all of the memory allocated * in the request pool */ obstack_free(request_pool, NULL); } /* We're finished with the connection, time * to free that pool */ obstack_free(connection_pool, NULL); } } int handle_request() { /* Be sure that all object allocations are allocated * from the request pool */ int bytes_i_need = 400; void *data1 = obstack_alloc(request_pool, bytes_i_need); /* Do stuff to process the request */ /* return */ return 0; } 基本上，在操作的每一个主要阶段结束之后，这个阶段的 obstack 会被释放。不过，要注意的是，如果一个过程需要分配持续时间比当前阶段更长的内存，那么它也可以使用更长期限的 obstack，比如连接或者全局内存。传递给 obstack_free() 的 NULL 指出它应该释放 obstack 的全部内容。可以用其他的值，但是它们通常不怎么实用。 使用池式内存分配的益处如下所示： 应用程序可以简单地管理内存。 内存分配和回收更快，因为每次都是在一个池中完成的。分配可以在 O(1) 时间内完成，释放内存池所需时间也差不多（实际上是 O(n) 时间，不过在大部分情况下会除以一个大的因数，使其变成 O(1)）。 可以预先分配错误处理池（Error-handling pools），以便程序在常规内存被耗尽时仍可以恢复。 有非常易于使用的标准实现。 池式内存的缺点是： 内存池只适用于操作可以分阶段的程序。 内存池通常不能与第三方库很好地合作。 如果程序的结构发生变化，则不得不修改内存池，这可能会导致内存管理系统的重新设计。 您必须记住需要从哪个池进行分配。另外，如果在这里出错，就很难捕获该内存池。 回页首 垃圾收集 垃圾收集（Garbage collection）是全自动地检测并移除不再使用的数据对象。垃圾收集器通常会在当可用内存减少到少于一个具体的阈值时运行。通常，它们以程序所知的可用的一组“基本”数据 —— 栈数据、全局变量、寄存器 —— 作为出发点。然后它们尝试去追踪通过这些数据连接到每一块数据。收集器找到的都是有用的数据；它没有找到的就是垃圾，可以被销毁并重新使用这些无用的数据。为了有效地管理内存，很多类型的垃圾收集器都需要知道数据结构内部指针的规划，所以，为了正确运行垃圾收集器，它们必须是语言本身的一部分。 收集器的类型 复制（copying）： 这些收集器将内存存储器分为两部分，只允许数据驻留在其中一部分上。它们定时地从“基本”的元素开始将数据从一部分复制到另一部分。内存新近被占用的部分现在成为活动的，另一部分上的所有内容都认为是垃圾。另外，当进行这项复制操作时，所有指针都必须被更新为指向每个内存条目的新位置。因此，为使用这种垃圾收集方法，垃圾收集器必须与编程语言集成在一起。 标记并清理（Mark and sweep）：每一块数据都被加上一个标签。不定期的，所有标签都被设置为 0，收集器从“基本”的元素开始遍历数据。当它遇到内存时，就将标签标记为 1。最后没有被标记为 1 的所有内容都认为是垃圾，以后分配内存时会重新使用它们。 增量的（Incremental）：增量垃圾收集器不需要遍历全部数据对象。因为在收集期间的突然等待，也因为与访问所有当前数据相关的缓存问题（所有内容都不得不被页入（page-in）），遍历所有内存会引发问题。增量收集器避免了这些问题。 保守的（Conservative）：保守的垃圾收集器在管理内存时不需要知道与数据结构相关的任何信息。它们只查看所有数据类型，并假定它们 可以全部都是指针。所以，如果一个字节序列可以是一个指向一块被分配的内存的指针，那么收集器就将其标记为正在被引用。有时没有被引用的内存会被收集，这样会引发问题，例如，如果一个整数域中包含一个值，该值是已分配内存的地址。不过，这种情况极少发生，而且它只会浪费少量内存。保守的收集器的优势是，它们可以与任何编程语言相集成。 Hans Boehm 的保守垃圾收集器是可用的最流行的垃圾收集器之一，因为它是免费的，而且既是保守的又是增量的，可以使用 --enable-redirect-malloc 选项来构建它，并且可以将它用作系统分配程序的简易替代者（drop-in replacement）（用 malloc/ free 代替它自己的 API）。实际上，如果这样做，您就可以使用与我们在示例分配程序中所使用的相同的 LD_PRELOAD 技巧，在系统上的几乎任何程序中启用垃圾收集。如果您怀疑某个程序正在泄漏内存，那么您可以使用这个垃圾收集器来控制进程。在早期，当 Mozilla 严重地泄漏内存时，很多人在其中使用了这项技术。这种垃圾收集器既可以在 Windows® 下运行，也可以在 UNIX 下运行。 垃圾收集的一些优点： 您永远不必担心内存的双重释放或者对象的生命周期。 使用某些收集器，您可以使用与常规分配相同的 API。 其缺点包括： 使用大部分收集器时，您都无法干涉何时释放内存。 在多数情况下，垃圾收集比其他形式的内存管理更慢。 垃圾收集错误引发的缺陷难于调试。 如果您忘记将不再使用的指针设置为 null，那么仍然会有内存泄漏。 回页首 结束语 一切都需要折衷：性能、易用、易于实现、支持线程的能力等，这里只列出了其中的一些。为了满足项目的要求，有很多内存管理模式可以供您使用。每种模式都有大量的实现，各有其优缺点。对很多项目来说，使用编程环境默认的技术就足够了，不过，当您的项目有特殊的需要时，了解可用的选择将会有帮助。下表对比了本文中涉及的内存管理策略。 表 1. 内存分配策略的对比 策略 分配速度 回收速度 局部缓存 易用性 通用性 实时可用 SMP 线程友好 定制分配程序 取决于实现 取决于实现 取决于实现 很难 无 取决于实现 取决于实现 简单分配程序 内存使用少时较快 很快 差 容易 高 否 否 GNU malloc 中 快 中 容易 高 否 中 Hoard 中 中 中 容易 高 否 是 引用计数 N/A N/A 非常好 中 中 是（取决于 malloc 实现） 取决于实现 池 中 非常快 极好 中 中 是（取决于 malloc 实现） 取决于实现 垃圾收集 中（进行收集时慢） 中 差 中 中 否 几乎不 增量垃圾收集 中 中 中 中 中 否 几乎不 增量保守垃圾收集 中 中 中 容易 高 否 几乎不 参考资料 您可以参阅本文在 developerWorks 全球站点上的 英文原文。 Web 上的文档 GNU C Library 手册的 obstacks 部分 提供了 obstacks 编程接口。 Apache Portable Runtime 文档 描述了它们的池式分配程序的接口。 基本的分配程序 Doug Lea 的 Malloc 是最流行的内存分配程序之一。 BSD Malloc 用于大部分基于 BSD 的系统中。 ptmalloc 起源于 Doug Lea 的 malloc，用于 GLIBC 之中。 Hoard 是一个为多线程应用程序优化的 malloc 实现。 GNU Memory-Mapped Malloc（GDB 的组成部分） 是一个基于 mmap() 的 malloc 实现。 池式分配程序 GNU Obstacks（GNU Libc 的组成部分）是安装最多的池式分配程序，因为在每一个基于 glibc 的系统中都有它。 Apache 的池式分配程序（Apache Portable Runtime 中） 是应用最为广泛的池式分配程序。 Squid 有其自己的池式分配程序。 NetBSD 也有其自己的池式分配程序。 talloc 是一个池式分配程序，是 Samba 的组成部分。 智能指针和定制分配程序 Loki C++ Library 有很多为 C++ 实现的通用模式，包括智能指针和一个定制的小对象分配程序。 垃圾收集器 Hahns Boehm Conservative Garbage Collector 是最流行的开源垃圾收集器，它可以用于常规的 C/C++ 程序。 关于现代操作系统中的虚拟内存的文章 Marshall Kirk McKusick 和 Michael J. Karels 合著的 A New Virtual Memory Implementation for Berkeley UNIX 讨论了 BSD 的 VM 系统。 Mel Gorman's Linux VM Documentation 讨论了 Linux VM 系统。 关于 malloc 的文章 Poul-Henning Kamp 撰写的 Malloc in Modern Virtual Memory Environments 讨论的是 malloc 以及它如何与 BSD 虚拟内存交互。 Berger、McKinley、Blumofe 和 Wilson 合著的 Hoard -- a Scalable Memory Allocator for Multithreaded Environments 讨论了 Hoard 分配程序的实现。 Marshall Kirk McKusick 和 Michael J. Karels 合著的 Design of a General Purpose Memory Allocator for the 4.3BSD UNIX Kernel 讨论了内核级的分配程序。 Doug Lea 撰写的 A Memory Allocator 给出了一个关于设计和实现分配程序的概述，其中包括设计选择与折衷。 Emery D. Berger 撰写的 Memory Management for High-Performance Applications 讨论的是定制内存管理以及它如何影响高性能应用程序。 关于定制分配程序的文章 Doug Lea 撰写的 Some Storage Management Techniques for Container Classes 描述的是为 C++ 类编写定制分配程序。 Berger、Zorn 和 McKinley 合著的 Composing High-Performance Memory Allocators 讨论了如何编写定制分配程序来加快具体工作的速度。 Berger、Zorn 和 McKinley 合著的 Reconsidering Custom Memory Allocation 再次提及了定制分配的主题，看是否真正值得为其费心。 关于垃圾收集的文章 Paul R. Wilson 撰写的 Uniprocessor Garbage Collection Techniques 给出了垃圾收集的一个基本概述。 Benjamin Zorn 撰写的 The Measured Cost of Garbage Collection 给出了关于垃圾收集和性能的硬数据（hard data）。 Hans-Juergen Boehm 撰写的 Memory Allocation Myths and Half-Truths 给出了关于垃圾收集的神话（myths）。 Hans-Juergen Boehm 撰写的 Space Efficient Conservative Garbage Collection 是一篇描述他的用于 C/C++ 的垃圾收集器的文章。 Web 上的通用参考资料 内存管理参考 中有很多关于内存管理参考资料和技术文章的链接。 关于内存管理和内存层级的 OOPS Group Papers 是非常好的一组关于此主题的技术文章。 C++ 中的内存管理讨论的是为 C++ 编写定制的分配程序。 Programming Alternatives: Memory Management 讨论了程序员进行内存管理时的一些选择。 垃圾收集 FAQ 讨论了关于垃圾收集您需要了解的所有内容。 Richard Jones 的 Garbage Collection Bibliography 有指向任何您想要的关于垃圾收集的文章的链接。 书籍 Michael Daconta 撰写的 C++ Pointers and Dynamic Memory Management 介绍了关于内存管理的很多技术。 Frantisek Franek 撰写的 Memory as a Programming Concept in C and C++ 讨论了有效使用内存的技术与工具，并给出了在计算机编程中应当引起注意的内存相关错误的角色。 Richard Jones 和 Rafael Lins 合著的 Garbage Collection: Algorithms for Automatic Dynamic Memory Management 描述了当前使用的最常见的垃圾收集算法。 在 Donald Knuth 撰写的 The Art of Computer Programming 第 1 卷 Fundamental Algorithms 的第 2.5 节“Dynamic Storage Allocation”中，描述了实现基本的分配程序的一些技术。 在 Donald Knuth 撰写的 The Art of Computer Programming 第 1 卷 Fundamental Algorithms 的第 2.3.5 节“Lists and Garbage Collection”中，讨论了用于列表的垃圾收集算法。 Andrei Alexandrescu 撰写的 Modern C++ Design 第 4 章“Small Object Allocation”描述了一个比 C++ 标准分配程序效率高得多的一个高速小对象分配程序。 Andrei Alexandrescu 撰写的 Modern C++ Design 第 7 章“Smart Pointers”描述了在 C++ 中智能指针的实现。 Jonathan 撰写的 Programming from the Ground Up 第 8 章“Intermediate Memory Topics”中有本文使用的简单分配程序的一个汇编语言版本。 来自 developerWorks 自我管理数据缓冲区内存 （developerWorks，2004 年 1 月）略述了一个用于管理内存的自管理的抽象数据缓存器的伪 C （pseudo-C）实现。 A framework for the user defined malloc replacement feature （developerWorks，2002 年 2 月）展示了如何利用 AIX 中的一个工具，使用自己设计的内存子系统取代原有的内存子系统。 掌握 Linux 调试技术 （developerWorks，2002 年 8 月）描述了可以使用调试方法的 4 种不同情形：段错误、内存溢出、内存泄漏和挂起。 在 处理 Java 程序中的内存漏洞 （developerWorks，2001 年 2 月）中，了解导致 Java 内存泄漏的原因，以及何时需要考虑它们。 在 developerWorks Linux 专区中，可以找到更多为 Linux 开发人员准备的参考资料。 从 developerWorks 的 Speed-start your Linux app 专区中，可以下载运行于 Linux 之上的 IBM 中间件产品的免费测试版本，其中包括 WebSphere® Studio Application Developer、WebSphere Application Server、DB2® Universal Database、Tivoli® Access Manager 和 Tivoli Directory Server，查找 how-to 文章和技术支持。 通过参与 developerWorks blogs 加入到 developerWorks 社区。 可以在 Developer Bookstore Linux 专栏中定购 打折出售的 Linux 书籍。 关于作者 Jonathan Bartlett 是 Programming from the Ground Up 一书的作者，这本书介绍的是 Linux 汇编语言编程。Jonathan Bartlett 是 New Media Worx 的总开发师，负责为客户开发 Web、视频、kiosk 和桌面应用程序。您可以通过 johnnyb@eskimo.com 与 Jonathan 联系。

python3.6.5参考手册 chm

Python参考手册，官方正式版参考手册，chm版。以下摘取部分内容:Navigation index modules | next | Python » 3.6.5 Documentation » Python Documentation contents What’s New in Python What’s New In Python 3.6 Summary – Release highlights New Features PEP 498: Formatted string literals PEP 526: Syntax for variable annotations PEP 515: Underscores in Numeric Literals PEP 525: Asynchronous Generators PEP 530: Asynchronous Comprehensions PEP 487: Simpler customization of class creation PEP 487: Descriptor Protocol Enhancements PEP 519: Adding a file system path protocol PEP 495: Local Time Disambiguation PEP 529: Change Windows filesystem encoding to UTF-8 PEP 528: Change Windows console encoding to UTF-8 PEP 520: Preserving Class Attribute Definition Order PEP 468: Preserving Keyword Argument Order New dict implementation PEP 523: Adding a frame evaluation API to CPython PYTHONMALLOC environment variable DTrace and SystemTap probing support Other Language Changes New Modules secrets Improved Modules array ast asyncio binascii cmath collections concurrent.futures contextlib datetime decimal distutils email encodings enum faulthandler fileinput hashlib http.client idlelib and IDLE importlib inspect json logging math multiprocessing os pathlib pdb pickle pickletools pydoc random re readline rlcompleter shlex site sqlite3 socket socketserver ssl statistics struct subprocess sys telnetlib time timeit tkinter traceback tracemalloc typing unicodedata unittest.mock urllib.request urllib.robotparser venv warnings winreg winsound xmlrpc.client zipfile zlib Optimizations Build and C API Changes Other Improvements Deprecated New Keywords Deprecated Python behavior Deprecated Python modules, functions and methods asynchat asyncore dbm distutils grp importlib os re ssl tkinter venv Deprecated functions and types of the C API Deprecated Build Options Removed API and Feature Removals Porting to Python 3.6 Changes in ‘python’ Command Behavior Changes in the Python API Changes in the C API CPython bytecode changes Notable changes in Python 3.6.2 New make regen-all build target Removal of make touch build target Notable changes in Python 3.6.5 What’s New In Python 3.5 Summary – Release highlights New Features PEP 492 - Coroutines with async and await syntax PEP 465 - A dedicated infix operator for matrix multiplication PEP 448 - Additional Unpacking Generalizations PEP 461 - percent formatting support for bytes and bytearray PEP 484 - Type Hints PEP 471 - os.scandir() function – a better and faster directory iterator PEP 475: Retry system calls failing with EINTR PEP 479: Change StopIteration handling inside generators PEP 485: A function for testing approximate equality PEP 486: Make the Python Launcher aware of virtual environments PEP 488: Elimination of PYO files PEP 489: Multi-phase extension module initialization Other Language Changes New Modules typing zipapp Improved Modules argparse asyncio bz2 cgi cmath code collections collections.abc compileall concurrent.futures configparser contextlib csv curses dbm difflib distutils doctest email enum faulthandler functools glob gzip heapq http http.client idlelib and IDLE imaplib imghdr importlib inspect io ipaddress json linecache locale logging lzma math multiprocessing operator os pathlib pickle poplib re readline selectors shutil signal smtpd smtplib sndhdr socket ssl Memory BIO Support Application-Layer Protocol Negotiation Support Other Changes sqlite3 subprocess sys sysconfig tarfile threading time timeit tkinter traceback types unicodedata unittest unittest.mock urllib wsgiref xmlrpc xml.sax zipfile Other module-level changes Optimizations Build and C API Changes Deprecated New Keywords Deprecated Python Behavior Unsupported Operating Systems Deprecated Python modules, functions and methods Removed API and Feature Removals Porting to Python 3.5 Changes in Python behavior Changes in the Python API Changes in the C API What’s New In Python 3.4 Summary – Release Highlights New Features PEP 453: Explicit Bootstrapping of PIP in Python Installations Bootstrapping pip By Default Documentation Changes PEP 446: Newly Created File Descriptors Are Non-Inheritable Improvements to Codec Handling PEP 451: A ModuleSpec Type for the Import System Other Language Changes New Modules asyncio ensurepip enum pathlib selectors statistics tracemalloc Improved Modules abc aifc argparse audioop base64 collections colorsys contextlib dbm dis doctest email filecmp functools gc glob hashlib hmac html http idlelib and IDLE importlib inspect ipaddress logging marshal mmap multiprocessing operator os pdb pickle plistlib poplib pprint pty pydoc re resource select shelve shutil smtpd smtplib socket sqlite3 ssl stat struct subprocess sunau sys tarfile textwrap threading traceback types urllib unittest venv wave weakref xml.etree zipfile CPython Implementation Changes PEP 445: Customization of CPython Memory Allocators PEP 442: Safe Object Finalization PEP 456: Secure and Interchangeable Hash Algorithm PEP 436: Argument Clinic Other Build and C API Changes Other Improvements Significant Optimizations Deprecated Deprecations in the Python API Deprecated Features Removed Operating Systems No Longer Supported API and Feature Removals Code Cleanups Porting to Python 3.4 Changes in ‘python’ Command Behavior Changes in the Python API Changes in the C API Changed in 3.4.3 PEP 476: Enabling certificate verification by default for stdlib http clients What’s New In Python 3.3 Summary – Release highlights PEP 405: Virtual Environments PEP 420: Implicit Namespace Packages PEP 3118: New memoryview implementation and buffer protocol documentation Features API changes PEP 393: Flexible String Representation Functionality Performance and resource usage PEP 397: Python Launcher for Windows PEP 3151: Reworking the OS and IO exception hierarchy PEP 380: Syntax for Delegating to a Subgenerator PEP 409: Suppressing exception context PEP 414: Explicit Unicode literals PEP 3155: Qualified name for classes and functions PEP 412: Key-Sharing Dictionary PEP 362: Function Signature Object PEP 421: Adding sys.implementation SimpleNamespace Using importlib as the Implementation of Import New APIs Visible Changes Other Language Changes A Finer-Grained Import Lock Builtin functions and types New Modules faulthandler ipaddress lzma Improved Modules abc array base64 binascii bz2 codecs collections contextlib crypt curses datetime decimal Features API changes email Policy Framework Provisional Policy with New Header API Other API Changes ftplib functools gc hmac http html imaplib inspect io itertools logging math mmap multiprocessing nntplib os pdb pickle pydoc re sched select shlex shutil signal smtpd smtplib socket socketserver sqlite3 ssl stat struct subprocess sys tarfile tempfile textwrap threading time types unittest urllib webbrowser xml.etree.ElementTree zlib Optimizations Build and C API Changes Deprecated Unsupported Operating Systems Deprecated Python modules, functions and methods Deprecated functions and types of the C API Deprecated features Porting to Python 3.3 Porting Python code Porting C code Building C extensions Command Line Switch Changes What’s New In Python 3.2 PEP 384: Defining a Stable ABI PEP 389: Argparse Command Line Parsing Module PEP 391: Dictionary Based Configuration for Logging PEP 3148: The concurrent.futures module PEP 3147: PYC Repository Directories PEP 3149: ABI Version Tagged .so Files PEP 3333: Python Web Server Gateway Interface v1.0.1 Other Language Changes New, Improved, and Deprecated Modules email elementtree functools itertools collections threading datetime and time math abc io reprlib logging csv contextlib decimal and fractions ftp popen select gzip and zipfile tarfile hashlib ast os shutil sqlite3 html socket ssl nntp certificates imaplib http.client unittest random poplib asyncore tempfile inspect pydoc dis dbm ctypes site sysconfig pdb configparser urllib.parse mailbox turtledemo Multi-threading Optimizations Unicode Codecs Documentation IDLE Code Repository Build and C API Changes Porting to Python 3.2 What’s New In Python 3.1 PEP 372: Ordered Dictionaries PEP 378: Format Specifier for Thousands Separator Other Language Changes New, Improved, and Deprecated Modules Optimizations IDLE Build and C API Changes Porting to Python 3.1 What’s New In Python 3.0 Common Stumbling Blocks Print Is A Function Views And Iterators Instead Of Lists Ordering Comparisons Integers Text Vs. Data Instead Of Unicode Vs. 8-bit Overview Of Syntax Changes New Syntax Changed Syntax Removed Syntax Changes Already Present In Python 2.6 Library Changes PEP 3101: A New Approach To String Formatting Changes To Exceptions Miscellaneous Other Changes Operators And Special Methods Builtins Build and C API Changes Performance Porting To Python 3.0 What’s New in Python 2.7 The Future for Python 2.x Changes to the Handling of Deprecation Warnings Python 3.1 Features PEP 372: Adding an Ordered Dictionary to collections PEP 378: Format Specifier for Thousands Separator PEP 389: The argparse Module for Parsing Command Lines PEP 391: Dictionary-Based Configuration For Logging PEP 3106: Dictionary Views PEP 3137: The memoryview Object Other Language Changes Interpreter Changes Optimizations New and Improved Modules New module: importlib New module: sysconfig ttk: Themed Widgets for Tk Updated module: unittest Updated module: ElementTree 1.3 Build and C API Changes Capsules Port-Specific Changes: Windows Port-Specific Changes: Mac OS X Port-Specific Changes: FreeBSD Other Changes and Fixes Porting to Python 2.7 New Features Added to Python 2.7 Maintenance Releases PEP 434: IDLE Enhancement Exception for All Branches PEP 466: Network Security Enhancements for Python 2.7 Acknowledgements What’s New in Python 2.6 Python 3.0 Changes to the Development Process New Issue Tracker: Roundup New Documentation Format: reStructuredText Using Sphinx PEP 343: The ‘with’ statement Writing Context Managers The contextlib module PEP 366: Explicit Relative Imports From a Main Module PEP 370: Per-user site-packages Directory PEP 371: The multiprocessing Package PEP 3101: Advanced String Formatting PEP 3105: print As a Function PEP 3110: Exception-Handling Changes PEP 3112: Byte Literals PEP 3116: New I/O Library PEP 3118: Revised Buffer Protocol PEP 3119: Abstract Base Classes PEP 3127: Integer Literal Support and Syntax PEP 3129: Class Decorators PEP 3141: A Type Hierarchy for Numbers The fractions Module Other Language Changes Optimizations Interpreter Changes New and Improved Modules The ast module The future_builtins module The json module: JavaScript Object Notation The plistlib module: A Property-List Parser ctypes Enhancements Improved SSL Support Deprecations and Removals Build and C API Changes Port-Specific Changes: Windows Port-Specific Changes: Mac OS X Port-Specific Changes: IRIX Porting to Python 2.6 Acknowledgements What’s New in Python 2.5 PEP 308: Conditional Expressions PEP 309: Partial Function Application PEP 314: Metadata for Python Software Packages v1.1 PEP 328: Absolute and Relative Imports PEP 338: Executing Modules as Scripts PEP 341: Unified try/except/finally PEP 342: New Generator Features PEP 343: The ‘with’ statement Writing Context Managers The contextlib module PEP 352: Exceptions as New-Style Classes PEP 353: Using ssize_t as the index type PEP 357: The ‘__index__’ method Other Language Changes Interactive Interpreter Changes Optimizations New, Improved, and Removed Modules The ctypes package The ElementTree package The hashlib package The sqlite3 package The wsgiref package Build and C API Changes Port-Specific Changes Porting to Python 2.5 Acknowledgements What’s New in Python 2.4 PEP 218: Built-In Set Objects PEP 237: Unifying Long Integers and Integers PEP 289: Generator Expressions PEP 292: Simpler String Substitutions PEP 318: Decorators for Functions and Methods PEP 322: Reverse Iteration PEP 324: New subprocess Module PEP 327: Decimal Data Type Why is Decimal needed? The Decimal type The Context type PEP 328: Multi-line Imports PEP 331: Locale-Independent Float/String Conversions Other Language Changes Optimizations New, Improved, and Deprecated Modules cookielib doctest Build and C API Changes Port-Specific Changes Porting to Python 2.4 Acknowledgements What’s New in Python 2.3 PEP 218: A Standard Set Datatype PEP 255: Simple Generators PEP 263: Source Code Encodings PEP 273: Importing Modules from ZIP Archives PEP 277: Unicode file name support for Windows NT PEP 278: Universal Newline Support PEP 279: enumerate() PEP 282: The logging Package PEP 285: A Boolean Type PEP 293: Codec Error Handling Callbacks PEP 301: Package Index and Metadata for Distutils PEP 302: New Import Hooks PEP 305: Comma-separated Files PEP 307: Pickle Enhancements Extended Slices Other Language Changes String Changes Optimizations New, Improved, and Deprecated Modules Date/Time Type The optparse Module Pymalloc: A Specialized Object Allocator Build and C API Changes Port-Specific Changes Other Changes and Fixes Porting to Python 2.3 Acknowledgements What’s New in Python 2.2 Introduction PEPs 252 and 253: Type and Class Changes Old and New Classes Descriptors Multiple Inheritance: The Diamond Rule Attribute Access Related Links PEP 234: Iterators PEP 255: Simple Generators PEP 237: Unifying Long Integers and Integers PEP 238: Changing the Division Operator Unicode Changes PEP 227: Nested Scopes New and Improved Modules Interpreter Changes and Fixes Other Changes and Fixes Acknowledgements What’s New in Python 2.1 Introduction PEP 227: Nested Scopes PEP 236: __future__ Directives PEP 207: Rich Comparisons PEP 230: Warning Framework PEP 229: New Build System PEP 205: Weak References PEP 232: Function Attributes PEP 235: Importing Modules on Case-Insensitive Platforms PEP 217: Interactive Display Hook PEP 208: New Coercion Model PEP 241: Metadata in Python Packages New and Improved Modules Other Changes and Fixes Acknowledgements What’s New in Python 2.0 Introduction What About Python 1.6? New Development Process Unicode List Comprehensions Augmented Assignment String Methods Garbage Collection of Cycles Other Core Changes Minor Language Changes Changes to Built-in Functions Porting to 2.0 Extending/Embedding Changes Distutils: Making Modules Easy to Install XML Modules SAX2 Support DOM Support Relationship to PyXML Module changes New modules IDLE Improvements Deleted and Deprecated Modules Acknowledgements Changelog Python 3.6.5 final? Tests Build Python 3.6.5 release candidate 1? Security Core and Builtins Library Documentation Tests Build Windows macOS IDLE Tools/Demos C API Python 3.6.4 final? Python 3.6.4 release candidate 1? Core and Builtins Library Documentation Tests Build Windows macOS IDLE Tools/Demos C API Python 3.6.3 final? Library Build Python 3.6.3 release candidate 1? Security Core and Builtins Library Documentation Tests Build Windows IDLE Tools/Demos Python 3.6.2 final? Python 3.6.2 release candidate 2? Security Python 3.6.2 release candidate 1? Core and Builtins Library Security Library IDLE C API Build Documentation Tools/Demos Tests Windows Python 3.6.1 final? Core and Builtins Build Python 3.6.1 release candidate 1? Core and Builtins Library IDLE Windows C API Documentation Tests Build Python 3.6.0 final? Python 3.6.0 release candidate 2? Core and Builtins Tools/Demos Windows Build Python 3.6.0 release candidate 1? Core and Builtins Library C API Documentation Tools/Demos Python 3.6.0 beta 4? Core and Builtins Library Documentation Tests Build Python 3.6.0 beta 3? Core and Builtins Library Windows Build Tests Python 3.6.0 beta 2? Core and Builtins Library Windows C API Build Tests Python 3.6.0 beta 1? Core and Builtins Library IDLE C API Tests Build Tools/Demos Windows Python 3.6.0 alpha 4? Core and Builtins Library IDLE Tests Windows Build Python 3.6.0 alpha 3? Core and Builtins Library Security Library Security Library IDLE C API Build Tools/Demos Documentation Tests Python 3.6.0 alpha 2? Core and Builtins Library Security Library Security Library IDLE Documentation Tests Windows Build Windows C API Tools/Demos Python 3.6.0 alpha 1? Core and Builtins Library Security Library Security Library Security Library IDLE Documentation Tests Build Windows Tools/Demos C API Python 3.5.3 final? Python 3.5.3 release candidate 1? Core and Builtins Library Security Library Security Library IDLE C API Documentation Tests Tools/Demos Windows Build Python 3.5.2 final? Core and Builtins Tests IDLE Python 3.5.2 release candidate 1? Core and Builtins Security Library Security Library Security Library Security Library Security Library IDLE Documentation Tests Build Windows Tools/Demos Windows Python 3.5.1 final? Core and Builtins Windows Python 3.5.1 release candidate 1? Core and Builtins Library IDLE Documentation Tests Build Windows Tools/Demos Python 3.5.0 final? Build Python 3.5.0 release candidate 4? Library Build Python 3.5.0 release candidate 3? Core and Builtins Library Python 3.5.0 release candidate 2? Core and Builtins Library Python 3.5.0 release candidate 1? Core and Builtins Library IDLE Documentation Tests Python 3.5.0 beta 4? Core and Builtins Library Build Python 3.5.0 beta 3? Core and Builtins Library Tests Documentation Build Python 3.5.0 beta 2? Core and Builtins Library Python 3.5.0 beta 1? Core and Builtins Library IDLE Tests Documentation Tools/Demos Python 3.5.0 alpha 4? Core and Builtins Library Build Tests Tools/Demos C API Python 3.5.0 alpha 3? Core and Builtins Library Build Tests Tools/Demos Python 3.5.0 alpha 2? Core and Builtins Library Build C API Windows Python 3.5.0 alpha 1? Core and Builtins Library IDLE Build C API Documentation Tests Tools/Demos Windows The Python Tutorial 1. Whetting Your Appetite 2. Using the Python Interpreter 2.1. Invoking the Interpreter 2.1.1. Argument Passing 2.1.2. Interactive Mode 2.2. The Interpreter and Its Environment 2.2.1. Source Code Encoding 3. An Informal Introduction to Python 3.1. Using Python as a Calculator 3.1.1. Numbers 3.1.2. Strings 3.1.3. Lists 3.2. First Steps Towards Programming 4. More Control Flow Tools 4.1. if Statements 4.2. for Statements 4.3. The range() Function 4.4. break and continue Statements, and else Clauses on Loops 4.5. pass Statements 4.6. Defining Functions 4.7. More on Defining Functions 4.7.1. Default Argument Values 4.7.2. Keyword Arguments 4.7.3. Arbitrary Argument Lists 4.7.4. Unpacking Argument Lists 4.7.5. Lambda Expressions 4.7.6. Documentation Strings 4.7.7. Function Annotations 4.8. Intermezzo: Coding Style 5. Data Structures 5.1. More on Lists 5.1.1. Using Lists as Stacks 5.1.2. Using Lists as Queues 5.1.3. List Comprehensions 5.1.4. Nested List Comprehensions 5.2. The del statement 5.3. Tuples and Sequences 5.4. Sets 5.5. Dictionaries 5.6. Looping Techniques 5.7. More on Conditions 5.8. Comparing Sequences and Other Types 6. Modules 6.1. More on Modules 6.1.1. Executing modules as scripts 6.1.2. The Module Search Path 6.1.3. “Compiled” Python files 6.2. Standard Modules 6.3. The dir() Function 6.4. Packages 6.4.1. Importing * From a Package 6.4.2. Intra-package References 6.4.3. Packages in Multiple Directories 7. Input and Output 7.1. Fancier Output Formatting 7.1.1. Old string formatting 7.2. Reading and Writing Files 7.2.1. Methods of File Objects 7.2.2. Saving structured data with json 8. Errors and Exceptions 8.1. Syntax Errors 8.2. Exceptions 8.3. Handling Exceptions 8.4. Raising Exceptions 8.5. User-defined Exceptions 8.6. Defining Clean-up Actions 8.7. Predefined Clean-up Actions 9. Classes 9.1. A Word About Names and Objects 9.2. Python Scopes and Namespaces 9.2.1. Scopes and Namespaces Example 9.3. A First Look at Classes 9.3.1. Class Definition Syntax 9.3.2. Class Objects 9.3.3. Instance Objects 9.3.4. Method Objects 9.3.5. Class and Instance Variables 9.4. Random Remarks 9.5. Inheritance 9.5.1. Multiple Inheritance 9.6. Private Variables 9.7. Odds and Ends 9.8. Iterators 9.9. Generators 9.10. Generator Expressions 10. Brief Tour of the Standard Library 10.1. Operating System Interface 10.2. File Wildcards 10.3. Command Line Arguments 10.4. Error Output Redirection and Program Termination 10.5. String Pattern Matching 10.6. Mathematics 10.7. Internet Access 10.8. Dates and Times 10.9. Data Compression 10.10. Performance Measurement 10.11. Quality Control 10.12. Batteries Included 11. Brief Tour of the Standard Library — Part II 11.1. Output Formatting 11.2. Templating 11.3. Working with Binary Data Record Layouts 11.4. Multi-threading 11.5. Logging 11.6. Weak References 11.7. Tools for Working with Lists 11.8. Decimal Floating Point Arithmetic 12. Virtual Environments and Packages 12.1. Introduction 12.2. Creating Virtual Environments 12.3. Managing Packages with pip 13. What Now? 14. Interactive Input Editing and History Substitution 14.1. Tab Completion and History Editing 14.2. Alternatives to the Interactive Interpreter 15. Floating Point Arithmetic: Issues and Limitations 15.1. Representation Error 16. Appendix 16.1. Interactive Mode 16.1.1. Error Handling 16.1.2. Executable Python Scripts 16.1.3. The Interactive Startup File 16.1.4. The Customization Modules Python Setup and Usage 1. Command line and environment 1.1. Command line 1.1.1. Interface options 1.1.2. Generic options 1.1.3. Miscellaneous options 1.1.4. Options you shouldn’t use 1.2. Environment variables 1.2.1. Debug-mode variables 2. Using Python on Unix platforms 2.1. Getting and installing the latest version of Python 2.1.1. On Linux 2.1.2. On FreeBSD and OpenBSD 2.1.3. On OpenSolaris 2.2. Building Python 2.3. Python-related paths and files 2.4. Miscellaneous 2.5. Editors and IDEs 3. Using Python on Windows 3.1. Installing Python 3.1.1. Supported Versions 3.1.2. Installation Steps 3.1.3. Removing the MAX_PATH Limitation 3.1.4. Installing Without UI 3.1.5. Installing Without Downloading 3.1.6. Modifying an install 3.1.7. Other Platforms 3.2. Alternative bundles 3.3. Configuring Python 3.3.1. Excursus: Setting environment variables 3.3.2. Finding the Python executable 3.4. Python Launcher for Windows 3.4.1. Getting started 3.4.1.1. From the command-line 3.4.1.2. Virtual environments 3.4.1.3. From a script 3.4.1.4. From file associations 3.4.2. Shebang Lines 3.4.3. Arguments in shebang lines 3.4.4. Customization 3.4.4.1. Customization via INI files 3.4.4.2. Customizing default Python versions 3.4.5. Diagnostics 3.5. Finding modules 3.6. Additional modules 3.6.1. PyWin32 3.6.2. cx_Freeze 3.6.3. WConio 3.7. Compiling Python on Windows 3.8. Embedded Distribution 3.8.1. Python Application 3.8.2. Embedding Python 3.9. Other resources 4. Using Python on a Macintosh 4.1. Getting and Installing MacPython 4.1.1. How to run a Python script 4.1.2. Running scripts with a GUI 4.1.3. Configuration 4.2. The IDE 4.3. Installing Additional Python Packages 4.4. GUI Programming on the Mac 4.5. Distributing Python Applications on the Mac 4.6. Other Resources The Python Language Reference 1. Introduction 1.1. Alternate Implementations 1.2. Notation 2. Lexical analysis 2.1. Line structure 2.1.1. Logical lines 2.1.2. Physical lines 2.1.3. Comments 2.1.4. Encoding declarations 2.1.5. Explicit line joining 2.1.6. Implicit line joining 2.1.7. Blank lines 2.1.8. Indentation 2.1.9. Whitespace between tokens 2.2. Other tokens 2.3. Identifiers and keywords 2.3.1. Keywords 2.3.2. Reserved classes of identifiers 2.4. Literals 2.4.1. String and Bytes literals 2.4.2. String literal concatenation 2.4.3. Formatted string literals 2.4.4. Numeric literals 2.4.5. Integer literals 2.4.6. Floating point literals 2.4.7. Imaginary literals 2.5. Operators 2.6. Delimiters 3. Data model 3.1. Objects, values and types 3.2. The standard type hierarchy 3.3. Special method names 3.3.1. Basic customization 3.3.2. Customizing attribute access 3.3.2.1. Customizing module attribute access 3.3.2.2. Implementing Descriptors 3.3.2.3. Invoking Descriptors 3.3.2.4. __slots__ 3.3.2.4.1. Notes on using __slots__ 3.3.3. Customizing class creation 3.3.3.1. Metaclasses 3.3.3.2. Determining the appropriate metaclass 3.3.3.3. Preparing the class namespace 3.3.3.4. Executing the class body 3.3.3.5. Creating the class object 3.3.3.6. Metaclass example 3.3.4. Customizing instance and subclass checks 3.3.5. Emulating callable objects 3.3.6. Emulating container types 3.3.7. Emulating numeric types 3.3.8. With Statement Context Managers 3.3.9. Special method lookup 3.4. Coroutines 3.4.1. Awaitable Objects 3.4.2. Coroutine Objects 3.4.3. Asynchronous Iterators 3.4.4. Asynchronous Context Managers 4. Execution model 4.1. Structure of a program 4.2. Naming and binding 4.2.1. Binding of names 4.2.2. Resolution of names 4.2.3. Builtins and restricted execution 4.2.4. Interaction with dynamic features 4.3. Exceptions 5. The import system 5.1. importlib 5.2. Packages 5.2.1. Regular packages 5.2.2. Namespace packages 5.3. Searching 5.3.1. The module cache 5.3.2. Finders and loaders 5.3.3. Import hooks 5.3.4. The meta path 5.4. Loading 5.4.1. Loaders 5.4.2. Submodules 5.4.3. Module spec 5.4.4. Import-related module attributes 5.4.5. module.__path__ 5.4.6. Module reprs 5.5. The Path Based Finder 5.5.1. Path entry finders 5.5.2. Path entry finder protocol 5.6. Replacing the standard import system 5.7. Special considerations for __main__ 5.7.1. __main__.__spec__ 5.8. Open issues 5.9. References 6. Expressions 6.1. Arithmetic conversions 6.2. Atoms 6.2.1. Identifiers (Names) 6.2.2. Literals 6.2.3. Parenthesized forms 6.2.4. Displays for lists, sets and dictionaries 6.2.5. List displays 6.2.6. Set displays 6.2.7. Dictionary displays 6.2.8. Generator expressions 6.2.9. Yield expressions 6.2.9.1. Generator-iterator methods 6.2.9.2. Examples 6.2.9.3. Asynchronous generator functions 6.2.9.4. Asynchronous generator-iterator methods 6.3. Primaries 6.3.1. Attribute references 6.3.2. Subscriptions 6.3.3. Slicings 6.3.4. Calls 6.4. Await expression 6.5. The power operator 6.6. Unary arithmetic and bitwise operations 6.7. Binary arithmetic operations 6.8. Shifting operations 6.9. Binary bitwise operations 6.10. Comparisons 6.10.1. Value comparisons 6.10.2. Membership test operations 6.10.3. Identity comparisons 6.11. Boolean operations 6.12. Conditional expressions 6.13. Lambdas 6.14. Expression lists 6.15. Evaluation order 6.16. Operator precedence 7. Simple statements 7.1. Expression statements 7.2. Assignment statements 7.2.1. Augmented assignment statements 7.2.2. Annotated assignment statements 7.3. The assert statement 7.4. The pass statement 7.5. The del statement 7.6. The return statement 7.7. The yield statement 7.8. The raise statement 7.9. The break statement 7.10. The continue statement 7.11. The import statement 7.11.1. Future statements 7.12. The global statement 7.13. The nonlocal statement 8. Compound statements 8.1. The if statement 8.2. The while statement 8.3. The for statement 8.4. The try statement 8.5. The with statement 8.6. Function definitions 8.7. Class definitions 8.8. Coroutines 8.8.1. Coroutine function definition 8.8.2. The async for statement 8.8.3. The async with statement 9. Top-level components 9.1. Complete Python programs 9.2. File input 9.3. Interactive input 9.4. Expression input 10. Full Grammar specification The Python Standard Library 1. Introduction 2. Built-in Functions 3. Built-in Constants 3.1. Constants added by the site module 4. Built-in Types 4.1. Truth Value Testing 4.2. Boolean Operations — and, or, not 4.3. Comparisons 4.4. Numeric Types — int, float, complex 4.4.1. Bitwise Operations on Integer Types 4.4.2. Additional Methods on Integer Types 4.4.3. Additional Methods on Float 4.4.4. Hashing of numeric types 4.5. Iterator Types 4.5.1. Generator Types 4.6. Sequence Types — list, tuple, range 4.6.1. Common Sequence Operations 4.6.2. Immutable Sequence Types 4.6.3. Mutable Sequence Types 4.6.4. Lists 4.6.5. Tuples 4.6.6. Ranges 4.7. Text Sequence Type — str 4.7.1. String Methods 4.7.2. printf-style String Formatting 4.8. Binary Sequence Types — bytes, bytearray, memoryview 4.8.1. Bytes Objects 4.8.2. Bytearray Objects 4.8.3. Bytes and Bytearray Operations 4.8.4. printf-style Bytes Formatting 4.8.5. Memory Views 4.9. Set Types — set, frozenset 4.10. Mapping Types — dict 4.10.1. Dictionary view objects 4.11. Context Manager Types 4.12. Other Built-in Types 4.12.1. Modules 4.12.2. Classes and Class Instances 4.12.3. Functions 4.12.4. Methods 4.12.5. Code Objects 4.12.6. Type Objects 4.12.7. The Null Object 4.12.8. The Ellipsis Object 4.12.9. The NotImplemented Object 4.12.10. Boolean Values 4.12.11. Internal Objects 4.13. Special Attributes 5. Built-in Exceptions 5.1. Base classes 5.2. Concrete exceptions 5.2.1. OS exceptions 5.3. Warnings 5.4. Exception hierarchy 6. Text Processing Services 6.1. string — Common string operations 6.1.1. String constants 6.1.2. Custom String Formatting 6.1.3. Format String Syntax 6.1.3.1. Format Specification Mini-Language 6.1.3.2. Format examples 6.1.4. Template strings 6.1.5. Helper functions 6.2. re — Regular expression operations 6.2.1. Regular Expression Syntax 6.2.2. Module Contents 6.2.3. Regular Expression Objects 6.2.4. Match Objects 6.2.5. Regular Expression Examples 6.2.5.1. Checking for a Pair 6.2.5.2. Simulating scanf() 6.2.5.3. search() vs. match() 6.2.5.4. Making a Phonebook 6.2.5.5. Text Munging 6.2.5.6. Finding all Adverbs 6.2.5.7. Finding all Adverbs and their Positions 6.2.5.8. Raw String Notation 6.2.5.9. Writing a Tokenizer 6.3. difflib — Helpers for computing deltas 6.3.1. SequenceMatcher Objects 6.3.2. SequenceMatcher Examples 6.3.3. Differ Objects 6.3.4. Differ Example 6.3.5. A command-line interface to difflib 6.4. textwrap — Text wrapping and filling 6.5. unicodedata — Unicode Database 6.6. stringprep — Internet String Preparation 6.7. readline — GNU readline interface 6.7.1. Init file 6.7.2. Line buffer 6.7.3. History file 6.7.4. History list 6.7.5. Startup hooks 6.7.6. Completion 6.7.7. Example 6.8. rlcompleter — Completion function for GNU readline 6.8.1. Completer Objects 7. Binary Data Services 7.1. struct — Interpret bytes as packed binary data 7.1.1. Functions and Exceptions 7.1.2. Format Strings 7.1.2.1. Byte Order, Size, and Alignment 7.1.2.2. Format Characters 7.1.2.3. Examples 7.1.3. Classes 7.2. codecs — Codec registry and base classes 7.2.1. Codec Base Classes 7.2.1.1. Error Handlers 7.2.1.2. Stateless Encoding and Decoding 7.2.1.3. Incremental Encoding and Decoding 7.2.1.3.1. IncrementalEncoder Objects 7.2.1.3.2. IncrementalDecoder Objects 7.2.1.4. Stream Encoding and Decoding 7.2.1.4.1. StreamWriter Objects 7.2.1.4.2. StreamReader Objects 7.2.1.4.3. StreamReaderWriter Objects 7.2.1.4.4. StreamRecoder Objects 7.2.2. Encodings and Unicode 7.2.3. Standard Encodings 7.2.4. Python Specific Encodings 7.2.4.1. Text Encodings 7.2.4.2. Binary Transforms 7.2.4.3. Text Transforms 7.2.5. encodings.idna — Internationalized Domain Names in Applications 7.2.6. encodings.mbcs — Windows ANSI codepage 7.2.7. encodings.utf_8_sig — UTF-8 codec with BOM signature 8. Data Types 8.1. datetime — Basic date and time types 8.1.1. Available Types 8.1.2. timedelta Objects 8.1.3. date Objects 8.1.4. datetime Objects 8.1.5. time Objects 8.1.6. tzinfo Objects 8.1.7. timezone Objects 8.1.8. strftime() and strptime() Behavior 8.2. calendar — General calendar-related functions 8.3. collections — Container datatypes 8.3.1. ChainMap objects 8.3.1.1. ChainMap Examples and Recipes 8.3.2. Counter objects 8.3.3. deque objects 8.3.3.1. deque Recipes 8.3.4. defaultdict objects 8.3.4.1. defaultdict Examples 8.3.5. namedtuple() Factory Function for Tuples with Named Fields 8.3.6. OrderedDict objects 8.3.6.1. OrderedDict Examples and Recipes 8.3.7. UserDict objects 8.3.8. UserList objects 8.3.9. UserString objects 8.4. collections.abc — Abstract Base Classes for Containers 8.4.1. Collections Abstract Base Classes 8.5. heapq — Heap queue algorithm 8.5.1. Basic Examples 8.5.2. Priority Queue Implementation Notes 8.5.3. Theory 8.6. bisect — Array bisection algorithm 8.6.1. Searching Sorted Lists 8.6.2. Other Examples 8.7. array — Efficient arrays of numeric values 8.8. weakref — Weak references 8.8.1. Weak Reference Objects 8.8.2. Example 8.8.3. Finalizer Objects 8.8.4. Comparing finalizers with __del__() methods 8.9. types — Dynamic type creation and names for built-in types 8.9.1. Dynamic Type Creation 8.9.2. Standard Interpreter Types 8.9.3. Additional Utility Classes and Functions 8.9.4. Coroutine Utility Functions 8.10. copy — Shallow and deep copy operations 8.11. pprint — Data pretty printer 8.11.1. PrettyPrinter Objects 8.11.2. Example 8.12. reprlib — Alternate repr() implementation 8.12.1. Repr Objects 8.12.2. Subclassing Repr Objects 8.13. enum — Support for enumerations 8.13.1. Module Contents 8.13.2. Creating an Enum 8.13.3. Programmatic access to enumeration members and their attributes 8.13.4. Duplicating enum members and values 8.13.5. Ensuring unique enumeration values 8.13.6. Using automatic values 8.13.7. Iteration 8.13.8. Comparisons 8.13.9. Allowed members and attributes of enumerations 8.13.10. Restricted subclassing of enumerations 8.13.11. Pickling 8.13.12. Functional API 8.13.13. Derived Enumerations 8.13.13.1. IntEnum 8.13.13.2. IntFlag 8.13.13.3. Flag 8.13.13.4. Others 8.13.14. Interesting examples 8.13.14.1. Omitting values 8.13.14.1.1. Using auto 8.13.14.1.2. Using object 8.13.14.1.3. Using a descriptive string 8.13.14.1.4. Using a custom __new__() 8.13.14.2. OrderedEnum 8.13.14.3. DuplicateFreeEnum 8.13.14.4. Planet 8.13.15. How are Enums different? 8.13.15.1. Enum Classes 8.13.15.2. Enum Members (aka instances) 8.13.15.3. Finer Points 8.13.15.3.1. Supported __dunder__ names 8.13.15.3.2. Supported _sunder_ names 8.13.15.3.3. Enum member type 8.13.15.3.4. Boolean value of Enum classes and members 8.13.15.3.5. Enum classes with methods 8.13.15.3.6. Combining members of Flag 9. Numeric and Mathematical Modules 9.1. numbers — Numeric abstract base classes 9.1.1. The numeric tower 9.1.2. Notes for type implementors 9.1.2.1. Adding More Numeric ABCs 9.1.2.2. Implementing the arithmetic operations 9.2. math — Mathematical functions 9.2.1. Number-theoretic and representation functions 9.2.2. Power and logarithmic functions 9.2.3. Trigonometric functions 9.2.4. Angular conversion 9.2.5. Hyperbolic functions 9.2.6. Special functions 9.2.7. Constants 9.3. cmath — Mathematical functions for complex numbers 9.3.1. Conversions to and from polar coordinates 9.3.2. Power and logarithmic functions 9.3.3. Trigonometric functions 9.3.4. Hyperbolic functions 9.3.5. Classification functions 9.3.6. Constants 9.4. decimal — Decimal fixed point and floating point arithmetic 9.4.1. Quick-start Tutorial 9.4.2. Decimal objects 9.4.2.1. Logical operands 9.4.3. Context objects 9.4.4. Constants 9.4.5. Rounding modes 9.4.6. Signals 9.4.7. Floating Point Notes 9.4.7.1. Mitigating round-off error with increased precision 9.4.7.2. Special values 9.4.8. Working with threads 9.4.9. Recipes 9.4.10. Decimal FAQ 9.5. fractions — Rational numbers 9.6. random — Generate pseudo-random numbers 9.6.1. Bookkeeping functions 9.6.2. Functions for integers 9.6.3. Functions for sequences 9.6.4. Real-valued distributions 9.6.5. Alternative Generator 9.6.6. Notes on Reproducibility 9.6.7. Examples and Recipes 9.7. statistics — Mathematical statistics functions 9.7.1. Averages and measures of central location 9.7.2. Measures of spread 9.7.3. Function details 9.7.4. Exceptions 10. Functional Programming Modules 10.1. itertools — Functions creating iterators for efficient looping 10.1.1. Itertool functions 10.1.2. Itertools Recipes 10.2. functools — Higher-order functions and operations on callable objects 10.2.1. partial Objects 10.3. operator — Standard operators as functions 10.3.1. Mapping Operators to Functions 10.3.2. Inplace Operators 11. File and Directory Access 11.1. pathlib — Object-oriented filesystem paths 11.1.1. Basic use 11.1.2. Pure paths 11.1.2.1. General properties 11.1.2.2. Operators 11.1.2.3. Accessing individual parts 11.1.2.4. Methods and properties 11.1.3. Concrete paths 11.1.3.1. Methods 11.2. os.path — Common pathname manipulations 11.3. fileinput — Iterate over lines from multiple input streams 11.4. stat — Interpreting stat() results 11.5. filecmp — File and Directory Comparisons 11.5.1. The dircmp class 11.6. tempfile — Generate temporary files and directories 11.6.1. Examples 11.6.2. Deprecated functions and variables 11.7. glob — Unix style pathname pattern expansion 11.8. fnmatch — Unix filename pattern matching 11.9. linecache — Random access to text lines 11.10. shutil — High-level file operations 11.10.1. Directory and files operations 11.10.1.1. copytree example 11.10.1.2. rmtree example 11.10.2. Archiving operations 11.10.2.1. Archiving example 11.10.3. Querying the size of the output terminal 11.11. macpath — Mac OS 9 path manipulation functions 12. Data Persistence 12.1. pickle — Python object serialization 12.1.1. Relationship to other Python modules 12.1.1.1. Comparison with marshal 12.1.1.2. Comparison with json 12.1.2. Data stream format 12.1.3. Module Interface 12.1.4. What can be pickled and unpickled? 12.1.5. Pickling Class Instances 12.1.5.1. Persistence of External Objects 12.1.5.2. Dispatch Tables 12.1.5.3. Handling Stateful Objects 12.1.6. Restricting Globals 12.1.7. Performance 12.1.8. Examples 12.2. copyreg — Register pickle support functions 12.2.1. Example 12.3. shelve — Python object persistence 12.3.1. Restrictions 12.3.2. Example 12.4. marshal — Internal Python object serialization 12.5. dbm — Interfaces to Unix “databases” 12.5.1. dbm.gnu — GNU’s reinterpretation of dbm 12.5.2. dbm.ndbm — Interface based on ndbm 12.5.3. dbm.dumb — Portable DBM implementation 12.6. sqlite3 — DB-API 2.0 interface for SQLite databases 12.6.1. Module functions and constants 12.6.2. Connection Objects 12.6.3. Cursor Objects 12.6.4. Row Objects 12.6.5. Exceptions 12.6.6. SQLite and Python types 12.6.6.1. Introduction 12.6.6.2. Using adapters to store additional Python types in SQLite databases 12.6.6.2.1. Letting your object adapt itself 12.6.6.2.2. Registering an adapter callable 12.6.6.3. Converting SQLite values to custom Python types 12.6.6.4. Default adapters and converters 12.6.7. Controlling Transactions 12.6.8. Using sqlite3 efficiently 12.6.8.1. Using shortcut methods 12.6.8.2. Accessing columns by name instead of by index 12.6.8.3. Using the connection as a context manager 12.6.9. Common issues 12.6.9.1. Multithreading 13. Data Compression and Archiving 13.1. zlib — Compression compatible with gzip 13.2. gzip — Support for gzip files 13.2.1. Examples of usage 13.3. bz2 — Support for bzip2 compression 13.3.1. (De)compression of files 13.3.2. Incremental (de)compression 13.3.3. One-shot (de)compression 13.4. lzma — Compression using the LZMA algorithm 13.4.1. Reading and writing compressed files 13.4.2. Compressing and decompressing data in memory 13.4.3. Miscellaneous 13.4.4. Specifying custom filter chains 13.4.5. Examples 13.5. zipfile — Work with ZIP archives 13.5.1. ZipFile Objects 13.5.2. PyZipFile Objects 13.5.3. ZipInfo Objects 13.5.4. Command-Line Interface 13.5.4.1. Command-line options 13.6. tarfile — Read and write tar archive files 13.6.1. TarFile Objects 13.6.2. TarInfo Objects 13.6.3. Command-Line Interface 13.6.3.1. Command-line options 13.6.4. Examples 13.6.5. Supported tar formats 13.6.6. Unicode issues 14. File Formats 14.1. csv — CSV File Reading and Writing 14.1.1. Module Contents 14.1.2. Dialects and Formatting Parameters 14.1.3. Reader Objects 14.1.4. Writer Objects 14.1.5. Examples 14.2. configparser — Configuration file parser 14.2.1. Quick Start 14.2.2. Supported Datatypes 14.2.3. Fallback Values 14.2.4. Supported INI File Structure 14.2.5. Interpolation of values 14.2.6. Mapping Protocol Access 14.2.7. Customizing Parser Behaviour 14.2.8. Legacy API Examples 14.2.9. ConfigParser Objects 14.2.10. RawConfigParser Objects 14.2.11. Exceptions 14.3. netrc — netrc file processing 14.3.1. netrc Objects 14.4. xdrlib — Encode and decode XDR data 14.4.1. Packer Objects 14.4.2. Unpacker Objects 14.4.3. Exceptions 14.5. plistlib — Generate and parse Mac OS X .plist files 14.5.1. Examples 15. Cryptographic Services 15.1. hashlib — Secure hashes and message digests 15.1.1. Hash algorithms 15.1.2. SHAKE variable length digests 15.1.3. Key derivation 15.1.4. BLAKE2 15.1.4.1. Creating hash objects 15.1.4.2. Constants 15.1.4.3. Examples 15.1.4.3.1. Simple hashing 15.1.4.3.2. Using different digest sizes 15.1.4.3.3. Keyed hashing 15.1.4.3.4. Randomized hashing 15.1.4.3.5. Personalization 15.1.4.3.6. Tree mode 15.1.4.4. Credits 15.2. hmac — Keyed-Hashing for Message Authentication 15.3. secrets — Generate secure random numbers for managing secrets 15.3.1. Random numbers 15.3.2. Generating tokens 15.3.2.1. How many bytes should tokens use? 15.3.3. Other functions 15.3.4. Recipes and best practices 16. Generic Operating System Services 16.1. os — Miscellaneous operating system interfaces 16.1.1. File Names, Command Line Arguments, and Environment Variables 16.1.2. Process Parameters 16.1.3. File Object Creation 16.1.4. File Descriptor Operations 16.1.4.1. Querying the size of a terminal 16.1.4.2. Inheritance of File Descriptors 16.1.5. Files and Directories 16.1.5.1. Linux extended attributes 16.1.6. Process Management 16.1.7. Interface to the scheduler 16.1.8. Miscellaneous System Information 16.1.9. Random numbers 16.2. io — Core tools for working with streams 16.2.1. Overview 16.2.1.1. Text I/O 16.2.1.2. Binary I/O 16.2.1.3. Raw I/O 16.2.2. High-level Module Interface 16.2.2.1. In-memory streams 16.2.3. Class hierarchy 16.2.3.1. I/O Base Classes 16.2.3.2. Raw File I/O 16.2.3.3. Buffered Streams 16.2.3.4. Text I/O 16.2.4. Performance 16.2.4.1. Binary I/O 16.2.4.2. Text I/O 16.2.4.3. Multi-threading 16.2.4.4. Reentrancy 16.3. time — Time access and conversions 16.3.1. Functions 16.3.2. Clock ID Constants 16.3.3. Timezone Constants 16.4. argparse — Parser for command-line options, arguments and sub-commands 16.4.1. Example 16.4.1.1. Creating a parser 16.4.1.2. Adding arguments 16.4.1.3. Parsing arguments 16.4.2. ArgumentParser objects 16.4.2.1. prog 16.4.2.2. usage 16.4.2.3. description 16.4.2.4. epilog 16.4.2.5. parents 16.4.2.6. formatter_class 16.4.2.7. prefix_chars 16.4.2.8. fromfile_prefix_chars 16.4.2.9. argument_default 16.4.2.10. allow_abbrev 16.4.2.11. conflict_handler 16.4.2.12. add_help 16.4.3. The add_argument() method 16.4.3.1. name or flags 16.4.3.2. action 16.4.3.3. nargs 16.4.3.4. const 16.4.3.5. default 16.4.3.6. type 16.4.3.7. choices 16.4.3.8. required 16.4.3.9. help 16.4.3.10. metavar 16.4.3.11. dest 16.4.3.12. Action classes 16.4.4. The parse_args() method 16.4.4.1. Option value syntax 16.4.4.2. Invalid arguments 16.4.4.3. Arguments containing - 16.4.4.4. Argument abbreviations (prefix matching) 16.4.4.5. Beyond sys.argv 16.4.4.6. The Namespace object 16.4.5. Other utilities 16.4.5.1. Sub-commands 16.4.5.2. FileType objects 16.4.5.3. Argument groups 16.4.5.4. Mutual exclusion 16.4.5.5. Parser defaults 16.4.5.6. Printing help 16.4.5.7. Partial parsing 16.4.5.8. Customizing file parsing 16.4.5.9. Exiting methods 16.4.6. Upgrading optparse code 16.5. getopt — C-style parser for command line options 16.6. logging — Logging facility for Python 16.6.1. Logger Objects 16.6.2. Logging Levels 16.6.3. Handler Objects 16.6.4. Formatter Objects 16.6.5. Filter Objects 16.6.6. LogRecord Objects 16.6.7. LogRecord attributes 16.6.8. LoggerAdapter Objects 16.6.9. Thread Safety 16.6.10. Module-Level Functions 16.6.11. Module-Level Attributes 16.6.12. Integration with the warnings module 16.7. logging.config — Logging configuration 16.7.1. Configuration functions 16.7.2. Configuration dictionary schema 16.7.2.1. Dictionary Schema Details 16.7.2.2. Incremental Configuration 16.7.2.3. Object connections 16.7.2.4. User-defined objects 16.7.2.5. Access to external objects 16.7.2.6. Access to internal objects 16.7.2.7. Import resolution and custom importers 16.7.3. Configuration file format 16.8. logging.handlers — Logging handlers 16.8.1. StreamHandler 16.8.2. FileHandler 16.8.3. NullHandler 16.8.4. WatchedFileHandler 16.8.5. BaseRotatingHandler 16.8.6. RotatingFileHandler 16.8.7. TimedRotatingFileHandler 16.8.8. SocketHandler 16.8.9. DatagramHandler 16.8.10. SysLogHandler 16.8.11. NTEventLogHandler 16.8.12. SMTPHandler 16.8.13. MemoryHandler 16.8.14. HTTPHandler 16.8.15. QueueHandler 16.8.16. QueueListener 16.9. getpass — Portable password input 16.10. curses — Terminal handling for character-cell displays 16.10.1. Functions 16.10.2. Window Objects 16.10.3. Constants 16.11. curses.textpad — Text input widget for curses programs 16.11.1. Textbox objects 16.12. curses.ascii — Utilities for ASCII characters 16.13. curses.panel — A panel stack extension for curses 16.13.1. Functions 16.13.2. Panel Objects 16.14. platform — Access to underlying platform’s identifying data 16.14.1. Cross Platform 16.14.2. Java Platform 16.14.3. Windows Platform 16.14.3.1. Win95/98 specific 16.14.4. Mac OS Platform 16.14.5. Unix Platforms 16.15. errno — Standard errno system symbols 16.16. ctypes — A foreign function library for Python 16.16.1. ctypes tutorial 16.16.1.1. Loading dynamic link libraries 16.16.1.2. Accessing functions from loaded dlls 16.16.1.3. Calling functions 16.16.1.4. Fundamental data types 16.16.1.5. Calling functions, continued 16.16.1.6. Calling functions with your own custom data types 16.16.1.7. Specifying the required argument types (function prototypes) 16.16.1.8. Return types 16.16.1.9. Passing pointers (or: passing parameters by reference) 16.16.1.10. Structures and unions 16.16.1.11. Structure/union alignment and byte order 16.16.1.12. Bit fields in structures and unions 16.16.1.13. Arrays 16.16.1.14. Pointers 16.16.1.15. Type conversions 16.16.1.16. Incomplete Types 16.16.1.17. Callback functions 16.16.1.18. Accessing values exported from dlls 16.16.1.19. Surprises 16.16.1.20. Variable-sized data types 16.16.2. ctypes reference 16.16.2.1. Finding shared libraries 16.16.2.2. Loading shared libraries 16.16.2.3. Foreign functions 16.16.2.4. Function prototypes 16.16.2.5. Utility functions 16.16.2.6. Data types 16.16.2.7. Fundamental data types 16.16.2.8. Structured data types 16.16.2.9. Arrays and pointers 17. Concurrent Execution 17.1. threading — Thread-based parallelism 17.1.1. Thread-Local Data 17.1.2. Thread Objects 17.1.3. Lock Objects 17.1.4. RLock Objects 17.1.5. Condition Objects 17.1.6. Semaphore Objects 17.1.6.1. Semaphore Example 17.1.7. Event Objects 17.1.8. Timer Objects 17.1.9. Barrier Objects 17.1.10. Using locks, conditions, and semaphores in the with statement 17.2. multiprocessing — Process-based parallelism 17.2.1. Introduction 17.2.1.1. The Process class 17.2.1.2. Contexts and start methods 17.2.1.3. Exchanging objects between processes 17.2.1.4. Synchronization between processes 17.2.1.5. Sharing state between processes 17.2.1.6. Using a pool of workers 17.2.2. Reference 17.2.2.1. Process and exceptions 17.2.2.2. Pipes and Queues 17.2.2.3. Miscellaneous 17.2.2.4. Connection Objects 17.2.2.5. Synchronization primitives 17.2.2.6. Shared ctypes Objects 17.2.2.6.1. The multiprocessing.sharedctypes module 17.2.2.7. Managers 17.2.2.7.1. Customized managers 17.2.2.7.2. Using a remote manager 17.2.2.8. Proxy Objects 17.2.2.8.1. Cleanup 17.2.2.9. Process Pools 17.2.2.10. Listeners and Clients 17.2.2.10.1. Address Formats 17.2.2.11. Authentication keys 17.2.2.12. Logging 17.2.2.13. The multiprocessing.dummy module 17.2.3. Programming guidelines 17.2.3.1. All start methods 17.2.3.2. The spawn and forkserver start methods 17.2.4. Examples 17.3. The concurrent package 17.4. concurrent.futures — Launching parallel tasks 17.4.1. Executor Objects 17.4.2. ThreadPoolExecutor 17.4.2.1. ThreadPoolExecutor Example 17.4.3. ProcessPoolExecutor 17.4.3.1. ProcessPoolExecutor Example 17.4.4. Future Objects 17.4.5. Module Functions 17.4.6. Exception classes 17.5. subprocess — Subprocess management 17.5.1. Using the subprocess Module 17.5.1.1. Frequently Used Arguments 17.5.1.2. Popen Constructor 17.5.1.3. Exceptions 17.5.2. Security Considerations 17.5.3. Popen Objects 17.5.4. Windows Popen Helpers 17.5.4.1. Constants 17.5.5. Older high-level API 17.5.6. Replacing Older Functions with the subprocess Module 17.5.6.1. Replacing /bin/sh shell backquote 17.5.6.2. Replacing shell pipeline 17.5.6.3. Replacing os.system() 17.5.6.4. Replacing the os.spawn family 17.5.6.5. Replacing os.popen(), os.popen2(), os.popen3() 17.5.6.6. Replacing functions from the popen2 module 17.5.7. Legacy Shell Invocation Functions 17.5.8. Notes 17.5.8.1. Converting an argument sequence to a string on Windows 17.6. sched — Event scheduler 17.6.1. Scheduler Objects 17.7. queue — A synchronized queue class 17.7.1. Queue Objects 17.8. dummy_threading — Drop-in replacement for the threading module 17.9. _thread — Low-level threading API 17.10. _dummy_thread — Drop-in replacement for the _thread module 18. Interprocess Communication and Networking 18.1. socket — Low-level networking interface 18.1.1. Socket families 18.1.2. Module contents 18.1.2.1. Exceptions 18.1.2.2. Constants 18.1.2.3. Functions 18.1.2.3.1. Creating sockets 18.1.2.3.2. Other functions 18.1.3. Socket Objects 18.1.4. Notes on socket timeouts 18.1.4.1. Timeouts and the connect method 18.1.4.2. Timeouts and the accept method 18.1.5. Example 18.2. ssl — TLS/SSL wrapper for socket objects 18.2.1. Functions, Constants, and Exceptions 18.2.1.1. Socket creation 18.2.1.2. Context creation 18.2.1.3. Random generation 18.2.1.4. Certificate handling 18.2.1.5. Constants 18.2.2. SSL Sockets 18.2.3. SSL Contexts 18.2.4. Certificates 18.2.4.1. Certificate chains 18.2.4.2. CA certificates 18.2.4.3. Combined key and certificate 18.2.4.4. Self-signed certificates 18.2.5. Examples 18.2.5.1. Testing for SSL support 18.2.5.2. Client-side operation 18.2.5.3. Server-side operation 18.2.6. Notes on non-blocking sockets 18.2.7. Memory BIO Support 18.2.8. SSL session 18.2.9. Security considerations 18.2.9.1. Best defaults 18.2.9.2. Manual settings 18.2.9.2.1. Verifying certificates 18.2.9.2.2. Protocol versions 18.2.9.2.3. Cipher selection 18.2.9.3. Multi-processing 18.2.10. LibreSSL support 18.3. select — Waiting for I/O completion 18.3.1. /dev/poll Polling Objects 18.3.2. Edge and Level Trigger Polling (epoll) Objects 18.3.3. Polling Objects 18.3.4. Kqueue Objects 18.3.5. Kevent Objects 18.4. selectors — High-level I/O multiplexing 18.4.1. Introduction 18.4.2. Classes 18.4.3. Examples 18.5. asyncio — Asynchronous I/O, event loop, coroutines and tasks 18.5.1. Base Event Loop 18.5.1.1. Run an event loop 18.5.1.2. Calls 18.5.1.3. Delayed calls 18.5.1.4. Futures 18.5.1.5. Tasks 18.5.1.6. Creating connections 18.5.1.7. Creating listening connections 18.5.1.8. Watch file descriptors 18.5.1.9. Low-level socket operations 18.5.1.10. Resolve host name 18.5.1.11. Connect pipes 18.5.1.12. UNIX signals 18.5.1.13. Executor 18.5.1.14. Error Handling API 18.5.1.15. Debug mode 18.5.1.16. Server 18.5.1.17. Handle 18.5.1.18. Event loop examples 18.5.1.18.1. Hello World with call_soon() 18.5.1.18.2. Display the current date with call_later() 18.5.1.18.3. Watch a file descriptor for read events 18.5.1.18.4. Set signal handlers for SIGINT and SIGTERM 18.5.2. Event loops 18.5.2.1. Event loop functions 18.5.2.2. Available event loops 18.5.2.3. Platform support 18.5.2.3.1. Windows 18.5.2.3.2. Mac OS X 18.5.2.4. Event loop policies and the default policy 18.5.2.5. Event loop policy interface 18.5.2.6. Access to the global loop policy 18.5.2.7. Customizing the event loop policy 18.5.3. Tasks and coroutines 18.5.3.1. Coroutines 18.5.3.1.1. Example: Hello World coroutine 18.5.3.1.2. Example: Coroutine displaying the current date 18.5.3.1.3. Example: Chain coroutines 18.5.3.2. InvalidStateError 18.5.3.3. TimeoutError 18.5.3.4. Future 18.5.3.4.1. Example: Future with run_until_complete() 18.5.3.4.2. Example: Future with run_forever() 18.5.3.5. Task 18.5.3.5.1. Example: Parallel execution of tasks 18.5.3.6. Task functions 18.5.4. Transports and protocols (callback based API) 18.5.4.1. Transports 18.5.4.1.1. BaseTransport 18.5.4.1.2. ReadTransport 18.5.4.1.3. WriteTransport 18.5.4.1.4. DatagramTransport 18.5.4.1.5. BaseSubprocessTransport 18.5.4.2. Protocols 18.5.4.2.1. Protocol classes 18.5.4.2.2. Connection callbacks 18.5.4.2.3. Streaming protocols 18.5.4.2.4. Datagram protocols 18.5.4.2.5. Flow control callbacks 18.5.4.2.6. Coroutines and protocols 18.5.4.3. Protocol examples 18.5.4.3.1. TCP echo client protocol 18.5.4.3.2. TCP echo server protocol 18.5.4.3.3. UDP echo client protocol 18.5.4.3.4. UDP echo server protocol 18.5.4.3.5. Register an open socket to wait for data using a protocol 18.5.5. Streams (coroutine based API) 18.5.5.1. Stream functions 18.5.5.2. StreamReader 18.5.5.3. StreamWriter 18.5.5.4. StreamReaderProtocol 18.5.5.5. IncompleteReadError 18.5.5.6. LimitOverrunError 18.5.5.7. Stream examples 18.5.5.7.1. TCP echo client using streams 18.5.5.7.2. TCP echo server using streams 18.5.5.7.3. Get HTTP headers 18.5.5.7.4. Register an open socket to wait for data using streams 18.5.6. Subprocess 18.5.6.1. Windows event loop 18.5.6.2. Create a subprocess: high-level API using Process 18.5.6.3. Create a subprocess: low-level API using subprocess.Popen 18.5.6.4. Constants 18.5.6.5. Process 18.5.6.6. Subprocess and threads 18.5.6.7. Subprocess examples 18.5.6.7.1. Subprocess using transport and protocol 18.5.6.7.2. Subprocess using streams 18.5.7. Synchronization primitives 18.5.7.1. Locks 18.5.7.1.1. Lock 18.5.7.1.2. Event 18.5.7.1.3. Condition 18.5.7.2. Semaphores 18.5.7.2.1. Semaphore 18.5.7.2.2. BoundedSemaphore 18.5.8. Queues 18.5.8.1. Queue 18.5.8.2. PriorityQueue 18.5.8.3. LifoQueue 18.5.8.3.1. Exceptions 18.5.9. Develop with asyncio 18.5.9.1. Debug mode of asyncio 18.5.9.2. Cancellation 18.5.9.3. Concurrency and multithreading 18.5.9.4. Handle blocking functions correctly 18.5.9.5. Logging 18.5.9.6. Detect coroutine objects never scheduled 18.5.9.7. Detect exceptions never consumed 18.5.9.8. Chain coroutines correctly 18.5.9.9. Pending task destroyed 18.5.9.10. Close transports and event loops 18.6. asyncore — Asynchronous socket handler 18.6.1. asyncore Example basic HTTP client 18.6.2. asyncore Example basic echo server 18.7. asynchat — Asynchronous socket command/response handler 18.7.1. asynchat Example 18.8. signal — Set handlers for asynchronous events 18.8.1. General rules 18.8.1.1. Execution of Python signal handlers 18.8.1.2. Signals and threads 18.8.2. Module contents 18.8.3. Example 18.9. mmap — Memory-mapped file support 19. Internet Data Handling 19.1. email — An email and MIME handling package 19.1.1. email.message: Representing an email message 19.1.2. email.parser: Parsing email messages 19.1.2.1. FeedParser API 19.1.2.2. Parser API 19.1.2.3. Additional notes 19.1.3. email.generator: Generating MIME documents 19.1.4. email.policy: Policy Objects 19.1.5. email.errors: Exception and Defect classes 19.1.6. email.headerregistry: Custom Header Objects 19.1.7. email.contentmanager: Managing MIME Content 19.1.7.1. Content Manager Instances 19.1.8. email: Examples 19.1.9. email.message.Message: Representing an email message using the compat32 API 19.1.10. email.mime: Creating email and MIME objects from scratch 19.1.11. email.header: Internationalized headers 19.1.12. email.charset: Representing character sets 19.1.13. email.encoders: Encoders 19.1.14. email.utils: Miscellaneous utilities 19.1.15. email.iterators: Iterators 19.2. json — JSON encoder and decoder 19.2.1. Basic Usage 19.2.2. Encoders and Decoders 19.2.3. Exceptions 19.2.4. Standard Compliance and Interoperability 19.2.4.1. Character Encodings 19.2.4.2. Infinite and NaN Number Values 19.2.4.3. Repeated Names Within an Object 19.2.4.4. Top-level Non-Object, Non-Array Values 19.2.4.5. Implementation Limitations 19.2.5. Command Line Interface 19.2.5.1. Command line options 19.3. mailcap — Mailcap file handling 19.4. mailbox — Manipulate mailboxes in various formats 19.4.1. Mailbox objects 19.4.1.1. Maildir 19.4.1.2. mbox 19.4.1.3. MH 19.4.1.4. Babyl 19.4.1.5. MMDF 19.4.2. Message objects 19.4.2.1. MaildirMessage 19.4.2.2. mboxMessage 19.4.2.3. MHMessage 19.4.2.4. BabylMessage 19.4.2.5. MMDFMessage 19.4.3. Exceptions 19.4.4. Examples 19.5. mimetypes — Map filenames to MIME types 19.5.1. MimeTypes Objects 19.6. base64 — Base16, Base32, Base64, Base85 Data Encodings 19.7. binhex — Encode and decode binhex4 files 19.7.1. Notes 19.8. binascii — Convert between binary and ASCII 19.9. quopri — Encode and decode MIME quoted-printable data 19.10. uu — Encode and decode uuencode files 20. Structured Markup Processing Tools 20.1. html — HyperText Markup Language support 20.2. html.parser — Simple HTML and XHTML parser 20.2.1. Example HTML Parser Application 20.2.2. HTMLParser Methods 20.2.3. Examples 20.3. html.entities — Definitions of HTML general entities 20.4. XML Processing Modules 20.4.1. XML vulnerabilities 20.4.2. The defusedxml and defusedexpat Packages 20.5. xml.etree.ElementTree — The ElementTree XML API 20.5.1. Tutorial 20.5.1.1. XML tree and elements 20.5.1.2. Parsing XML 20.5.1.3. Pull API for non-blocking parsing 20.5.1.4. Finding interesting elements 20.5.1.5. Modifying an XML File 20.5.1.6. Building XML documents 20.5.1.7. Parsing XML with Namespaces 20.5.1.8. Additional resources 20.5.2. XPath support 20.5.2.1. Example 20.5.2.2. Supported XPath syntax 20.5.3. Reference 20.5.3.1. Functions 20.5.3.2. Element Objects 20.5.3.3. ElementTree Objects 20.5.3.4. QName Objects 20.5.3.5. TreeBuilder Objects 20.5.3.6. XMLParser Objects 20.5.3.7. XMLPullParser Objects 20.5.3.8. Exceptions 20.6. xml.dom — The Document Object Model API 20.6.1. Module Contents 20.6.2. Objects in the DOM 20.6.2.1. DOMImplementation Objects 20.6.2.2. Node Objects 20.6.2.3. NodeList Objects 20.6.2.4. DocumentType Objects 20.6.2.5. Document Objects 20.6.2.6. Element Objects 20.6.2.7. Attr Objects 20.6.2.8. NamedNodeMap Objects 20.6.2.9. Comment Objects 20.6.2.10. Text and CDATASection Objects 20.6.2.11. ProcessingInstruction Objects 20.6.2.12. Exceptions 20.6.3. Conformance 20.6.3.1. Type Mapping 20.6.3.2. Accessor Methods 20.7. xml.dom.minidom — Minimal DOM implementation 20.7.1. DOM Objects 20.7.2. DOM Example 20.7.3. minidom and the DOM standard 20.8. xml.dom.pulldom — Support for building partial DOM trees 20.8.1. DOMEventStream Objects 20.9. xml.sax — Support for SAX2 parsers 20.9.1. SAXException Objects 20.10. xml.sax.handler — Base classes for SAX handlers 20.10.1. ContentHandler Objects 20.10.2. DTDHandler Objects 20.10.3. EntityResolver Objects 20.10.4. ErrorHandler Objects 20.11. xml.sax.saxutils — SAX Utilities 20.12. xml.sax.xmlreader — Interface for XML parsers 20.12.1. XMLReader Objects 20.12.2. IncrementalParser Objects 20.12.3. Locator Objects 20.12.4. InputSource Objects 20.12.5. The Attributes Interface 20.12.6. The AttributesNS Interface 20.13. xml.parsers.expat — Fast XML parsing using Expat 20.13.1. XMLParser Objects 20.13.2. ExpatError Exceptions 20.13.3. Example 20.13.4. Content Model Descriptions 20.13.5. Expat error constants 21. Internet Protocols and Support 21.1. webbrowser — Convenient Web-browser controller 21.1.1. Browser Controller Objects 21.2. cgi — Common Gateway Interface support 21.2.1. Introduction 21.2.2. Using the cgi module 21.2.3. Higher Level Interface 21.2.4. Functions 21.2.5. Caring about security 21.2.6. Installing your CGI script on a Unix system 21.2.7. Testing your CGI script 21.2.8. Debugging CGI scripts 21.2.9. Common problems and solutions 21.3. cgitb — Traceback manager for CGI scripts 21.4. wsgiref — WSGI Utilities and Reference Implementation 21.4.1. wsgiref.util – WSGI environment utilities 21.4.2. wsgiref.headers – WSGI response header tools 21.4.3. wsgiref.simple_server – a simple WSGI HTTP server 21.4.4. wsgiref.validate — WSGI conformance checker 21.4.5. wsgiref.handlers – server/gateway base classes 21.4.6. Examples 21.5. urllib — URL handling modules 21.6. urllib.request — Extensible library for opening URLs 21.6.1. Request Objects 21.6.2. OpenerDirector Objects 21.6.3. BaseHandler Objects 21.6.4. HTTPRedirectHandler Objects 21.6.5. HTTPCookieProcessor Objects 21.6.6. ProxyHandler Objects 21.6.7. HTTPPasswordMgr Objects 21.6.8. HTTPPasswordMgrWithPriorAuth Objects 21.6.9. AbstractBasicAuthHandler Objects 21.6.10. HTTPBasicAuthHandler Objects 21.6.11. ProxyBasicAuthHandler Objects 21.6.12. AbstractDigestAuthHandler Objects 21.6.13. HTTPDigestAuthHandler Objects 21.6.14. ProxyDigestAuthHandler Objects 21.6.15. HTTPHandler Objects 21.6.16. HTTPSHandler Objects 21.6.17. FileHandler Objects 21.6.18. DataHandler Objects 21.6.19. FTPHandler Objects 21.6.20. CacheFTPHandler Objects 21.6.21. UnknownHandler Objects 21.6.22. HTTPErrorProcessor Objects 21.6.23. Examples 21.6.24. Legacy interface 21.6.25. urllib.request Restrictions 21.7. urllib.response — Response classes used by urllib 21.8. urllib.parse — Parse URLs into components 21.8.1. URL Parsing 21.8.2. Parsing ASCII Encoded Bytes 21.8.3. Structured Parse Results 21.8.4. URL Quoting 21.9. urllib.error — Exception classes raised by urllib.request 21.10. urllib.robotparser — Parser for robots.txt 21.11. http — HTTP modules 21.11.1. HTTP status codes 21.12. http.client — HTTP protocol client 21.12.1. HTTPConnection Objects 21.12.2. HTTPResponse Objects 21.12.3. Examples 21.12.4. HTTPMessage Objects 21.13. ftplib — FTP protocol client 21.13.1. FTP Objects 21.13.2. FTP_TLS Objects 21.14. poplib — POP3 protocol client 21.14.1. POP3 Objects 21.14.2. POP3 Example 21.15. imaplib — IMAP4 protocol client 21.15.1. IMAP4 Objects 21.15.2. IMAP4 Example 21.16. nntplib — NNTP protocol client 21.16.1. NNTP Objects 21.16.1.1. Attributes 21.16.1.2. Methods 21.16.2. Utility functions 21.17. smtplib — SMTP protocol client 21.17.1. SMTP Objects 21.17.2. SMTP Example 21.18. smtpd — SMTP Server 21.18.1. SMTPServer Objects 21.18.2. DebuggingServer Objects 21.18.3. PureProxy Objects 21.18.4. MailmanProxy Objects 21.18.5. SMTPChannel Objects 21.19. telnetlib — Telnet client 21.19.1. Telnet Objects 21.19.2. Telnet Example 21.20. uuid — UUID objects according to RFC 4122 21.20.1. Example 21.21. socketserver — A framework for network servers 21.21.1. Server Creation Notes 21.21.2. Server Objects 21.21.3. Request Handler Objects 21.21.4. Examples 21.21.4.1. socketserver.TCPServer Example 21.21.4.2. socketserver.UDPServer Example 21.21.4.3. Asynchronous Mixins 21.22. http.server — HTTP servers 21.23. http.cookies — HTTP state management 21.23.1. Cookie Objects 21.23.2. Morsel Objects 21.23.3. Example 21.24. http.cookiejar — Cookie handling for HTTP clients 21.24.1. CookieJar and FileCookieJar Objects 21.24.2. FileCookieJar subclasses and co-operation with web browsers 21.24.3. CookiePolicy Objects 21.24.4. DefaultCookiePolicy Objects 21.24.5. Cookie Objec

基于MPC+二自由度动力学的车辆轨迹跟踪+横向控制Carsim和Simulink联合仿真（Matlab代码、Simulink仿真实现）

内容概要：本文系统阐述了基于模型预测控制（MPC）与二自由度车辆动力学模型的轨迹跟踪与横向控制方法，通过Carsim与Simulink联合仿真平台实现了Matlab代码与Simulink模型的协同验证。该方法结合MPC算法的滚动时域优化特性与车辆二自由度动力学模型的运动学精度，构建了高精度的路径跟踪控制系统，能够有效提升自动驾驶车辆在复杂工况下的行驶稳定性与轨迹跟随精度。文中详细介绍了控制策略设计、车辆动力学建模、仿真参数配置、联合仿真接口搭建及结果分析全过程，涵盖了状态预测、代价函数构建、约束处理与优化求解等核心环节，适用于智能驾驶中路径规划与跟踪控制系统的研发与验证。; 适合人群：具备车辆动力学、现代控制理论（如最优控制、预测控制）基础知识，熟练掌握Matlab/Simulink与Carsim仿真工具，从事自动驾驶、智能车辆控制算法开发的研究生、科研人员及工程技术人员。; 使用场景及目标：①用于智能网联汽车与无人驾驶系统中横向控制算法的设计与性能验证；②作为MPC在车辆运动控制中应用的教学案例，辅助高校课程实践与科研训练；③支撑高水平学术论文复现、课题申报与工程原型开发。; 阅读建议：建议读者在Carsim与Simulink联合仿真环境下动手复现，重点掌握MPC控制器中预测模型的建立、权重系数调节、约束设定及实时性优化等关键技术，并尝试在不同道路曲率、车速及路面附着条件下进行鲁棒性测试，进一步拓展至非线性MPC或自适应MPC等先进控制策略的研究。